Как приручить AI: «harness engineering» на практике

Все говорят: «возьми Claude Code / Cursor / Codex, подключи к проекту, и будет магия». Я тоже так думал. А потом два месяца строил вокруг агента инфраструктуру, и только тогда он начал реально ускорять работу. Это история про harness engineering, подход, о котором мало кто пишет на русском, но который, на мой взгляд, меняет многое.

В декабре 2025-го я впервые запустил Claude Code на реальном проекте. Без CLAUDE.md. Без skills. Без каких-либо инструкций. Просто: «вот репозиторий, вот задача, давай».

Результат был... ну, рабочий. Код генерировался, тесты иногда проходили. Но каждая сессия начиналась с одного и того же: агент не знал, как запустить dev-окружение, не понимал, какой линтер используется, не догадывался, что в проекте есть специфичные конвенции именования. Каждый раз я объяснял одно и то же в чате, и каждый раз он забывал это к следующей сессии.

Нанял стажёра, который каждое утро приходит с чистой памятью. Опытный, способный, но без контекста. И тратил первые 40 минут каждой «смены» на то, чтобы вернуть его в курс дела.

В какой-то момент я прочитал статью Mitchell Hashimoto (создатель Terraform, Vagrant, кто не знает) про его путь с AI-агентами. И там была фраза, которая щёлкнула: если агент совершает ошибку, ты не просто исправляешь результат, а создаёшь условие, при котором эта ошибка больше не повторится. Он назвал это harness engineering.

А потом вышел пост от OpenAI про их внутренний эксперимент с Codex, где вся команда строила продукт руками агентов, а люди только «рулили». И там та же мысль, но в масштабе организации.

Я понял, что последние два месяца занимался ровно этим. Только не знал, что у этого есть название ¯\_(ツ)_/¯

Harness дословно переводится как «упряжь». Метафора грубая, но точная: это всё, что помогает агенту тянуть в нужную сторону и не сваливаться в кювет.

Но тут важно не перепутать. Harness это не «ещё один хороший промпт». Промпт это разовая инструкция. Harness это система. Она включает:

Hashimoto разделяет это на две формы. Первая, implicit prompting: это AGENTS.md (или CLAUDE.md в моём случае) с короткими, конкретными правилами. Не «пиши чистый код», а «запускай npm run lint после каждого изменения в src/». Вторая, настоящие программные инструменты. Скрипты, которые делают конкретную работу, плюс запись в том же CLAUDE.md, что эти скрипты существуют.

OpenAI масштабирует идею дальше. Они отказались от одного большого AGENTS.md, потому что длинные инструкции превращаются в шум. Вместо этого: AGENTS.md как карта-оглавление, а реальное знание лежит в структурированных docs/ внутри репозитория. Ключевая мысль: если агент не может получить знание во время работы, для него этого знания не существует.

Расскажу конкретно, как это выглядело у меня. Последовательность действий и выводов.

Этап 1: CLAUDE.md как спасательный круг

Первое, что я сделал, написал CLAUDE.md. Туда попали базовые вещи: как запустить проект, какие команды использовать, структура директорий. Это убрало примерно треть повторяющихся объяснений. Агент перестал спрашивать «а как запустить тесты?» каждую сессию. Но этого было мало.

Этап 2: Skills и Commands

Потом я начал создавать skills, шаблоны для повторяющихся задач. Написание нового теста, проверка code-style, генерация вспомогательных скриптов. Я писал про это в посте про Skills/Agents/Commands. Каждый skill это не просто промпт, а целый контекст: какие файлы читать, какому стилю следовать, какие ограничения соблюдать.

И вот тут я заметил интересную вещь. Качество результата выросло не потому, что модель стала умнее. Она осталась та же самая. Изменилась среда, в которой она работала.

Этап 3: Subagents и изоляция

Следующий шаг: субагенты. Отдельные контексты для разных задач. Лёгкая модель (Haiku) для рутинных проверок, тяжёлая (Opus) для архитектурных решений. Hooks, которые автоматически форматируют файлы и инжектят git-контекст при старте сессии. По сути, middleware между мной и агентом.

Параллельно я настроил DevContainer, изолированное окружение, где агент мог делать что угодно без риска сломать мою систему. Отдельная большая тема, но суть: я перестал бояться давать агенту полный доступ к терминалу, потому что терминал был в песочнице.

Этап 4: Документация не для людей, а для агента

Это был неочевидный переломный момент. Я всегда вёл документацию проекта. Но она была написана для себя, для человека, который и так понимает контекст. Агент её читал и... ну, как-то интерпретировал. Иногда правильно, иногда нет.

