Fabien Sanglard — автор культового технічного розбору Doom Black Book — виклав на власному сайті свій особистий agent.md: перелік правил, яким він змушує LLM-агентів слідувати під час генерації коду. За кілька днів допис розійшовся Hacker News як готовий шаблон, який кожен може адаптувати під власний CLAUDE.md чи AGENTS.md. Майже паралельно на тому ж форумі активно обговорювали інший текст — пояснення терміна «harness», обв'язки, яка керує циклом дій LLM-агента: доступ до інструментів, пам'ять, цикли перевірки. На перший погляд це дві незалежні теми. Але якщо їх скласти разом, виходить майже вичерпна відповідь на питання, яке зараз турбує кожного, хто будує власного агента на кшталт Claude Code чи Codex: з яких шарів технічно складається робочий агент і чим саме ці шари наповнювати, щоб код на виході був придатний для проду, а не для демо.

Harness: обв'язка, а не мозок

Велика мовна модель сама по собі нічого не «робить» — вона передбачає наступний токен на основі контексту. Дія з'являється лише тоді, коли навколо моделі побудований цикл: отримати задачу → дати моделі доступний контекст і перелік інструментів → виконати той інструмент, який вона обрала → повернути результат назад у контекст → повторити, поки задача не вважається виконаною або не спрацює стоп-умова. Саме цей керуючий цикл і називають harness — обв'язкою, за аналогією з упряжжю, яка перетворює силу коня на керований рух воза: модель дає «силу» (передбачення), а harness перетворює її на послідовність перевірених дій.

За даними earendil.com, harness — не єдиний моноліт, а стос окремих шарів, кожен з яких можна проєктувати й міняти незалежно: шар виклику інструментів (tool calling) з валідацією аргументів; шар пам'яті, який вирішує, що з історії лишити в контексті, а що стиснути чи винести назовні; і шар перевірки — цикл, що дає моделі зворотний зв'язок про власні помилки, замість того щоб сліпо вірити її звіту про виконання. Це пояснення важливе саме тому, що воно знімає з LLM надмірні очікування: агент «розумний» не тому, що модель стала кращою, а тому, що обв'язка навколо неї змушує її звірятися з реальністю на кожному кроці.

Продукти, з якими стикається більшість практиків — Claude Code, Codex CLI, а також десятки саморобних агентів на голому Anthropic чи OpenAI API — це, по суті, різні реалізації одного й того самого harness-патерну з різним ступенем зрілості циклу перевірки. У найпростішому варіанті модель просто генерує код одним пострілом. У складнішому — вона сама запускає тести, читає їхній вивід, і повторює спробу, поки тести не позеленіють. Різниця між цими двома варіантами — це вся різниця між «агент написав щось схоже на код» і «агент здав робочий PR».

Термін прижився не випадково: у робототехніці й reinforcement learning «harness» роками означав тестове середовище, що годує агента спостереженнями і забирає в нього дії, — сама модель поведінки могла лишатися незмінною, а якість системи все одно різко змінювалася залежно від того, наскільки чесно обв'язка симулювала реальність. З агентами на LLM повторюється та сама історія, тільки замість симуляції фізики тепер файлова система, термінал і мережеві виклики. Шар пам'яті в цьому контексті — не просто «історія повідомлень»: коли контекст переповнюється, harness мусить вирішити, що стиснути в короткий підсумок, що винести в окремий файл нотаток, а що взагалі викинути, — і саме тут найчастіше губляться інструкції, задані на самому початку сесії, включно з правилами з agent.md.

Друга половина рецепта: чим наповнити обв'язку

Harness сам по собі — порожня труба. Він однаково сумлінно виконає і добре сформульований план, і безглуздий. Питання «що саме лити в цю трубу» — окремий шар роботи, і саме на нього відповідає другий матеріал, що розійшовся Hacker News тими ж днями.

За даними fabiensanglard.net, Санглар оприлюднив не абстрактний маніфест, а робочий файл, який він реально підкладає під кожен запуск агента. Механіка тут та сама, що стоїть за CLAUDE.md у Claude Code чи AGENTS.md у Codex і сумісних інструментах: текстовий файл у корені репозиторію, який harness автоматично підвантажує в контекст на старті сесії, — так розробнику не доводиться щоразу вручну повторювати одні й ті самі інструкції в чаті.

