Что такое harness engineering: как сделать AI-агента рабочим инструментом

Harness engineering простыми словами

Harness engineering — это инженерная дисциплина о том, как построить вокруг языковой модели окружение, в котором она надёжно выполняет реальную работу. Слово harness переводится как «упряжь»: модель — сильная, но сама по себе она не знает, куда идти, чем пользоваться и когда остановиться. Харнес направляет эту силу.

Самая короткая формулировка звучит так:

Агент = Модель + Харнес

Модель — это веса и способность рассуждать и писать текст или код. Харнес — всё остальное: системные инструкции и файлы вроде CLAUDE.md или AGENTS.md, набор инструментов (shell, редактирование файлов, MCP-серверы), песочница, в которой агент запускает команды, файлы состояния между сессиями, тесты, линтеры и хуки, которые сообщают агенту об ошибках. Если убрать харнес, останется чат, который умеет только отвечать текстом.

Почему агент «то сеньор, то джун»

Знакомая картина: в одном репозитории агент работает как опытный разработчик, в другом — путается, забывает вчерашние решения и рапортует «готово» про фичу, которая не работает. Первая реакция — сменить модель на более новую. Обычно это не помогает, потому что модель в обоих случаях одна и та же. Разница — в окружении.

Отсюда главный сдвиг мышления, с которого начинается harness engineering: агент не сломан — сломано то, что вокруг него. Агент не может запустить тесты, если у него нет к ним доступа. Он не вспомнит, что уже пробовал, если это нигде не записано. Он не узнает, что фича сломана, если ни одна проверка ему об этом не скажет. Это не «характер» модели, а дефекты конструкции, и их можно системно чинить.

Типичные симптомы плохого харнеса

• Каждая новая сессия начинается с починки окружения: не те зависимости, не запускается база, нет переменных.
• Агент повторяет уже отвергнутые решения, потому что не помнит прошлую сессию.
• Правило прямо написано в инструкциях, но агент его игнорирует.
• «Тесты зелёные» — а фича сломана, потому что тесты проверяли не то.
• Агент берётся за три задачи сразу и ни одну не доводит до конца.

Из чего состоит харнес: пять подсистем

Частая ошибка — считать харнесом один файл с промптом. На деле это пять механизмов, и каждый ломается по-своему.

Инструкции

Инструкции отвечают на вопрос «найдёт ли агент нужное правило». Хороший входной файл — это карта, а не учебник: короткое оглавление с командами проверки и жёсткими ограничениями, а детали — в отдельных документах, которые агент открывает по необходимости. Хорошие инструкции задают инварианты («все SQL-запросы параметризованы»), а не диктуют реализацию построчно.

Инструменты

Агент может проверить только то, к чему у него есть доступ. Если он не может запустить линтер, никакое правило «запускай линтер перед коммитом» не сработает. Инструменты подключают через встроенные возможности агента (чтение и правка файлов, выполнение команд) и через MCP — протокол, по которому агенту дают доступ к базам данных, браузеру, трекерам задач.

Среда

Среда — то, где агент запускает команды. Она должна подниматься одной командой, быть одинаковой от сессии к сессии и ограничивать ущерб от ошибки: песочница без доступа к продакшену, отдельная ветка или рабочая копия, возможность за минуту вернуть всё в исходное состояние.

Состояние

У модели нет памяти между сессиями: всё, что не записано в репозиторий, исчезает вместе с окном контекста. Поэтому цель, сделанное, принятые решения, тупики и следующий шаг должны жить в файлах. Проверка простая: откройте новую сессию, скажите агенту «продолжай» — и посмотрите, начнёт ли он работать или начнёт спрашивать, что делать.

Обратная связь

Петли обратной связи — самая важная подсистема. Без них агент — сам себе единственный судья и честно считает задачу выполненной. Тесты, проверка типов, линтер, хук, который запускается после каждой правки, E2E-сценарий в браузере — всё это возвращает агенту красный сигнал, пока ошибку ещё дёшево исправить.

Харнес — это контур, а не список

Пять подсистем работают как замкнутый контур. Модель получает инструкции, через инструменты действует в среде, вносит изменения в репозиторий, верификация проверяет результат. Красный ответ возвращается к модели на исправление, зелёный — фиксируется в состоянии. Состояние, в свою очередь, обновляет инструкции для следующей сессии.