Когда я переписал ключевые файлы так, чтобы они были однозначно понятны машине (конкретные команды, пути, примеры), эффективность сессий скакнула. Не на 10%, а кратно. Вещи, которые я делал руками всю жизнь (запуск линтера, поднятие dev-окружения, прогон тестов), для AI были чёрным ящиком. Стоило описать их явно, и ящик стал прозрачным.

Тут будет спорный тезис, но я в нём уверен.

Если у вас подписка на Claude Code (или любой другой AI-кодер), большая часть этих денег должна идти не на новые фичи. А на подготовку проекта к тому, чтобы AI мог в нём эффективно работать.

Я бы сказал, 60-70% бюджета подписки это инвестиция в tech debt и инфраструктуру. Документация, тесты, линтеры, CI, структурирование кода, cleanup. Звучит скучно? Возможно. Но вот что я заметил: после двух недель «скучной» работы по наведению порядка в проекте, следующие фичи стали внедряться в разы быстрее. Агент перестал блуждать, перестал ломать соседний код, перестал предлагать архитектуру, которая противоречит существующей.

Это, кстати, не новая идея. До эпохи AI нормальные команды тоже тратили часть времени на поддержание здоровья кодовой базы. Просто сейчас у нас появился инструмент, который может делать эту работу быстрее. Но только если проект к этому готов.

Формула простая: AI в первую очередь не для фичей. AI для подготовки продукта к возможностям AI. Парадоксально, но это работает.

Совместный ресёрч с агентом вообще отдельный кайф. Просишь его пройтись по проекту, найти устаревшие зависимости, несогласованные паттерны, мёртвый код. Он находит такое, что ты сам бы не заметил ещё полгода. OpenAI в своей статье описывают то же самое: они запускали регулярные «cleanup-задачи», фоновые PR на рефакторинг, которые постепенно приводили кодовую базу в порядок. Борьба с энтропией, по сути.

Я писал пост про типичные ошибки AI-кодера. Перечитал его через призму harness engineering и вот что понял: почти все эти ошибки это симптомы слабого harness, а не глупости модели.

«Не читает сгенерированный код». Значит нет автоматических проверок. Если бы lint и тесты запускались после каждого изменения (через hooks), плохой код не прошёл бы дальше.

«Расползание скоупа». Значит нет архитектурных ограничений. Если бы структура проекта была зафиксирована с валидацией зависимостей, агент не смог бы «на ходу» зарефачить половину кодовой базы.

«Контекст утекает». Значит сессии слишком длинные и нет механизма передачи контекста между ними. Harness решает это через persistent memory и структурированные docs.

«Слепое доверие модели». Значит нет слоя верификации. Субагент-ревьюер, который проверяет результат основного агента на дешёвой модели, тоже часть harness.

Короче, большинство жалоб на «тупой AI» это жалобы на отсутствие инфраструктуры вокруг него.

Было бы нечестно не сказать, где всё это не работает.

Harness это инвестиция времени. Серьёзная. Настройка skills, написание документации, создание скриптов, это дни/недели работы. Если проект живёт два месяца и умирает, тратить на это время бессмысленно. Harness окупается только на длинной дистанции. Нужно честно ответить себе: буду ли я этот проект развивать ещё год? Два? Если да – инвестируй. Если нет – не морочь голову, работай с голым агентом.

Harness устаревает. OpenAI прямо пишет: длинные инструкции быстро превращаются в шум. CLAUDE.md, который не обновляется, хуже, чем его отсутствие. Он будет направлять агента по старым рельсам, и вы получите код, который соответствует архитектуре полугодовой давности. Это непрерывный процесс, а не разовая настройка.

Модель всё равно может сломать что угодно. Harness снижает вероятность, но не убирает её. Я до сих пор читаю каждый PR, сгенерированный агентом. Просто теперь PR-ы стали меньше и чище, и ревью занимает минуты, а не часы.

Переинжиниринг harness это реальная проблема. Я сам попадал в ловушку: вместо того чтобы писать код, неделю настраивал обвязку. В какой-то момент нужно остановиться и сказать: «ок, достаточно, теперь работаем». Harness это средство, не цель.

Если вы сейчас работаете с AI-кодером без всякой обвязки, вот минимальный набор для старта:

Harness engineering это не модное слово и не очередной фреймворк. Просто здравый смысл, применённый к работе с AI-агентами. Модели будут становиться умнее, но без качественной среды вокруг них даже самая умная модель будет спотыкаться на ровном месте. Вкладывайтесь в инфраструктуру, и она вернёт вам это сторицей.

А как у вас с обвязкой? Используете CLAUDE.md / AGENTS.md, или каждый раз объясняете агенту всё заново? Интересно услышать, кто до чего дошёл.