中文版 →

Приклади коду: code/ Практичний проєкт: Проєкт 01. Тільки промпт проти підходу «правила насамперед»: наскільки велика різниця від harness

Лекція 01. Сильна модель — ще не гарантія надійного виконання

Наприкінці 2025 року найсильніші агенти для написання коду на SWE-bench Verified досягають приблизно 50–60% успішних проходжень. На перший погляд цифра здається непоганою — але не поспішайте радіти. Це ретельно відібрані задачі з чіткими описами і готовими тестами. Дайте агенту ваші повсякденні вимоги — розмиті специфікації, відсутні тести, неявні бізнес-правила, розкидані по всьому коду, — і відсоток успіху впаде ще нижче. Ви передаєте задачу з повною впевненістю, агент працює 20 хвилин і повідомляє «все зроблено», а ви дивитесь на код: функціонал додано, але тести зламані, баг виправлено, але з'явилися нові, та й взагалі — це не те, про що ви просили.

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

Один кінь, дві долі

Anthropic провела контрольований експеримент, який ідеально ілюструє цю думку. Один і той самий промпт («збудуй 2D-редактор ретро-ігор»), одна й та сама модель (Opus 4.5), два запуски. Перший запуск: без підтримки — 20 хвилин, $9, основний функціонал гри не працював. Другий запуск: повноцінний harness — архітектура з трьох агентів (планувальник, генератор, оцінювач) — 6 годин, $200, гра повністю готова до гри.

Модель не змінювали. Opus 4.5 залишався Opus 4.5. Змінилося спорядження.

Стаття OpenAI про harness engineering 2025 року висловлюється ще прямолінійніше. Там сказано, що Codex у добре підготовленому репозиторії переходить від «ненадійного» прямо до «надійного». Зверніть увагу на формулювання — не «трохи кращий», а якісний стрибок. Harness тут означає всю інженерну інфраструктуру поза вагами моделі.

Де агенти насправді застрягають

Конкретні сценарії збоїв зводяться лише до кількох типових ситуацій:

• Розмиті вимоги — агент змушений вгадувати. «Додай функцію пошуку» — це речення майже нічого не означає. Пошук чого? Повнотекстовий чи структурований? Чи потрібна пагінація? Підсвічування? Ви не уточнили — агент вгадує. Правильне вгадування — це удача; неправильне — переробка, яка коштує в рази дорожче за конкретизацію на старті.
• Неявні конвенції, не зафіксовані в жодному документі, — агент не може їх дотримуватися. Уся команда використовує новий синтаксис SQLAlchemy 2.0, а агент за замовчуванням пише код 1.x. Усі API-ендпоінти мають проходити через автентифікацію OAuth 2.0, але це правило існує лише у вашій голові та в повідомленні Slack тримісячної давнини. Агент не має жодного уявлення про це — не тому що не хоче дотримуватися правил, а тому що він їх просто ніколи не бачив.
• Неповне налаштування середовища — агент витрачає сили на виправлення оточення. Незавершений dev-сетап, відсутні залежності, невірні версії інструментів — агент спалює дорогоцінне контекстне вікно на помилки pip install і конфлікти версій Node замість того, щоб виконувати реальну роботу.
• Відсутність методів верифікації — агент вважає задачу завершеною, коли йому так здається. Немає тестів, немає лінтера чи верифікаційних команд, про які агенту не повідомили. Агент пише код, перечитує його, вирішує, що все виглядає нормально, і оголошує про завершення. Anthropic також зафіксувала цікавий феномен: коли агенти відчувають, що контекстне вікно закінчується, вони поспішають із завершенням, пропускають кроки верифікації та обирають просте рішення замість оптимального. Це явище називають «контекстною тривогою».
• Втрата стану між сесіями — кожна нова сесія починається з нуля. Усі відкриття попередньої сесії зникають. Кожна нова сесія змушена заново досліджувати структуру проєкту і заново розуміти організацію коду. Агенти без збереження стану демонструють різке зростання відсотка відмов на задачах, що перевищують 30 хвилин.

