Harness Engineering: Как создавать ИИ-агентов, которые действительно работают

Большинство людей пытаются починить AI-агентов не на том уровне.

Когда агент ошибается, они переписывают промпт. Когда он ошибается снова — добавляют больше инструкций, меняют модель, увеличивают контекстное окно или подключают еще один инструмент.

А потом те же проблемы возвращаются.

Агент забывает важное решение. Использует не тот инструмент. Теряет нить того, что произошло три шага назад. Заявляет, что задача выполнена, даже не проверив результат. Снова и снова пытается выполнить одно и то же действие, пока не закончится бюджет.

Проблема не всегда в модели.

Проблема — в среде вокруг нее.

Эта среда и есть harness (обвязка).

Harness Engineering (инженерия обвязок) — это практика построения системы вокруг модели, которая определяет, что она может видеть, что делать, что запоминать, что считается успехом и что происходит при сбое.

Лучший промпт может улучшить один ответ.

Лучшая обвязка улучшает каждый запуск.

Подписывайтесь на мой Substack, чтобы получать больше практических разборов AI-агентов, автоматизации и продакшен-систем:

substack.com/@lunarresearcher

1. Модель — это не агент

Модель умеет рассуждать, генерировать, сравнивать и выбирать.

Но это не делает ее надежным агентом.

Настоящему агенту нужно еще находить нужный контекст, использовать инструменты, сохранять состояние, соблюдать права доступа, проверять собственную работу и восстанавливаться, когда среда ведет себя не так, как ожидалось.

Модель — это только движок рассуждений.

Обвязка — это всё, что превращает эти рассуждения в реальное выполнение.

1ЗАПРОС ПОЛЬЗОВАТЕЛЯ
2      |
3      v
4+-----------------------------+
5|           ОБВЯЗКА           |
6|                             |
7| контракт      контекст      |
8| инструменты   состояние     |
9| политика      верификация   |
10| трассировки   восстановление|
11+-----------------------------+
12      |
13      v
14    МОДЕЛЬ
15      |
16      v
17РЕАЛЬНАЯ СРЕДА

Поместите ту же модель в чат-бокс — и она будет просто отвечать на вопросы.

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

Модель не изменилась.

Изменилась обвязка.

2. Превращайте каждый запрос в контракт

Естественный язык гибок.

Автономное выполнение — нет.

Запрос вроде:

Улучши процесс онбординга.

отлично работает, когда человек сидит рядом с моделью.

Но как продакшен-инструкция он ужасен.

Прежде чем агент начнет действовать, превратите запрос в ограниченный контракт задачи.

1objective: снизить отток пользователей на этапе онбординга
2
3inputs:
4  - описание продукта
5  - данные аналитики
6  - репозиторий
7
8constraints:
9  - сохранить аутентификацию
10  - не менять схему базы данных
11  - сохранить текущее поведение на мобильных устройствах
12
13deliverable:
14  - готовый к ревью pull request
15
16done_when:
17  - тесты проходят
18  - событие аналитики отправляется корректно
19  - десктопный сценарий проходит ревью
20  - мобильный сценарий проходит ревью
21
22approval_required:
23  - деплой в продакшен

Самое важное здесь — done_when (условия завершения).

Без него агент может решить чуть более простую версию задачи и уверенно заявить, что работа выполнена.

С ним завершение становится измеримым.

Агент не должен спрашивать:

Что мне делать дальше?

Он должен спрашивать:

Какое действие приблизит текущую среду к результату, описанному в контракте?

Это гораздо более сильный цикл.

3. Дайте агенту карту, а не гигантское контекстное окно

Типичная реакция на ошибки агента — дать модели больше контекста.

Больше документации.

Больше истории диалога.

Больше файлов.

Больше вывода инструментов.

В итоге агент получает вообще всё и понимает всё меньше.

Контекст — это не хранилище.

Это бюджет внимания.

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

1КАРТА ПРОЕКТА
2
3правила продукта  -> docs/product/
4архитектура       -> docs/architecture.md
5фронтенд          -> apps/web/
6бэкенд            -> services/api/
7тесты             -> tests/
8команды           -> docs/commands.md
9безопасность      -> docs/security.md