Практика таких файлів, що встигла скластися в спільноті й до якої вписується допис Санглара, тримається на кількох повторюваних принципах:

Жоден із цих пунктів не є відкриттям окремо взятим — кожен уже зустрічався в тій чи іншій формі в конвенціях OpenAI щодо AGENTS.md або в документації Anthropic щодо CLAUDE.md. Цінність публікації Санглара — не в новизні правил, а в тому, що це перевірений роками особистого використання документ конкретної людини, а не корпоративний шаблон «зі стелі». Для практика це різниця між теорією і чужим робочим рецептом.

Де ці два матеріали стикаються — і де один без іншого не працює

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

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

Три сценарії для тих, хто будує

Перший сценарій — соло-розробник, що пише власного агента поверх голого Anthropic чи OpenAI API, без готового Claude Code чи Codex CLI. Йому harness доведеться зібрати самому, і розбір з earendil.com тут корисний буквально як чекліст: схема інструментів з валідацією аргументів окремо від бізнес-логіки, явний стоп-критерій циклу (інакше агент або зупиниться зарано, або зациклиться), і мінімум один канал зворотного зв'язку від реального світу — бодай найпростіший «прогнати команду й повернути stdout/stderr у контекст». Без цього останнього пункту будь-який agent.md, який туди підкласти, залишиться декларацією намірів.

Другий сценарій — команда, яка вже працює в Claude Code або Codex і в принципі harness не будує, бо він уже є в продукті. Тут головна робота — не інженерна, а редакторська: написати або переписати CLAUDE.md/AGENTS.md так, щоб він реально відповідав на повторювані скарги «агент зробив зайве» чи «агент видав код, що не компілюється». Файл Санглара тут — не готовий рецепт для копіпасту, а зразок структури й тону, який варто адаптувати під конкретний стек і конкретні больові точки команди, а не переносити один в один.

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

Висновок редакції AiiN

Те, що обидва тексти одночасно вистрілили на Hacker News, — не збіг, а симптом стадії, на якій зараз перебуває індустрія агентів: базова спроможність моделей уже достатня для більшості задач, а вузьким місцем стала інженерія навколо моделі. Рік тому обговорення концентрувалися на тому, яка модель розумніша; зараз — на тому, як побудувати цикл, у якому будь-яка достатньо сильна модель перестає халтурити.

На горизонті 6–12 місяців ми в AiiN очікуємо два паралельні процеси. По-перше, подальшу консолідацію навколо спільних конвенцій файлів-інструкцій — те, що зараз існує як CLAUDE.md, AGENTS.md і десяток саморобних варіантів, тяжітиме до формату, який читають кілька інструментів одночасно, а не лише той, під який файл писався. По-друге, сам harness перестане бути точкою диференціації: базові SDK для агентів (на кшталт Claude Agent SDK чи аналогічних рішень від OpenAI) заберуть на себе більшість типової інженерії циклу, і перевага компаній та окремих розробників переміститься саме туди, де зараз стоїть допис Санглара, — у якість і специфічність правил, якими наповнюють цей цикл, та в те, наскільки жорстко команда змушує harness верифікувати результат, а не вірити агенту на слово.

Є й зворотний бік, про який варто говорити чесно: файли-інструкції мають тенденцію розбухати. Кожна нова скарга на поведінку агента спокушає дописати ще одне правило, і за кілька місяців agent.md чи CLAUDE.md перетворюється на простирадло, яке сама модель вже не в змозі втримати в увазі поруч із рештою контексту, — а це саме той провал пам'яті, про який пише earendil.com. Практичний висновок для будівельників агентів на наступний рік простий: цінність файла-інструкції вимірюється не кількістю правил у ньому, а тим, скільки з них harness реально здатен перевірити автоматично. Решта — це не інструкції, а побажання в порожнечу. Хто це зрозуміє раніше за конкурентів, витрачатиме менше часу на розбір коду, який лише «виглядав готовим».