Ключова термінологія

З огляду на описані вище сценарії ці концепції вже не є просто жаргоном:

• Capability Gap (Розрив у можливостях): Величезна прірва між продуктивністю моделі на бенчмарках і продуктивністю на реальних задачах. 50–60% на SWE-bench Verified означає, що майже половина реальних проблем залишається невирішеною.
• Harness: Все, що знаходиться поза моделлю — інструкції, інструменти, середовище, управління станом, зворотний зв'язок для верифікації. Якщо це не ваги моделі — це harness. Те, що ми називали «спорядженням».
• Harness-Induced Failure (Збій, спричинений harness): Модель має достатні можливості, але середовище виконання має структурні дефекти. Контрольований експеримент Anthropic вже довів це.
• Verification Gap (Розрив верифікації): Розрив між впевненістю агента у своєму результаті та реальною коректністю. Агент каже «я готовий», коли насправді ні — це найпоширеніший сценарій збою.
• Diagnostic Loop (Діагностичний цикл): Виконати — зафіксувати збій — встановити, який шар harness його спричинив — виправити цей шар — виконати знову. Це основна методологія harness engineering.
• Definition of Done (Визначення завершеності): Набір умов, перевірних командою — тести проходять, лінтер чистий, перевірка типів пройдена. Без явного визначення завершеності агент вигадає власне.

Коли щось іде не так — спочатку перевіряйте harness

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

Як це виглядає на практиці? Відносьте кожен збій до конкретного шару. Не кажіть просто «модель недостатньо хороша». Запитайте себе: задача була незрозумілою? Контексту не вистачало? Методів верифікації не було? Зіставляйте кожен збій з одним із п'яти захисних шарів: специфікація задачі, надання контексту, середовище виконання, зворотний зв'язок для верифікації, управління станом. Виробіть цю звичку — і ви побачите, що фраза «модель недостатньо хороша» все рідше з'являтиметься у ваших нотатках.

Потім пишіть явне Визначення завершеності для кожної задачі. Не кажіть «додай функцію пошуку». Деталізуйте:

Критерії завершення:
- Новий ендпоінт GET /api/search?q=xxx
- Підтримує пагінацію, за замовчуванням 20 елементів
- Результати містять підсвічені фрагменти
- Весь новий код проходить pytest
- Перевірка типів пройдена (mypy --strict)

Розмістіть файл AGENTS.md у корені репозиторію — він повідомить агенту про технологічний стек проєкту, архітектурні конвенції та верифікаційні команди. Це перший крок у harness engineering і той, що дає найвищу віддачу від вкладень. Один файл AGENTS.md може бути ефективнішим за перехід на дорожчу модель — і це не жарт.

Далі будуйте діагностичний цикл. Не сприймайте збої як «модель знову тупить». Сприймайте їх як сигнали про те, що ваш harness виявив дефект. При кожному збої визначайте шар, виправляйте його — і більше ніколи не провалюйтеся на цьому місці. Після кількох ітерацій harness стає міцнішим, а продуктивність агента стабілізується. Достатньо простого журналу — для кожної задачі фіксуйте: успіх чи збій, і який шар спричинив збій. Після кількох раундів ви побачите, який шар є вузьким місцем, і зможете зосередити зусилля саме там.

Експеримент з мільйоном рядків

У 2025 році троє інженерів OpenAI розпочали експеримент. Правила були прості: вони самі не пишуть код — тільки Codex. Починаючи з порожнього git-репозиторію, через п'ять місяців у репозиторії було приблизно мільйон рядків коду. Логіка застосунку, інфраструктура, інструментарій, документація — все згенеровано агентом. Троє інженерів відкрили загалом 1500 PR, в середньому 3,5 на людину на день.