И раскрывайте детали только по мере необходимости.

1ЗАДАЧА
2  |
3  v
4КАРТА ПРОЕКТА
5  |
6  v
7НУЖНАЯ СИСТЕМА
8  |
9  v
10КОНКРЕТНЫЕ ФАЙЛЫ
11  |
12  v
13ЛОКАЛЬНЫЕ ИНСТРУКЦИИ

В исходных материалах это называется прогрессивным раскрытием: обвязка должна подгружать больше информации потому, что этого требует задача, а не просто потому, что эта информация существует.

Цель — не максимальный контекст.

Цель — максимум полезного сигнала.

4. Поставьте шлюз между моделью и её инструментами

Модель с двадцатью инструментами автоматически не становится в двадцать раз способнее.

Возможно, у неё просто появляется двадцать новых способов сломаться.

У каждого инструмента должен быть контракт.

1ИНСТРУМЕНТ: edit_file
2
3ВХОДНЫЕ ДАННЫЕ
4path
5patch
6
7ПРЕДУСЛОВИЯ
8path существует
9path находится внутри рабочей директории
10
11УСПЕХ
12patch применен
13diff возвращен
14
15ОШИБКА
16структурированная ошибка
17никаких частичных перезаписей
18
19РИСК
20обратимо

Тогда путь выполнения выглядит так:

1МОДЕЛЬ ПРЕДЛАГАЕТ
2      |
3      v
4ШЛЮЗ ПРОВЕРЯЕТ
5      |
6      v
7ПОЛИТИКА АВТОРИЗУЕТ
8      |
9      v
10ИНСТРУМЕНТ ВЫПОЛНЯЕТ
11      |
12      v
13ОБВЯЗКА ФИКСИРУЕТ РЕЗУЛЬТАТ

Модель решает, какое действие она хочет совершить.

Обвязка решает, допустимо ли это действие, разрешено ли оно и безопасно ли.

Это разделение становится критически важным, когда инструменты могут отправлять сообщения, изменять продакшен, тратить деньги или удалять данные.

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

Хорошие инструменты уменьшают количество вещей, которые модели приходится угадывать.

5. Вынесите память за пределы диалога

Диалог не должен быть системой учета.

Долгоживущие агенты рано или поздно упираются в лимиты контекста, падают, перезапускаются или передают работу другой сессии.

Если все важные решения существуют только в логе переписки, рабочий процесс крайне хрупок.

Храните устойчивое состояние отдельно.

1{
2  "task_id": "feature_042",
3  "status": "verifying",
4  "current_step": "mobile_check",
5
6  "completed": [
7    "implementation",
8    "unit_tests",
9    "desktop_check"
10  ],
11
12  "decisions": [
13    "reuse existing export endpoint",
14    "preserve current date format"
15  ],
16
17  "artifacts": [
18    "export.csv",
19    "desktop-after.png"
20  ],
21
22  "open_risks": [
23    "mobile toolbar may overflow"
24  ],
25
26  "next_action": "render mobile viewport"
27}

Полезная система разделяет память на четыре категории:

1ФАКТЫ
2стабильные знания
3
4РЕШЕНИЯ
5что было выбрано и почему
6
7СОСТОЯНИЕ
8на каком этапе находится текущий запуск
9
10УРОКИ
11ошибки, которые должны повлиять на будущие запуски

Следующая сессия агента должна наследовать состояние работы, а не сжатый пересказ предыдущего диалога.

6. Сделайте доказательства пропуском к завершению

Слова агента «готово» — не доказательство того, что работа сделана.

Это просто еще один вывод модели.

Обвязке нужны наблюдаемые доказательства.

1УТВЕРЖДЕНИЕ               ДОКАЗАТЕЛЬСТВО
2
3«баг исправлен»           падающий тест теперь проходит
4«страница работает»       браузерный сценарий пройден
5«данные верны»            значения совпадают с источником
6«миграция безопасна»      успешный dry run + откат
7«задача выполнена»        все проверки приемки пройдены