инструкции → модель → инструменты → среда → изменения
                ↑                              ↓
                └──── красный ── верификация ──┘
                                     ↓ зелёный
                                 состояние → (следующая сессия)

Уберите любую стрелку — и контур размыкается именно в этом месте. Нет верификации — агент не узнает об ошибке. Нет состояния — следующая сессия начнётся с археологии вместо работы. Поэтому вложения в одну подсистему не компенсируют дыру в другой: пятистраничный AGENTS.md не заменит отсутствующие тесты.

Чем harness engineering отличается от промпт- и контекст-инжиниринга

Эти понятия вложены друг в друга, а не конкурируют.

Промпт-инжиниринг — часть подсистемы инструкций. Контекст-инжиниринг охватывает инструкции и состояние: что агент видит в каждый момент. Harness engineering добавляет то, что в окно контекста не помещается вовсе: доступы, песочницу, тесты, хуки, процесс работы. Хорошо написанный промпт не поможет, если агент физически не может запустить тесты.

Зачем нужен харнес: математика длинных задач

Интуитивно кажется, что модель, которая правильно делает 95% шагов, — почти идеальна. Но задача агента состоит из многих шагов, и ошибки накапливаются. Если шаги независимы, вероятность пройти их все без ошибки — произведение вероятностей:

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

На десятом шаге без единой ошибки доходит лишь около 60% прогонов, на пятидесятом — меньше одного из десяти. Улучшить модель до 97% — дорого и не в ваших руках. А вот поймать ошибку на том же шаге, где она случилась, и вернуть её агенту — задача харнеса. Петля обратной связи превращает цепочку «ошибка тянет за собой следующую» в цепочку коротких исправимых шагов.

Пример: один и тот же агент в двух репозиториях

Задача: добавить в платёжный бэкенд на FastAPI скидку по промокоду.

Без харнеса

Агент читает пару файлов, пишет функцию расчёта скидки и юнит-тест, который проверяет эту функцию в изоляции. Тест зелёный, агент пишет «готово». Он не знал, что расчёт итоговой суммы идёт в другом модуле, не мог поднять базу и прогнать сценарий оформления заказа целиком. Через день выясняется, что скидка в корзине не применяется.

С харнесом

В корне лежит AGENTS.md на несколько десятков строк: как поднять окружение, какие команды проверки обязательны, где описана архитектура платежей. Окружение поднимается командой docker compose up -d. В репозитории есть файл плана с критерием готовности: «E2E-сценарий оформления заказа с промокодом проходит». После каждой правки хук запускает линтер и типизацию, перед завершением агент обязан прогнать E2E-тест.

# AGENTS.md (фрагмент)
## Проверка — обязательно перед словом «готово»
make lint        # ruff + mypy
make test        # pytest, юнит и интеграционные
make e2e         # сценарий оформления заказа

## MUST
- Деньги считаются в копейках (int), никогда во float
- Все SQL-запросы параметризованы
- Не трогать миграции, уже применённые в проде

Модель та же. Но теперь агент находит модуль итоговой суммы через карту проекта, E2E-тест падает на первой попытке, агент видит, что скидка не дошла до корзины, исправляет и только после зелёного прогона отчитывается. Разница в результате — целиком заслуга харнеса.

С чего начать

1. Опишите, как агент проверяет свою работу: одна-три команды, которые он обязан запускать. Обратная связь даёт наибольший эффект, начинать стоит с неё.
2. Сделайте среду воспроизводимой: окружение поднимается одной командой, есть способ быстро откатиться.
3. Заведите файл состояния: цель, сделанное, решения и тупики, следующий шаг.
4. Сократите инструкции до карты: команды проверки, жёсткие ограничения, ссылки на подробные документы.
5. Ведите журнал провалов агента: на каждый сбой записывайте, какая подсистема его допустила. Журнал покажет, что чинить дальше.

Полезная практика — оценить каждую из пяти подсистем по шкале от 1 до 5, потратить полчаса на самую слабую и прогнать тот же набор из нескольких типовых задач до и после. Так улучшения харнеса становятся измеримыми, а не делаются «по ощущениям».

Итог

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