Перші кроки виявилися напрочуд повільними. Codex був не поганий — він просто не мав інструментів і структур, достатньо повних для досягнення цілей високого рівня. Троє інженерів поступово виявили закономірність: розбивайте великі цілі на дрібні будівельні блоки — проектування, код, рев'ю, тести — давайте агенту складати їх один за одним, а потім використовуйте ці блоки для компонування складніших задач. Щоразу, коли щось ішло не так, проблема майже ніколи не була «недостатнє старання». Завжди: «чого агенту ще не вистачає, і чи можна надати цю відсутню можливість у спосіб, зрозумілий і придатний до виконання?»

Цей експеримент безпосередньо доводить головну тезу лекції: та сама модель дає принципово різний результат у голому середовищі та в середовищі з повноцінним harness. Модель не змінилася. Змінилося середовище.

Джерело: OpenAI: Harness engineering: leveraging Codex in an agent-first world

Більш приземлений приклад

Одна команда використовувала Claude Sonnet для додавання нових API-ендпоінтів до середнього Python-веб-застосунку (FastAPI + PostgreSQL + Redis, ~15 000 рядків коду).

Спочатку вони дали лише одне речення: «додай ендпоінти налаштувань користувача під /api/v2/users». Результат? Агент витратив 40% контекстного вікна на дослідження структури репозиторію, написав код, що виглядав розумно, але не відповідав паттернам обробки помилок у проєкті, використав старий синтаксис SQLAlchemy та оголосив про завершення, коли в ендпоінті були runtime-помилки. Наступна сесія мала заново виконати всю розвідку.

Пізніше вони додали AGENTS.md (з описом архітектури проєкту та версій технологічного стека), явні верифікаційні команди (pytest tests/api/v2/ && python -m mypy src/) та записи про архітектурні рішення. Та сама модель успішно виконала завдання в усіх трьох незалежних запусках, з ефективністю використання контексту приблизно на 60% вищою.

Модель не змінювали. Змінили harness.

Ключові висновки

• Можливості моделі та надійність виконання — це дві різні речі. Навіть породистий кінь потребує гарного спорядження.
• Коли щось іде не так — спочатку перевіряйте harness, потім модель. Заміна моделі — найдорожчий варіант, і найчастіше проблема взагалі не в ній.
• Кожен збій — це сигнал: у вашому harness є структурний дефект. Знайдіть його й виправте.
• Не кажіть просто «модель недостатньо хороша». Систематично проходьте п'ять шарів: задача нечітко визначена, недостатньо контексту, неправильно налаштоване середовище, відсутня верифікація, втрата стану між сесіями. Дев'ять разів із десяти проблема знаходиться в одному з цих шарів.
• Один файл AGENTS.md може бути ефективнішим за перехід на дорожчу модель.

Додаткова література

• OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World
• Anthropic: Effective Harnesses for Long-Running Agents
• HumanLayer: Skill Issue — Harness Engineering for Coding Agents
• SWE-bench Leaderboard
• Thoughtworks Technology Radar: Harness Engineering

Вправи

1. Порівняльний експеримент: Візьміть кодову базу, яку ви добре знаєте, і нетривіальну задачу на модифікацію. Спочатку запустіть агент без підтримки harness і зафіксуйте збої. Потім додайте AGENTS.md та явні верифікаційні команди і запустіть знову з тим самим агентом. Порівняйте два результати, відносячи кожен збій до одного з п'яти захисних шарів.

2. Вимірювання розриву верифікації: Виберіть 5 задач на написання коду. Після кожної задачі фіксуйте: чи оголошує агент про завершення, — а потім перевіряйте реальну коректність незалежними тестами. Обчисліть частку випадків, коли агент вважає задачу виконаною, а насправді ні — це і є ваш розрив верифікації. Потім подумайте: які верифікаційні команди зменшили б цю частку?

3. Практика діагностичного циклу: Знайдіть задачу, на якій агент регулярно зазнає збоїв у вашому проєкті. Запустіть один раз, зафіксуйте збій. Віднесіть його до одного з п'яти шарів. Виправте цей шар. Запустіть знову. Повторіть три-п'ять раундів, щоразу фіксуючи покращення.