Сначала используйте детерминированные проверки.

1синтаксис
2  |
3  v
4типы
5  |
6  v
7целевые тесты
8  |
9  v
10интеграционные тесты
11  |
12  v
13визуальное / семантическое ревью
14  |
15  v
16подтверждение человеком

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

Используйте модели для суждений.

Используйте детерминированные системы для фактов.

Модель создает артефакт.

Среда создает доказательства об этом артефакте.

Обвязка решает, достаточно ли этих доказательств.

7. Отделите создателя от проверяющего

У саморевью есть еще одна проблема.

Агент, допустивший ошибку, часто переносит те же ложные предпосылки и в этап проверки.

Более сильная архитектура разделяет исполнителя и проверяющего.

1СОЗДАТЕЛЬ
2   |
3   v
4создает кандидата
5   |
6   v
7ПРОВЕРЯЮЩИЙ
8   |
9   +-- сверяет с контрактом
10   +-- ищет упущенные случаи
11   +-- тестирует необоснованные утверждения
12   +-- пытается сломать результат
13   |
14   +------ УСПЕХ ------> ПРИНЯТЬ
15   |
16   +------ ПРОВАЛ ------> ВЕРНУТЬ ДОКАЗАТЕЛЬСТВА

Проверяющий не должен спрашивать:

Выглядит нормально?

Он должен спрашивать:

Что сделало бы этот результат неприемлемым?

Это превращает ревью из поиска подтверждений в попытку опровержения.

Исходные материалы прямо рекомендуют давать процессу верификации собственные критерии отклонения и достаточно независимости, чтобы ставить под сомнение предпосылки, которые привели к первому результату.

8. Вынесите права доступа за пределы модели

Некоторые правила никогда не должны зависеть от того, вспомнит их модель или нет.

1никогда не публиковать без одобрения
2никогда не раскрывать секреты
3никогда не превышать лимит расходов
4никогда не писать за пределами рабочей директории
5никогда не заявлять, что тесты пройдены, если они не запускались

Это не пожелания для промпта.

Это политика.

Простая лестница прав доступа:

1НИЗКИЙ РИСК
2
3чтение
4поиск
5инспекция
6
7-> автоматически
8
9ОБРАТИМОЕ
10
11редактирование рабочей директории
12запуск тестов
13создание черновика
14
15-> автоматически + трассировка
16
17ВНЕШНИЙ ЭФФЕКТ
18
19отправка
20деплой
21покупка
22
23-> требуется одобрение
24
25НЕОБРАТИМОЕ / ЧУВСТВИТЕЛЬНОЕ
26
27удаление данных
28ротация ключей
29глобальная публикация
30
31-> жесткий шлюз или запрещено

Чем серьезнее последствия, тем строже контроль.

Модель может рекомендовать действие.

Обвязка его авторизует.

Инструмент выполняет.

Автономность — это не отсутствие контроля.

Это свобода в рамках установленных границ.

9. Перестаньте слепо повторять попытки

Одна из худших стратегий восстановления:

Что-то пошло не так. Попробуй еще раз.

Если ничего не меняется, система просто платит за воспроизведение той же ошибки.

Сначала сбои нужно классифицировать.

1ТАЙМАУТ ИНСТРУМЕНТА
2-> повторить с экспоненциальной задержкой
3
4НЕВЕРНЫЕ АРГУМЕНТЫ
5-> исправить вызов инструмента
6
7НЕХВАТКА КОНТЕКСТА
8-> получить недостающий источник
9
10ПАДЕНИЕ ТЕСТА
11-> изучить причину сбоя
12
13ДОСТУП ЗАПРЕЩЕН
14-> запросить одобрение
15
16КОНФЛИКТ ТРЕБОВАНИЙ
17-> эскалировать
18
19ПОВТОРЯЮЩИЙСЯ СБОЙ БЕЗ ИЗМЕНЕНИЙ
20-> остановиться

Полезный цикл агента выглядит так:

