Harness Engineering: Як створити AI-агентів, які реально працюють

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

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

А потім ті самі проблеми повертаються.

Агент забуває важливе рішення. Використовує не той інструмент. Губить нитку того, що сталося три кроки тому. Заявляє, що завдання виконано, навіть не перевіривши результат. Повторює одну й ту саму невдалу дію, поки не вичерпається бюджет.

Проблема не завжди в моделі.

Проблема — у середовищі навколо неї.

Це середовище і є harness (обв'язка).

Harness Engineering — це практика побудови системи навколо моделі, яка визначає, що вона може бачити, що робити, що пам'ятати, що вважається успіхом і що відбувається, коли щось іде не так.

Кращий промпт може покращити одну відповідь.

Кращий harness покращує кожен запуск.

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

substack.com/@lunarresearcher

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

Модель може міркувати, генерувати, порівнювати й обирати.

Але це не робить її надійним агентом.

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

Модель — це лише рушій для міркувань.

Harness — це все те, що перетворює ці міркування на реальне виконання.

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

Помістіть ту саму модель у чат-вікно — і вона відповідатиме на запитання.

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

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

Змінився harness.

2. Перетворюйте кожен запит на контракт

Природна мова гнучка.

Автономне виконання — ні.

Запит на кшталт:

Покращ онбординг.

цілком нормальний, якщо людина сидить поруч із моделлю.

Але як продакшн-інструкція він жахливий.

Перш ніж агент почне діяти, перетворіть запит на обмежений контракт завдання.

1objective: зменшити відсів на етапі онбордингу
2
3inputs:
4  - опис продукту
5  - дані аналітики
6  - репозиторій
7
8constraints:
9  - зберегти автентифікацію
10  - не змінювати схему бази даних
11  - зберегти поточну поведінку на мобільних пристроях
12
13deliverable:
14  - пул-реквест, готовий до ревью
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ЛОКАЛЬНІ ІНСТРУКЦІЇ

У вихідному матеріалі це називається прогресивним розкриттям: harness має завантажувати більше інформації тому, що цього вимагає завдання, а не просто тому, що ця інформація існує.

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

Мета — максимальний корисний сигнал.

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
13HARNESS ФІКСУЄ РЕЗУЛЬТАТ

Модель вирішує, яку дію вона хоче виконати.

Harness вирішує, чи є ця дія валідною, дозволеною та безпечною.

Ця різниця стає критичною, коли інструменти можуть надсилати повідомлення, змінювати продакшн, витрачати гроші або видаляти дані.

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

Якісні інструменти зменшують кількість речей, які моделі доводиться вгадувати.

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. Зробіть докази умовою завершення

Те, що агент сказав «готово», не означає, що роботу виконано.

Це просто ще один вивід моделі.

Harness потребує спостережуваних доказів.

1ТВЕРДЖЕННЯ                ДОКАЗ
2
3"баг виправлено"          тест, що падав, тепер проходить
4
5"сторінка працює"         браузерний флоу завершено
6
7"дані коректні"           значення збігаються з джерелом
8
9"міграція безпечна"       dry run + rollback пройшли успішно
10
11"завдання виконано"       всі acceptance-перевірки пройдено

Спочатку використовуйте детерміновані перевірки.

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

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

Використовуйте моделі для суджень.

Використовуйте детерміновані системи для фактів.

Модель створює артефакт.

Середовище створює докази щодо цього артефакту.

Harness вирішує, чи достатньо цих доказів.

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-> жорсткий бар'єр або заборона

Що серйозніші наслідки, то суворіший контроль.

Модель може рекомендувати дію.

Harness її авторизує.

Інструмент виконує.

Автономність — це не відсутність контролю.

Це свобода в межах встановлених рамок.

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ПРИМУСОВА ПОЛІТИКА

Промпт має пояснювати логіку суджень.

Harness має забезпечувати дотримання інваріантів.

Кожна повторювана помилка має просуватися трохи нижче цією драбиною.

Зрештою моделі більше не потрібно запам'ятовувати цей урок.

Середовище пам'ятає його замість неї.

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

Це не переказ того, що, на думку моделі, відбулося.

Це зведення того, що harness може довести.

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

13. Нехай кожна помилка покращує harness

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

Кращий підхід — виправити систему, яка допустила цю помилку.

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

Саме тут Harness Engineering починає давати кумулятивний ефект.

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

Один виправлений harness покращує кожен наступний запуск.

Найкращі системи з агентами стають надійнішими, бо помилки залишають після себе інфраструктуру.

14. Починайте з найменшого корисного harness

Для старту вам не потрібна величезна платформа оркестрації.

Будуйте пошарово.

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
7HARNESS
8-> операційне середовище
9
10ЦИКЛ
11-> локальна корекція
12
13ГРАФ
14-> координація

Моделі й надалі змінюватимуться.

Стійка перевага будується навколо них.

Ваші контракти стають кращими.

Ваші інструменти стають кращими.

Ваші тести стають кращими.

Ваш стан стає чистішим.

Ваші дозволи стають безпечнішими.

Ваша логіка відновлення стає розумнішою.

Ваші помилки перетворюються на інфраструктуру.

Ось так здібні моделі стають надійними агентами.

Ось що таке Harness Engineering.

Якщо ви дочитали до цього місця

Збережіть цей гайд у закладки.

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

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

Надішліть цю статтю тому, хто досі намагається виправити кожну помилку агента довшим промптом.