1НАБЛЮДАТЬ
2   |
3   v
4РЕШАТЬ
5   |
6   v
7ДЕЙСТВОВАТЬ
8   |
9   v
10ИЗМЕРЯТЬ
11   |
12   +---- ПРИНЯТЬ
13   |
14   +---- ИСПРАВИТЬ
15   |
16   +---- ЭСКАЛИРОВАТЬ
17   |
18   +---- ОСТАНОВИТЬ

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

Надежному агенту нужно знать, как продолжать работу.

Но ему также нужно знать, когда очередная попытка уже не имеет смысла.

10. Превращайте повторяющиеся инструкции в инфраструктуру

Допустим, в промпте написано:

Всегда запускай форматтер.

Это правило станет надежнее, если форматтер будет запускаться автоматически.

Допустим, инструкция гласит:

UI-код не должен обращаться к базе данных напрямую.

Это правило станет сильнее, если оформить его как архитектурный тест, который падает при нарушении.

Прогрессия выглядит так:

1ОБЪЯСНЕНИЕ
2      |
3      v
4ЧЕК-ЛИСТ
5      |
6      v
7ШАБЛОН
8      |
9      v
10АВТОМАТИЧЕСКАЯ ПРОВЕРКА
11      |
12      v
13ПРИНУДИТЕЛЬНАЯ ПОЛИТИКА

Промпт должен объяснять логику принятия решений.

Обвязка должна обеспечивать соблюдение инвариантов.

Каждая повторяющаяся ошибка должна спускаться на ступеньку ниже по этой лестнице.

В итоге модели больше не нужно помнить урок.

Среда помнит его за неё.

11. Записывайте ход выполнения

Идеальный финальный артефакт может скрывать ужасный путь выполнения.

Возможно, агент обратился не к тому источнику.

Возможно, он проигнорировал упавшую команду.

Возможно, он дважды выполнил внешнее действие.

Возможно, он потратил в десять раз больше ожидаемого бюджета.

Возможно, он получил правильный ответ по неправильной причине.

Сохраняйте достаточно информации, чтобы восстановить ход событий.

109:14  создан контракт задачи
209:15  загружен architecture.md
309:17  отредактирован checkout.ts
409:18  целевой тест упал
509:21  реализация исправлена
609:22  целевой тест пройден
709:24  интеграционный тест пройден
809:25  деплой заблокирован: требуется одобрение

Полезные трассировки включают источники контекста, вызовы инструментов, изменения состояния, результаты проверок, причины повторных попыток, решения об одобрении, стоимость и задержки.

Смысл не в том, чтобы собирать логи ради развлечения.

Смысл в том, чтобы локализовать сбой.

Если ломается шаг 18, вы должны иметь возможность починить именно шаг 18.

Вам не должно требоваться прогонять весь запуск заново.

12. Выдавайте квитанцию на каждый запуск

Не заставляйте человека читать лог из сорока сообщений.

Соберите результат в короткую квитанцию.

1ЦЕЛЬ
2
3Исправить двойное применение купона.
4
5ИЗМЕНЕНО
6
7валидация чекаута
8регрессионный тест
9
10ПРОВЕРЕНО
11
12lint пройден
13юнит-тесты пройдены
14интеграционный тест пройден
15
16НЕ ПРОВЕРЕНО
17
18продакшен-провайдер платежей
19
20РИСКИ
21
22старый мобильный клиент недоступен
23
24ТРЕБУЕТСЯ ОДОБРЕНИЕ
25
26деплой на staging

Это не краткое изложение того, что, по словам модели, произошло.

Это сводка того, что обвязка может доказать.

Именно это различие делает квитанцию полезной для ревью, передачи дел и будущих сессий агента.

13. Пусть каждый сбой улучшает обвязку

Большинство команд чинят неудачный результат.

Лучший подход — чинить систему, которая допустила сбой.

1НЕХВАТКА КОНТЕКСТА
2-> улучшить карту проекта
3
4НЕ ТОТ ИНСТРУМЕНТ
5-> улучшить маршрутизацию или контракт инструмента
6
7ПЛОХОЙ РЕЗУЛЬТАТ
8-> добавить валидатор
9
10ЗАЦИКЛИВАНИЕ
11-> добавить лимит повторных попыток
12
13НЕБЕЗОПАСНОЕ ДЕЙСТВИЕ
14-> добавить шлюз прав доступа
15
16ПОТЕРЯНО РЕШЕНИЕ
17-> сохранять состояние
18
19НЕИЗВЕСТНЫЙ СБОЙ
20-> улучшить трассировку

Именно здесь инженерия обвязок начинает давать накопительный эффект.

Один исправленный результат помогает одному запуску.

Одна исправленная обвязка улучшает все последующие запуски.

Лучшие системы агентов становятся надежнее, потому что ошибки оставляют после себя инфраструктуру.

14. Начните с минимально полезной обвязки

Чтобы начать, вам не нужна огромная платформа оркестрации.

Стройте слоями.

1УРОВЕНЬ 0
2
3промпт
4модель
5
6УРОВЕНЬ 1
7
8контракт задачи
9карта проекта
10инструменты
11
12УРОВЕНЬ 2
13
14структурированное состояние
15верификация
16ограниченный цикл
17
18УРОВЕНЬ 3
19
20права доступа
21трассировки
22восстановление
23шлюзы с участием человека

Короткой исследовательской задаче может хватить промпта и одного ревью.

Шестичасовой задаче по написанию кода с доступом к файлам, сети и возможностью деплоя нужно гораздо больше.

Добавляйте сложность тогда, когда поверхность отказов этого требует.

А не потому, что архитектура агентов выглядит круто.

Чек-лист Harness Engineering

Прежде чем давать агенту значимую автономию, спросите себя:

1[ ] Определен ли успех до начала выполнения?
2
3[ ] Может ли агент найти нужный контекст,
4    не загружая вообще всё?
5
6[ ] Есть ли у каждого инструмента четкая цель,
7    схема и состояние ошибки?
8
9[ ] Хранятся ли важные решения
10    за пределами диалога?
11
12[ ] Требуются ли доказательства для завершения?
13
14[ ] Защищены ли рискованные действия политикой?
15
16[ ] Есть ли у каждого цикла лимит повторных попыток?
17
18[ ] Может ли запуск продолжиться после прерывания?
19
20[ ] Можете ли вы восстановить каждое важное действие?
21
22[ ] Улучшает ли сбой какое-либо правило, инструмент,
23    тест, карту или право доступа?
24
25[ ] Можно ли откатить итоговое изменение?

Если на несколько вопросов ответ «нет», более мощная модель автоматически не сделает агента надежным.

Она просто сделает сбой быстрее и дороже.

Настоящий сдвиг парадигмы

Prompt engineering спрашивает:

Что я должен сказать модели?

Context engineering спрашивает:

Что модель должна знать прямо сейчас?

Harness engineering спрашивает:

Какая система позволит модели действовать, проверять свою работу, восстанавливаться после сбоев и работать безопасно?

1ПРОМПТ
2-> инструкция
3
4КОНТЕКСТ
5-> рабочая картина
6
7ОБВЯЗКА
8-> операционная среда
9
10ЦИКЛ
11-> локальная корректировка
12
13ГРАФ
14-> координация

Модели будут продолжать меняться.

Долгосрочное преимущество живет вокруг них.

Ваши контракты становятся лучше.

Ваши инструменты становятся лучше.

Ваши тесты становятся лучше.

Ваше состояние становится чище.

Ваши права доступа становятся безопаснее.

Ваша логика восстановления становится умнее.

Ваши сбои превращаются в инфраструктуру.

Именно так способные модели становятся надежными агентами.

Это и есть Harness Engineering.

Если вы дочитали до этого места

Добавьте это руководство в закладки.

Подписывайтесь на меня в X: x.com/0xjmori

Подписывайтесь на мой Substack: substack.com/@lunarresearcher

Отправьте эту статью тому, кто до сих пор пытается лечить любой сбой агента более длинным промптом.