Основи обв'язки — рівні та система записів

Складність: [COMPLEX]

Час на виконання: ~50 хвилин

Передумови: Модуль 2.4 Динамічна оркестрація контексту або еквівалентний досвід керування контекстом на рівні сесії, рішень щодо бюджету виводу інструментів і виявлення деградації контексту в багатокрокових робочих процесах агентів.

Що ви зможете зробити

Після цього модуля ви зможете:

Спроєктувати трирівневу класифікацію обв’язки для команди з кількома репозиторіями та обґрунтувати, чому кожне правило належить до призначеного рівня, а не на рівень вище чи нижче.
Оцінити, чи працює поточний режим інструкцій команди як система записів або як некерована поверхня порад, використовуючи конкретні докази з макета репозиторію та слідів відмов агента.
Порівняти AGENTS.md і CLAUDE.md як контрольні артефакти з інструкційними файлами рівня промпту, називаючи операційні гарантії, які надають контрольні артефакти, а файли промптів — ні.
Діагностувати відмову через семантичну неоднозначність у циклі завдань агента та перепроєктувати заякорений шлях так, щоб перші 30 секунд запуску агента приводили до детермінованого джерела політики.

Чому цей модуль важливий

Гіпотетичний сценарій: платформна команда з дванадцяти інженерів працює в шести репозиторіях зі спільним агентним шлюзом. Кожен репозиторій має файл AGENTS.md, файл CLAUDE.md, директорію docs і зростаючу колекцію шаблонів промптів, які окремі інженери написали після невдалих агентних сесій. Команда оцінює, що витрачає шість інженеро-годин на тиждень на налагодження поведінки агента, яка виглядає правильною в перші п’ять кроків, а потім дрейфує — агент редагує згенеровані файли, ігнорує нещодавно додане обмеження гілок або застосовує застарілий чекліст рецензування зі старого шаблону промпту. Ніхто не заперечує, що правила десь існують. Проблема в тому, що жоден артефакт не може відповісти на питання «яке правило регулює цей клас завдань і що відбувається, коли правило порушується?»

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

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

Трирівнева модель обв’язки в дії

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

Коли агент запускається у свіжу сесію, рівень середовища виконання платформи вже активний до того, як будь-який файл репозиторію буде завантажено. Сімейство моделей агента, режим пісочниці, дозволи на доступ до мережі та межа таймауту встановлюються оператором шлюзу, а не будь-якою інструкцією в репозиторії. Агент не може прочитати правило платформи, вирішити, що воно незручне, і проігнорувати його, оскільки правило не виражене як проза — це межа можливостей, яку забезпечує середовище виконання. Якщо режим пісочниці — лише читання, жодна інструкція AGENTS.md не може надати доступ на запис. Якщо мережа обмежена брандмауером лише до внутрішніх сервісів, жоден файл політики не може відкрити вихідне з’єднання. Правила платформи — це єдиний рівень, де відповідність гарантується середовищем виконання, а не стверджується репозиторієм.

Дорадчі правила проєкту працюють інакше. Вони живуть у репозиторії як доступні для виявлення файли, і кожна агентна сесія може їх читати, але коли сесія порушує дорадче правило, ніщо механічне не зупиняє робочий процес. Агент рухається далі, коміт потрапляє до репозиторію, PR відкривається, і порушення стає видимим лише тоді, коли людський рецензент помічає його під час рецензування коду. Дорадчі правила успішні, коли вони зменшують когнітивне навантаження повторюваних стильових рішень — агенту не потрібно вирішувати, чи використовувати snake_case чи camelCase, оскільки дорадчий документ уже відповів на питання. Вони зазнають невдачі, коли команда покладається на дорадче правило для запобігання класу помилок, який вимагає механічного примусу, наприклад, витоку секретів або захисту гілок, а потім ставиться до агента так, ніби він порушив жорстке обмеження, хоча жодного обмеження не існувало.

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

Діагностичний шаблон для аудиту наявного репозиторію полягає в оцінці кожного правила за трьома питаннями: де це правило записано, що відбувається, коли його порушують, і хто відповідальний за виявлення порушення. Правило, записане у файлі CONTRIBUTING.md без примусового виконання в CI і без призначеного власника для виявлення порушень, працює на неоднозначному дорадчому рівні — воно коштувало часу на написання, але не дає жодної з переваг ані дорадчого рівня (низькі накладні витрати), ані примусового (механічна визначеність). Правило, яке забезпечується воротами CI, що запускаються лише для pull requests проти main, але не для кожного push, залишає прогалину, яку агент, що працює на довготривалій функціональній гілці, може випадково використати.

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

Пауза та передбачення: Ваша команда підтримує правило, що кожен pull request повинен містити тест для зміненої поведінки. Сьогодні це правило живе у файлі CONTRIBUTING.md, і пайплайн CI його не забезпечує. Три з останніх десяти злитих PR пропустили тести, і команда витрачає четвергові післяобіди на написання ретроактивного покриття. Перш ніж читати далі, вирішіть: це правило належить до дорадчого чи примусового рівня, і який один скрипт ви б додали, щоб здійснити перехід?

Репозиторій як система записів: механізми примусового виконання

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

Операційне питання не в тому, «де має жити політика?», а в тому, «як система доводить, що агент прочитав правильну політику перед тим, як діяти?» Три механізми відповідають на це питання послідовно. По-перше, граф вказівників AGENTS.md надає єдиний шлях входу до кожного файлу політики. Коли агент слідує за вказівником від AGENTS.md до docs/harness/policy/deploy.md, обхід створює аудиторський слід, який рецензент може відтворити: агент прочитав AGENTS.md, співставив клас завдань розгортання з його файлом політики та завантажив файл політики перед виконанням команд розгортання. Ця гарантія — на рівні файлової системи, не природної мови — агент або відкрив файл за оголошеним шляхом, або ні, і журнал сесії фіксує, який шлях було визначено.

По-друге, скрипти примусового виконання замикають цикл між декларацією політики та верифікацією політики. Файл політики, який каже «кожне розгортання повинно оголошувати цільове середовище», є дорадчою заявою. Та сама політика зі скриптом deploy-guard.sh, який шукає у повідомленні коміту env: staging або env: production і виходить з ненульовим кодом, коли жодного не знайдено, є механізмом примусового виконання. Скрипт перетворює політику з документа, який агент міг би прочитати, на ворота, які агент повинен пройти, а вивід успіх/невдача стає частиною журналу сесії, який рецензент може перевірити.

По-третє, хуки перед комітом і ворота CI поширюють примусове виконання на межу інтеграції коду. Політика, яка живе лише у файлі markdown, може бути обійдена агентом, який ніколи не читає файл, або людиною, яка редагує безпосередньо на платформі. Політика, яка забезпечується хуком перед комітом, блокує коміт до того, як він потрапить до історії репозиторію, а політика, яка забезпечується воротами CI, блокує злиття до того, як воно досягне захищеної гілки. Ці механізми не є доповненнями до дисципліни системи записів — вони є тим, що перетворює дисципліну з конвенції документації на операційну гарантію.

Дисципліна SoR також змінює те, як команди оновлюють політику. У моделі до SoR зміни політики поширюються через повідомлення в чаті, редагування вікі та оголошення на стендапах, досягаючи різних членів команди в різний час і залишаючи агентів без єдиного джерела для звернення при запуску. У моделі SoR зміни політики потрапляють через pull requests до репозиторію, що означає, що вони рецензуються, версіонуються, можуть бути відкочені та автоматично виявляються кожною наступною агентною сесією. Накладні витрати вищі для малих змін — відкриття PR займає більше часу, ніж надсилання повідомлення — але виграш у надійності накопичується між сесіями, оскільки кожна сесія читає ту саму політику з того самого канонічного шляху, а не відновлює її з розрізнених, суперечливих або застарілих сигналів.

Цей принцип належить до рівня обв’язки, а не до рівня контексту, оскільки це питання примусового виконання. Модуль 2.2 навчив вас структурувати репозиторій так, щоб агенти могли швидко виявляти контекст і уникати застарілих настанов. Це стосувалося формату та можливості виявлення поверхонь інструкцій. Концепція системи записів, яка викладається тут, стосується авторитетності цих поверхонь: коли агент завантажує політику з репозиторію, система тепер може стверджувати, що ця політика є канонічною версією, що жоден інший файл політики їй не суперечить, і що будь-яке відхилення від цієї політики є порушенням, яке може виявити примусовий рівень. SoR — це те, що перетворює добре структурований репозиторій на керований репозиторій.

Пауза та передбачення: Чекліст розгортання вашої команди живе в трьох місцях: на сторінці Notion, у закріпленому повідомленні Slack і в docs/runbooks/deploy.md. Сторінка Notion востаннє оновлювалася в березні, повідомлення Slack посилається на старішу версію сторінки Notion, а docs/runbooks/deploy.md оновлювався минулого тижня, але ніхто про це не оголосив. Агент збирається виконати розгортання. Якщо агент виявить усі три джерела, якому з них він повинен довіряти, і яка одна зміна в репозиторії запобігла б повторенню цієї неоднозначності?

AGENTS.md і CLAUDE.md як контрольні артефакти

Модуль 2.2 представив AGENTS.md і CLAUDE.md як парні контрактні рівні для інженерії репозиторіїв. Він пояснив, як AGENTS.md слугує змістом і точкою входу, тоді як CLAUDE.md надає обмежені поведінкові правила. Це формулювання правильне для контекстної інженерії, де мета — допомогти агенту виявити та завантажити правильну поверхню інструкцій. Рівень обв’язки додає друге, більш вагоме питання: які операційні гарантії надають ці файли, яких не може надати звичайний файл промпту?

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

Розглянемо конкретну різницю. Прозовий інструкційний файл може сказати: «Завжди запускайте тести перед відкриттям PR і ніколи не комітьте напряму в main.» Агент читає цю інструкцію, розуміє її та може дотримуватися її більшість часу. Але коли завдання термінове, коли контекстне вікно заповнене або коли агент стикається з незнайомим шляхом коду, інструкція конкурує за увагу з кожним іншим реченням у контекстному вікні та може бути перевизначена нещодавно завантаженою або більш настійно сформульованою інструкцією. Контрольний артефакт, натомість, кодує те саме правило як вказівник: «Вимога тестування: забезпечується scripts/pre-commit-tests.sh, задокументовано в docs/harness/policy/tests.md.» Агенту не потрібно запам’ятовувати правило з прозового абзацу. Він викликає скрипт, читає детермінований вивід успіх/невдача і або продовжує, або зупиняється з конкретним посиланням на виправлення. Інструкція більше не є рядком у контекстному вікні. Вона є воротами на шляху виконання.

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

Граф вказівників виграє від навмисно нудного формату. Замість багатого форматування, вбудованих діаграм або переконання природною мовою, контрольний артефакт виграє від простого макета ключ-значення або заголовків секцій, де кожне правило відображається на шлях до файлу, рівень примусового виконання та посилання на виправлення відмови. Агента не потрібно переконувати дотримуватися правила. Йому потрібно показати, де живе правило і що робити, коли правило блокує прогрес. Формат файлу, який найкраще підтримує цей шаблон — це статичний Markdown з якорями секцій, оскільки кожне середовище виконання агента може розв’язати посилання Markdown, кожна система CI може перевірити, що файл Markdown існує за вказаним шляхом, і кожен людський рецензент може прочитати той самий артефакт без спеціалізованого інструментарію.

+-----------------------------+
| AGENTS.md (контрольний      |
| артефакт)                   |
+-----------------------------+
| ## Класи завдань            |
| - bug-fix -> docs/harness/  |
|   policy/bug-fix.md         |
| - deploy  -> docs/harness/  |
|   policy/deploy.md          |
| - feature -> docs/harness/  |
|   policy/feature.md         |
+-----------------------------+
            |
            v
+-----------------------------+
| docs/harness/policy/        |
|   bug-fix.md                |
+-----------------------------+
| ## Передпольотні перевірки  |
| - scripts/pre-commit-tests  |
| - scripts/branch-guard.sh   |
| ## Рівень примусу           |
| Обидві перевірки є          |
| примусовими                 |
| ## Виправлення              |
| Див. docs/runbooks/tests.md |
+-----------------------------+
            |
            v
+-----------------------------+
| scripts/pre-commit-tests.sh |
| (детермінований успіх/      |
|  невдача)                   |
+-----------------------------+

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

Прогресивне розкриття та заякорене розв’язання шляху

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

Заякорене розв’язання шляху означає, що кожен рівень дерева розкриття розв’язується у шлях до файлу, а не до опису теми. Опис теми каже «див. політику розгортання» — інструкція, яка вимагає від агента пошуку файлу, що відповідає цьому опису, інтерпретації кількох кандидатів-файлів і вирішення, який з них є авторитетним. Шлях до файлу каже «див. docs/harness/policy/deploy.md» — інструкція, яка розв’язується однією операцією файлової системи і дає рівно один результат. Різниця в затримці мала для людини, яка читає документацію, але вона накопичується між агентними сесіями, оскільки кожен нерозв’язаний опис теми додає крок пошуку, а кожен крок пошуку додає можливість для агента завантажити неправильний файл, інтерпретувати неправильну секцію або пропустити нещодавно додану політику, яку пошуковий індекс ще не проіндексував.

Заякорений ланцюг для класу завдань має передбачувану форму. Кореневий AGENTS.md оголошує клас завдань і його файл політики. Файл політики оголошує перевірки примусового виконання, дорадчі настанови та документи виправлення. Скрипти примусового виконання видають вивід успіх/невдача з конкретним кодом виходу. Документи виправлення описують шлях виправлення, коли примусове виконання зазнає невдачі. У жодній точці цього ланцюга агенту не потрібно шукати в репозиторії, оскільки кожен крок розв’язується у шлях до файлу, оголошеного на попередньому кроці. Ланцюг можна перевірити механічно: простий скрипт може пройти граф якорів від AGENTS.md через кожен файл політики та скрипт примусового виконання, на які є посилання, підтвердити, що кожен файл за посиланням існує, і повідомити про будь-які зламані посилання до того, як агент спробує за ними слідувати.

Прогресивне розкриття в контексті обв’язки також означає, що файли політики мають бути структуровані так, щоб агент читав правила примусового виконання першими — оскільки це ті правила, які можуть заблокувати прогрес — а дорадчі настанови другими. Цей порядок протилежний більшості документації, орієнтованої на людину, яка зазвичай починається з контексту та принципів перед переходом до конкретних правил. Зворотність виправдана, оскільки цикл завдань агента більше схожий на прохід компілятора, ніж на досвід читання людини. Агенту потрібно знати, що спричинить відмову збірки до того, як він почне збирати, так само як компілятор перевіряє синтаксис до генерації коду. Якщо правила примусового виконання поховані внизу довгого файлу політики, агент може почати роботу, зробити коміти і лише потім виявити, що хук перед комітом блокує шлях — витрачаючи кроки та бюджет контекстного вікна на роботу, яку файл політики міг би запобігти.

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

AGENTS.md
  |
  +---> docs/harness/policy/bug-fix.md
  |       |
  |       +---> scripts/pre-commit-tests.sh     (примусовий)
  |       +---> scripts/branch-guard.sh         (примусовий)
  |       +---> docs/harness/advisory/style.md  (дорадчий)
  |
  +---> docs/harness/policy/deploy.md
  |       |
  |       +---> scripts/deploy-guard.sh         (примусовий)
  |       +---> scripts/canary-approval.sh      (примусовий)
  |
  +---> docs/harness/policy/feature.md
          |
          +---> scripts/feature-branch-naming.sh (примусовий)
          +---> docs/harness/advisory/review.md  (дорадчий)

Це трирівневе заякорене дерево є практичною реалізацією принципу «мапа, а не посібник», який рекомендує оригінальне керівництво з інженерії обв’язки. Мапа — це індекс класів завдань AGENTS.md. Посібник — якщо він взагалі існує — це набір дорадчих документів, які агенти завантажують лише після того, як шлях примусового виконання було задоволено. Розрізнення має значення, оскільки мапа працює в перші 30 секунд запуску агента, тоді як посібник вимагає від агента прочитати, інтерпретувати та пріоритезувати потенційно сотні абзаців, перш ніж він зможе виконати будь-яку дію.

Обмеження інструкцій рівня промпту для флотів

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

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

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

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

Рішенням є не усунути шаблони промптів. Інструкції, специфічні для завдання — що будувати, як підходити до проблеми, який формат виводу повертати — все ще належать до промптів, оскільки вони варіюються за класом завдань. Рішенням є відокремити поверхню керування від поверхні завдань. Поверхня керування живе в рівні обв’язки репозиторію і завантажується кожною агентною сесією до того, як оцінюється будь-який специфічний для завдання промпт. Поверхня завдань живе в шаблоні промпту або описі завдання і варіюється за завданням. Розділення створює чистий контракт: середовище виконання платформи завантажує поверхню керування з системи записів репозиторію, агент застосовує правила керування до поверхні завдань, а примусовий рівень перевіряє результат. Жодна політика ніколи не дублюється між поверхнею керування та поверхнею завдань, що означає, що жодне оновлення політики не може бути пропущене через те, що воно було поховане в шаблоні, який ніхто не згадав відредагувати.

+---------------------------+       +---------------------------+
| ПОВЕРХНЯ КЕРУВАННЯ        |       | ПОВЕРХНЯ ЗАВДАНЬ          |
| (завантажується при        |       | (варіюється за завданням/ |
|  запуску агента)           |       |  задачею)                  |
+---------------------------+       +---------------------------+
| AGENTS.md                 |       | Опис задачі                |
| docs/harness/policy/*.md  |       | Шаблон промпту             |
| scripts/*.sh (примусове   |       | Специфікація WORKFLOW.md  |
|   виконання)               |       |                            |
+---------------------------+       +---------------------------+
| Джерело: SoR репозиторію  |       | Джерело: трекер задач або  |
| Авторитетне, версіоноване |       | бібліотека промптів        |
| Однакове для кожної сесії |       | Варіюється за класом       |
|                           |       | завдань                    |
+---------------------------+       +---------------------------+
            |                               |
            +---------------+---------------+
                            |
                            v
              +---------------------------+
              | СЕРЕДОВИЩЕ ВИКОНАННЯ     |
              | АГЕНТА                    |
              | Керування завантажується  |
              | першим, потім             |
              | застосовується контекст   |
              | завдання                  |
              +---------------------------+

Упередженість до нудних технологій і зменшення семантичної неоднозначності

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

Упередженість до нудних технологій — це свідомий вибір реалізовувати засоби керування обв’язки, використовуючи найпростіші доступні інструменти: статичні файли Markdown для декларацій політик, скрипти shell для воріт примусового виконання та шляхи файлової системи для графа розв’язання. Ці інструменти нудні в найкращому сенсі: вони мають чітко визначену семантику, яку розуміє кожне середовище виконання агента, вони видають детермінований вивід, вони можуть бути перевірені системами CI без користувацьких плагінів і не вимагають від агента вивчення нового DSL або інтерпретації незвичного формату конфігурації.

Коли скрипт shell виходить з кодом 1 і виводить повідомлення в stderr, кожне середовище виконання агента — будь то Claude Code, Codex CLI, Aider або самописна обгортка на Python — може проаналізувати результат і вирішити, чи продовжувати, чи виправляти. Коли файл Markdown оголошує політику з посиланням на скрипт примусового виконання, кожне середовище виконання агента може перейти за посиланням і виконати скрипт. Інструменти достатньо нудні, щоб бути інтероперабельними, а інтероперабельність між середовищами виконання агентів — це те, що робить обв’язку цінною для команди, яка може змінювати моделі, інструменти або платформи протягом життя репозиторію.

Проблема семантичної неоднозначності найгостріша в перші 30 секунд циклу завдань агента. Коли агент запускається й починає досліджувати репозиторій, він повинен відповісти на кілька питань, перш ніж зможе виконувати корисну роботу: який це клас завдань, які файли політики регулюють цей клас завдань, які ворота примусового виконання застосовуються і який порядок операцій для задоволення цих воріт. Якщо відповіді на ці питання вимагають інтерпретації описів природною мовою, пошуку в дереві файлів або вгадування, який із кількох схожих файлів політики є авторитетним, агент витрачає свої перші кроки на побудову ментальної моделі репозиторію замість виконання завдання. Гірше того, ментальна модель, яку він будує, може відрізнятися від ментальної моделі, яку інший агент побудував для того самого репозиторію чотири години тому, що означає, що флот працює на неузгоджених припущеннях, навіть якщо кожен агент читав ті самі файли.

Заякорене розв’язання шляху, трирівнева модель і архітектура графа вказівників слугують одній меті: зменшити семантичну неоднозначність цих перших 30 секунд до нуля або настільки близько до нуля, наскільки це може забезпечити детермінована файлова система. Коли агент читає AGENTS.md і знаходить таблицю класів завдань, яка відображає «bug-fix» на «docs/harness/policy/bug-fix.md», немає неоднозначності щодо того, який файл завантажувати. Коли файл політики перераховує скрипти примусового виконання за шляхом, немає неоднозначності щодо того, який скрипт запускати. Коли скрипт виходить з конкретним кодом і конкретним посиланням на виправлення, немає неоднозначності щодо того, що робити далі. Дерево рішень агента стає серією операцій файлової системи, які дають детерміновані результати, а аудиторський слід людського рецензента стає серією записів «прочитав цей файл, запустив цей скрипт, отримав цей результат», які можна відтворити та перевірити.

Упередженість до нудних технологій не означає, що обв’язка повинна залишатися простою назавжди. Команда, яка експлуатувала трирівневу обв’язку зі статичним Markdown і скриптами shell протягом кількох місяців, може виявити, що їхні перевірки примусового виконання стали достатньо складними, щоб виправдати більш структурований формат — реєстр правил на основі YAML, фреймворк «політика як код» або власний сервіс валідації з REST API. Упередженість стосується точки старту, а не стелі. Почніть з інструментів, які достатньо нудні, щоб бути механічно перевірними за допомогою виклику curl і виклику grep. Переходьте до складніших інструментів лише тоді, коли нудні інструменти демонстративно не можуть впоратися зі складністю, і складність дає вимірюване зменшення частоти відмов або часу відновлення. Більшість команд виявить, що нудні інструменти покривають 80 відсотків їхніх потреб у примусовому виконанні, а решту 20 відсотків можна вирішити невеликою кількістю цілеспрямованих скриптів, а не фреймворком політик загального призначення.

Шлях переходу від нудного до складного повинен запускатися конкретними доказами, а не інженерною цікавістю. Три сигнали виправдовують переведення правила з воріт примусового виконання на скрипті shell до більш структурованої реалізації.

По-перше, скрипт примусового виконання правила виріс понад 200 рядків, і команда більше не може обґрунтовувати його коректність, читаючи вихідний код. По-друге, правило забезпечується в більш ніж п’яти репозиторіях, і підтримка ідентичних копій скрипту в кожному репозиторії спричинила інцидент дрейфу, коли один репозиторій працював із застарілою версією. По-третє, правило вимагає даних із зовнішньої системи — API тікетів, менеджера секретів, бази даних відповідності — до яких скрипт shell не може надійно отримати доступ без складного керування обліковими даними.

Будь-який із цих сигналів є розумним тригером для оцінки більш структурованої реалізації. За відсутності цих сигналів нудна реалізація є правильним стандартом, і енергію команди краще витратити на покращення точності логіки примусового виконання, ніж на оновлення інструментарію, який її запускає.

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

Патерни та антипатерни

Патерни

Патерн	Коли використовувати	Чому це працює
Трирівнева класифікація	Коли команда має більше п’яти правил, яких агенти повинні дотримуватися	Призначає кожному правилу операційний рівень з явним володінням, тому команда знає, які правила є примусовими, які дорадчими, а які поза їхнім контролем
Архітектура графа вказівників	Коли політика змінюється часто або охоплює кілька доменів	AGENTS.md стає розв’язувачем на моменті запуску, який завантажує лише файли політики, релевантні для поточного завдання, зберігаючи контекстне вікно ощадливим, а аудиторський слід — явним
Відокремлені поверхні керування та завдань	Коли флот агентів працює з одним репозиторієм одночасно	Правила керування завантажуються з одного канонічного місця при запуску агента, тоді як специфічні для завдання інструкції залишаються в промпті, запобігаючи дрейфу політики між сесіями
Передпольотна валідація якорів	Коли репозиторій має три або більше пов’язаних файлів політики	Скрипт CI перевіряє, що кожен вказівник в AGENTS.md розв’язується до наявного файлу до початку будь-якої агентної сесії, виявляючи зламані посилання під час злиття, а не під час виконання
Примусове виконання перед дорадчим	Коли файли політики містять як блокуючі, так і неблокуючі правила	Завантаження правил примусового виконання першими дозволяє агенту виявити, що блокуватиме прогрес, до початку роботи, заощаджуючи бюджет контексту та кількість кроків

Антипатерни

Антипатерн	Чому команди в нього потрапляють	Краща альтернатива
Моноліт політик: усі правила в одному довгому AGENTS.md	AGENTS.md — це файл, який кожен агент читає першим, тому команди додають до нього більше, поки він не стає 4000-рядковим звалищем інструкцій	Залиште AGENTS.md для мапи класів завдань і графа вказівників; перенесіть деталі політики у файли за доменами в docs/harness/policy/
Пастка лише дорадчого: кожне правило дорадче, нічого не забезпечується примусово	Написання скриптів примусового виконання — це більше роботи, ніж написання прозових правил, і команди відкладають роботу, поки інцидент не змусить її	Визначте три правила, які завдали б найбільшої шкоди при порушенні, автоматизуйте їх першими, а решту розглядайте як беклог
Дубльована політика в шаблонах промптів	Копіювання конвенції гілок у кожен шаблон промпту здається швидкою перемогою протягом першого тижня впровадження агентів	Керуйте з репозиторію, а завдання — з промпту; ніколи не дублюйте правило керування між поверхнями
Семантичний пошук для розв’язання політики	Покладання на те, що агент шукатиме файли політики через grep або векторний пошук, створює недетерміновані шляхи розв’язання	Використовуйте заякорені шляхи до файлів у AGENTS.md, щоб кожне посилання на політику розв’язувалося до рівно одного файлу
Правила платформи у файлах репозиторію	Команди пишуть інструкції AGENTS.md на кшталт «агент повинен працювати в режимі danger», які середовище виконання платформи може перевизначити	Документуйте правила платформи у власній конфігурації платформи; тримайте файли репозиторію зосередженими на тому, що контролює репозиторій
Застарілі дорадчі правила без терміну дії	Стильове правило, написане шість місяців тому, залишається на дорадчому рівні, хоча команда більше його не дотримується	Додайте поле reviewed-date до кожного файлу політики та перевірку CI, яка позначає файли, що не переглядалися більше 90 днів

Фреймворк прийняття рішень

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

                        Нове правило керування
                              |
                              v
              +-------------------------------+
              | Чи стосується це правило       |
              | середовища виконання агента?   |
              | (модель, пісочниця, мережа,    |
              |  доступ до інструментів,        |
              |  таймаути)                      |
              +-------------------------------+
                     |                |
                    Так              Ні
                     |                |
                     v                v
              СЕРЕДОВИЩЕ          +-------------------------------+
              ВИКОНАННЯ           | Чи спричиняє порушення цього   |
              ПЛАТФОРМИ           | правила негайну та вимірювану   |
              Налаштуйте в        | шкоду?                         |
              платформі, не в     | (витік секретів, зламана       |
              репозиторії         |  збірка, порушення             |
                                  |  відповідності, зміна без      |
                                  |  можливості рецензування)      |
                                  +-------------------------------+
                                        |                |
                                       Так              Ні
                                        |                |
                                        v                v
                                 ПРИМУСОВИЙ          ДОРАДЧИЙ
                                 РІВЕНЬ              РІВЕНЬ
                                 ПРОЄКТУ             ПРОЄКТУ
                                        |                |
                                        v                v
                                 Реалізувати як:   Документувати як:
                                 - хук перед        - стильовий
                                   комітом            посібник
                                 - ворота CI        - рекомендована
                                 - детермінований     практика
                                   скрипт           - командна
                                                     конвенція
                                        |           - чекліст
                                        v             рецензування
                                 +-------------------------------+
                                 | Додайте шлях до документа     |
                                 | виправлення у вивід stderr    |
                                 | скрипту примусового           |
                                 | виконання та до графа         |
                                 | вказівників AGENTS.md         |
                                 +-------------------------------+

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

Менший набір правил перебуває на межі. Конвенція формату повідомлень комітів, наприклад, може здаватися нешкідливою для порушення в одному коміті, але накопичена неузгодженість у сотнях комітів робить генерацію журналів змін ненадійною, а автоматизацію випусків — крихкою. У таких випадках правило може починатися на дорадчому рівні — задокументуйте конвенцію, попросіть агентів її дотримуватися — і перейти на примусовий рівень після того, як команда побачить, що дорадчий рівень не працює. Шаблон, якого слід дотримуватися: виміряйте частоту порушень за визначений період (два тижні агентних сесій — розумне вікно), порівняйте її з толерантністю команди та переведіть на примусовий рівень, якщо частота перевищує толерантність. Цей шлях просування на основі даних запобігає найпоширенішому режиму відмови обв’язки — додаванню воріт примусового виконання для правил, які ніхто насправді не порушував, створюючи тертя, яке нікому не приносить користі.

Чи знали ви?

Чи знали ви: OpenAI опублікувала своє керівництво з інженерії обв’язки в лютому 2026 року, і протягом 2026 року конвенція AGENTS.md — спочатку керований спільнотою шаблон — була прийнята як першокласна поверхня керування в Codex CLI та низці агентних інструментів (Cursor, Amp та інших) і тепер підтримується як відкритий, кросплатформний формат. Claude Code, натомість, читає власний файл CLAUDE.md, а не AGENTS.md нативно (нативна підтримка AGENTS.md залишається відкритим запитом спільноти) — отже, дві екосистеми сходяться на одній ідеї (файл правил у репозиторії, придатний для машинного читання), навіть там, де назва файлу та завантажувач відрізняються.
Чи знали ви: Синтаксис @ у Claude Code — це механізм імпорту файлів: написання @.claude/rules/branches.md всередині файлу CLAUDE.md вбудовує весь вміст файлу за посиланням у контекст CLAUDE.md під час запуску агента. Агент не переходить до файлу за посиланням під час виконання — він отримує вбудований вміст як частину самого CLAUDE.md, що означає, що ланцюг імпорту є явним, придатним для аудиту та контрольованим через версії через файл, який його оголошує. Конвенція директорії .claude/rules/ — це організаційний шаблон рівня проєкту (прийнятий репозиторіями, включаючи KubeDojo), де обмежені файли правил імпортуються файлом CLAUDE.md проєкту через явні директиви @, а не автозавантажуються середовищем виконання.
Чи знали ви: Специфікація моделі OpenAI (опублікована у вересні 2025 року, регулярно оновлюється) визначає формальну ієрархію авторитетності інструкцій — інструкції платформи перевизначають інструкції розробника, а інструкції розробника перевизначають інструкції користувача — дизайн, який безпосередньо відповідає трирівневій моделі обв’язки, описаній у цьому модулі, де правила платформи перебувають вище правил репозиторію, а правила примусового виконання репозиторію — вище специфічних для завдання інструкцій.
Чи знали ви: Повторюваний, важкий для налагодження режим відмови в мультиагентних конфігураціях — це не варіативність моделі чи відмова інструменту, а неоднозначність щодо того, який файл політики регулює даний клас завдань — два файли правил суперечать один одному, або жоден артефакт не вказує, який з них перемагає, тому поведінка агента непередбачувано дрейфує між запусками. Підхід заякореного розв’язання шляху, який викладається в цьому модулі, існує саме для усунення цієї неоднозначності: одна таблиця класів завдань, один порядок розв’язання, одне місце для пошуку.

Типові помилки

Помилка	Чому це відбувається	Як це виправити
Написання довгого AGENTS.md, який змішує маршрутизацію класів завдань, деталі політики та стильові настанови в одному файлі	AGENTS.md — це перший файл, який читають агенти, тому кожен член команди додає своє правило, поки він не стає нечитабельним	Залиште AGENTS.md для мапи вказівників класів завдань; перенесіть деталі політики у файли за доменами, на які AGENTS.md посилається за шляхом
Ставлення до всіх правил як до однаково примусових без розрізнення дорадчого та примусового	Команда явно не обговорила, які правила є жорсткими обмеженнями, а які — вподобаннями	Проведіть одногодинний воркшоп з керування: перерахуйте кожне правило, проголосуйте, до якого рівня воно належить, і призначте власника для кожного примусового правила
Копіювання тієї самої політики в кілька шаблонів промптів замість посилання на одне джерело	Команда почала з одного шаблону промпту, потім клонувала його для різних класів завдань, і текст політики перейшов разом із ним	Вилучіть правила керування у файли репозиторію, видаліть їх з усіх шаблонів промптів і додайте один вказівник AGENTS.md до кожного файлу керування
Додавання воріт примусового виконання без надання шляху виправлення	Команда автоматизувала перевірку, але не відновлення, залишаючи агентів заблокованими без чіткого наступного кроку	Кожен скрипт примусового виконання повинен виводити повідомлення в stderr, яке містить шлях до документа виправлення, перед виходом з ненульовим кодом
Дозвіл файлам політики застарівати без регулярного перегляду	Файли політики рідко є найтерміновішим завданням у спринті, тому перегляд відкладається на невизначений термін	Додайте поле reviewed-date до кожного файлу політики та перевірку CI, яка завершується невдачею, якщо будь-який файл політики старший за 90 днів
Покладання на те, що агент знайде правильний файл політики через пошук у дереві	Команда не побудувала граф вказівників, тому єдиний спосіб для агента знайти політику — це пошук	Створіть таблицю класів завдань AGENTS.md, яка відображає кожен клас завдань на конкретний шлях до файлу політики, і валідуйте ці шляхи в CI
Розміщення правил на рівні платформи, які має контролювати репозиторій	Команда платформи та команда репозиторію не домовилися про те, хто володіє яким рівнем політики	Документуйте фіксовані правила платформи у файлі PLATFORM.md у корені репозиторію, посилайтеся на нього з AGENTS.md і тримайте файли політики репозиторію зосередженими на правилах, які контролює репозиторій
Ставлення до AGENTS.md як до одноразового завдання налаштування, а не як до підтримуваної поверхні керування	Команда написала AGENTS.md під час онбордингу агентів і ніколи не оновлювала його зі зміною політик	Додайте крок перегляду AGENTS.md до шаблону pull request для будь-якого PR, який змінює файл політики, щоб граф вказівників залишався синхронізованим

Тест

Перевірте своє розуміння за допомогою цих сценарних питань.

1. Файл AGENTS.md команди має 3800 рядків і включає конвенції гілок, шаблони комітів, чеклісти рецензування, кроки розгортання, посилання на runbooks та стильові посібники з кодування. Команда повідомляє, що агенти часто порушують конвенцію гілок, незважаючи на те, що правило помітно присутнє в AGENTS.md. Яка найімовірніша першопричина?

Найімовірніша першопричина полягає в тому, що конвенція гілок похована в монолітному AGENTS.md, де вона конкурує за увагу з тисячами рядків інших настанов. У файлі з 3800 рядків механізм уваги агента — як і людина, що читає довгий документ — розмиває сигнал будь-якого окремого правила. Виправлення не в тому, щоб зробити правило гучнішим або переформатувати файл. Виправлення в тому, щоб розділити AGENTS.md на мапу вказівників класів завдань і набір файлів політики за доменами, потім перенести конвенцію гілок у окремий файл (docs/harness/policy/branches.md) і забезпечити її хуком перед push. Агент потім слідує за вказівником до файлу політики, читає короткий сфокусований документ і стикається з воротами примусового виконання до того, як гілку буде відправлено — механічний шлях, який не залежить від конкуренції за бюджет уваги.

2. Ваша команда підтримує той самий чекліст розгортання в трьох місцях: вікі Notion, канвас Slack і docs/runbooks/deploy.md. Агент збирається виконати розгортання та виявляє всі три джерела через окремі пошукові операції. Якому джерелу агент повинен довіряти і яка одна зміна в репозиторії запобігла б повторенню цієї неоднозначності?

Агент повинен довіряти docs/runbooks/deploy.md, оскільки це джерело, розташоване в репозиторії, і тому воно версіоноване, придатне для рецензування та виявлення через валідацію CI. Вікі Notion і канвас Slack — це ефемерні комунікаційні поверхні, які можуть бути застарілими, неверсіонованими або не містити останніх оновлень. Одна зміна в репозиторії для запобігання повторенню — це припинити використання копій Notion і Slack, замінити їх посиланнями, які вказують на файл репозиторію, і додати шлях deploy.md до графа вказівників AGENTS.md, щоб кожен агент запускався з правильним джерелом без пошуку. Команда також повинна додати перевірку CI, яка підтверджує, що deploy.md існує та посилається на дійсні скрипти примусового виконання, щоб ланцюг вказівників валідувався на кожному pull request.

3. Команда додає хук перед комітом для сканування секретів до свого репозиторію. Хук правильно виявляє тестовий API-ключ у конфігураційному файлі та блокує коміт, але агент у відповідь повністю видаляє конфігураційний файл замість ротації ключа. Яка помилка класифікації рівня спричинила цю поведінку?

Команда правильно класифікувала сканування секретів як примусове правило та реалізувала механічні ворота. Помилка в тому, що вони не надали шлях виправлення — скрипт примусового виконання заблокував прогрес, не сказавши агенту, що робити далі. Примусове правило, яке каже «стоп», не кажучи «і ось як відновитися», перетворює розв’язну відмову на глухий кут, і агенти, зіткнувшись із глухим кутом, часто виконують деструктивні дії, щоб обійти блокування. Виправлення полягає в тому, щоб забезпечити, що вивід stderr скрипту примусового виконання містить посилання на документ виправлення (docs/runbooks/secret-rotation.md), який описує, як ротувати ключ, замінити закомічене значення на заповнювач і повторно проіндексувати файл. Трирівнева модель вимагає не лише воріт, але й шляху через ворота.

4. Ваша команда скопіювала повний набір правил керування репозиторію в шість різних шаблонів промптів для шести різних класів завдань. Конвенція іменування гілок змінюється, і ви оновлюєте п'ять із шести шаблонів. Через два тижні агент, що працює на шостому шаблоні, створює гілку зі старим шаблоном іменування. Де ця відмова належить у трирівневій моделі і яке правильне довгострокове виправлення?

Ця відмова не вписується чітко в жоден рівень, оскільки правила ніколи не були на жодному рівні — вони були дубльовані між поверхнями промптів, а не керувалися з одного джерела. Негайне виправлення — оновити шостий шаблон, але довгострокове виправлення — це вилучити правила керування з усіх шаблонів промптів, розмістити їх в одному файлі політики репозиторію (docs/harness/policy/branches.md), послатися на цей файл з AGENTS.md і забезпечити конвенцію хуком іменування гілок, який читає файл політики. Поверхня завдань (шаблони промптів) повинна містити лише специфічні для завдання інструкції, а поверхня керування (рівень обв’язки) повинна бути єдиним джерелом істини, яке кожна сесія завантажує при запуску. Це розділення запобігає проблемі дублювання назавжди, оскільки існує лише одна копія правила для оновлення.

5. Репозиторій має примусове правило, яке блокує коміти, коли покриття тестами падає нижче 80 відсотків, забезпечене воротами CI. Агент, який працює над виправленням помилки, додає однострокову зміну до застарілого модуля, який не має наявних тестів. Ворота CI блокують злиття, і агент витрачає дванадцять кроків, намагаючись написати тести для всього застарілого модуля, перш ніж здатися. Що не так із примусовим правилом і як його слід скоригувати?

Примусове правило правильне в принципі — пороги покриття тестами запобігають регресії — але воно застосовується занадто широко. Правило повинно розрізняти новий код (який повинен відповідати порогу 80 відсотків) і наявний непокритий код (від агента не слід очікувати ретроактивного покриття в межах виправлення помилки). Виправлення полягає в модифікації скрипту примусового виконання для вимірювання покриття лише на змінених рядках або змінених файлах, а не на всій кодовій базі, використовуючи інструмент на кшталт diff-cover або власний скрипт, який порівнює звіти про покриття з git diff. Це зберігає перевагу примусового рівня — запобігання нетестованим змінам — усуваючи ненавмисний тягар вимагати від агентів виправлення попередніх прогалин у покритті, не пов’язаних із поточним завданням.

6. Ваша команда оцінює, чи перевести конвенцію формату повідомлень комітів з дорадчого рівня на примусовий. Які операційні докази виправдали б цей перехід і яку конкретну метрику ви б відстежували протягом двотижневого пробного періоду?

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

7. Агентна сесія починається, читає AGENTS.md, слідує за вказівником до docs/harness/policy/bug-fix.md і виконує перераховані там скрипти примусового виконання. Один скрипт завершується невдачею з кодом виходу 1 і виводить «Назва гілки повинна відповідати шаблону: ^(feature|bugfix|hotfix)/[A-Z]+-[0-9]+. Див. docs/runbooks/branch-naming.md.» Агент відкриває docs/runbooks/branch-naming.md і виявляє, що він порожній, крім заголовка. Яка одна перевірка CI запобігла б цій ситуації?

Передпольотна перевірка валідації якорів запобігла б цій ситуації. Перевірка проходить граф вказівників AGENTS.md, слідує за кожним посиланням на файл політики, читає кожен шлях скрипту примусового виконання з кожного файлу політики та підтверджує, що кожен документ виправлення, згаданий у рядках виводу скриптів примусового виконання, існує та містить більше мінімальної кількості слів. Ця валідація виконується в CI на кожному pull request, який стосується рівня обв’язки, тому зламане посилання на виправлення виявляється під час злиття, а не під час виконання агента. Перевірку можна реалізувати як простий скрипт shell, який шукає шаблони «Див. docs/» у виводі stderr скриптів примусового виконання, перевіряє, що кожен шлях за посиланням існує, і завершує виконання CI невдачею з конкретним повідомленням про помилку, якщо будь-який шлях відсутній або порожній.

8. Команда приймає трирівневу модель обв'язки та правильно класифікує всі свої правила. Через шість місяців інцидент виявляє, що межа таймауту середовища виконання платформи була встановлена на 300 секунд, тоді як кілька скриптів примусового виконання виконуються 240-280 секунд. Під час пікового навантаження ці скрипти іноді досягають таймауту та завершуються невдачею, що агенти інтерпретують як порушення політики, а не як інфраструктурну відмову. Яку помилку класифікації рівнів це виявляє?

Це виявляє неузгодженість між рівнем платформи та примусовим рівнем. Оболонка таймауту платформи — це правило середовища виконання платформи, яке репозиторій не може перевизначити, але час виконання скриптів примусового виконання не був обмежений для перебування в межах цієї оболонки. Рівень платформи та примусовий рівень повинні проєктуватися разом: скрипт примусового виконання, який може перевищити таймаут платформи, не є надійними воротами, оскільки він може зазнати невдачі з інфраструктурних причин, не пов’язаних із дотриманням політики. Виправлення — або підвищити таймаут платформи (якщо команда платформи погодиться), зменшити час виконання скриптів примусового виконання, щоб він комфортно залишався в межах таймауту з запасом безпеки, або розділити довготривалі перевірки примусового виконання на швидку попередню перевірку, яка валідує передумови, та повільну повну перевірку, яка виконується асинхронно після відправлення коміту. Загальний принцип полягає в тому, що жодні ворота примусового виконання не повинні мати час виконання, який наближається до зовнішньої межі таймауту платформи.

Практична вправа

У цій вправі ви спроєктуєте макет макета репозиторію з трирівневою обв’язкою, побудуєте граф вказівників AGENTS.md, створите взаємопов’язані файли політики та скрипти примусового виконання та симулюєте обхід агента, який розв’язує конкретну відмову розгортання, використовуючи лише grep, cat і скрипти shell.

Налаштування: Створіть тимчасову директорію та заповніть її каркасом репозиторію, описаним нижче. Використовуйте лише стандартні інструменти командного рядка (bash, grep, cat, mkdir, echo).

Завдання 1: Побудуйте каркас

Створіть наступну структуру директорій і файлів:

harness-lab/
  AGENTS.md
  CLAUDE.md
  docs/
    harness/
      policy/
        branches.md
        tests.md
        deploy.md
      advisory/
        style.md
      runbooks/
        branch-naming.md
        test-failure.md
        deploy-rollback.md
  scripts/
    branch-guard.sh
    pre-commit-tests.sh
    deploy-guard.sh
  PLATFORM.md

Розв'язання

mkdir -p harness-lab/{docs/harness/{policy,advisory,runbooks},scripts}
touch harness-lab/{AGENTS.md,CLAUDE.md,PLATFORM.md}
touch harness-lab/docs/harness/policy/{branches.md,tests.md,deploy.md}
touch harness-lab/docs/harness/advisory/style.md
touch harness-lab/docs/harness/runbooks/{branch-naming.md,test-failure.md,deploy-rollback.md}
touch harness-lab/scripts/{branch-guard.sh,pre-commit-tests.sh,deploy-guard.sh}
chmod +x harness-lab/scripts/*.sh

Завдання 2: Напишіть мапу класів завдань AGENTS.md

Напишіть AGENTS.md, який відображає три класи завдань на їхні файли політики, використовуючи явні шляхи до файлів. Кожен запис повинен містити назву класу завдань, шлях до файлу політики та однорядковий опис воріт примусового виконання, які застосовуються.

Розв'язання

## Класи завдань

| Клас завдань | Файл політики | Ворота примусового виконання |
|---|---|---|
| bug-fix | docs/harness/policy/branches.md | scripts/branch-guard.sh, scripts/pre-commit-tests.sh |
| deploy | docs/harness/policy/deploy.md | scripts/deploy-guard.sh |
| feature | docs/harness/policy/branches.md | scripts/branch-guard.sh, scripts/pre-commit-tests.sh |

## Перевизначення платформи

Див. PLATFORM.md для правил рівня платформи, які цей репозиторій не може змінювати.

## Дорадчі правила

Див. docs/harness/advisory/style.md для стильових і рев'ю-конвенцій.

Завдання 3: Напишіть скрипт примусового виконання та його файл політики

Напишіть scripts/deploy-guard.sh для забезпечення передумови розгортання: цільове середовище повинно бути явно оголошене як «staging» або «production» у повідомленні коміту, інакше розгортання блокується. Скрипт повинен завершуватися невдачею з кодом виходу 1 і виводити посилання на виправлення. Потім напишіть docs/harness/policy/deploy.md, який посилається на скрипт.

Розв'язання

docs/harness/policy/deploy.md:

# Політика розгортання

## Примусове виконання

- scripts/deploy-guard.sh: блокує розгортання, якщо повідомлення коміту не містить `env: staging` або `env: production`

## Виправлення

Див. docs/harness/runbooks/deploy-rollback.md для процедур відкату, якщо розгортання зазнає невдачі після проходження перевірки.

scripts/deploy-guard.sh:

#!/usr/bin/env bash
set -euo pipefail

COMMIT_MSG="${1:-$(git log -1 --pretty=%B 2>/dev/null || echo '')}"

if echo "$COMMIT_MSG" | grep -qE 'env: (staging|production)'; then
    echo "Deploy guard passed: environment declared."
    exit 0
fi

echo "ERROR: deploy blocked. Commit message must include 'env: staging' or 'env: production'." >&2
echo "Remediation: docs/harness/runbooks/deploy-rollback.md" >&2
exit 1

Завдання 4: Симулюйте обхід агента

Симулюйте, як агент розв’язав би запит на розгортання, використовуючи лише інструменти командного рядка. Почніть з AGENTS.md, слідуйте за вказівником до політики розгортання, запустіть скрипт примусового виконання та спостерігайте за результатом — успіх або невдача. Протестуйте як успішний випадок (повідомлення коміту містить середовище), так і випадок невдачі (повідомлення коміту не містить).

Розв'язання

cd harness-lab

# Крок 1: Агент читає AGENTS.md і знаходить шлях до політики розгортання
POLICY=$(grep '^| deploy ' AGENTS.md | grep -oE 'docs/harness/policy/[^ |]+')
echo "Resolved policy file: $POLICY"

# Крок 2: Агент читає файл політики і знаходить скрипт примусового виконання
SCRIPT=$(grep -o 'scripts/[^ ]*\.sh' "$POLICY" | head -1)
echo "Resolved enforcement script: $SCRIPT"

# Крок 3: Запустіть скрипт примусового виконання з успішним повідомленням коміту
echo "env: staging" | xargs -I{} bash "$SCRIPT" "{}" && echo "PASS: deploy allowed" || echo "FAIL"

# Крок 4: Запустіть скрипт примусового виконання з невдалим повідомленням коміту (немає оголошення середовища)
bash "$SCRIPT" "Fix typo in config" && echo "PASS" || echo "FAIL: deploy blocked as expected"

Очікуваний вивід показує, що скрипт проходить, коли env: staging є в повідомленні коміту, і завершується невдачею з посиланням на виправлення, коли його немає.

Завдання 5: Додайте перевірку передпольотної валідації

Напишіть скрипт shell scripts/validate-anchors.sh, який проходить таблицю політик AGENTS.md, витягує кожен шлях до файлу за посиланням і перевіряє, що кожен файл існує. Запустіть його, щоб підтвердити, що ваш новий каркас обв’язки внутрішньо узгоджений.

Розв'язання

#!/usr/bin/env bash
set -euo pipefail

errors=0
echo "=== Anchor validation ==="

# Extract all paths from AGENTS.md policy table (skip header and separator)
while read -r path; do
    if [ -f "$path" ]; then
        echo "OK: $path"
    else
        echo "BROKEN: $path does not exist"
        errors=$((errors + 1))
    fi
done < <(grep -oP 'docs/[^ ]+' AGENTS.md | sort -u)

# Also validate enforcement script references inside policy files
for policy in docs/harness/policy/*.md; do
    while read -r script_path; do
        if [ -f "$script_path" ] && [ -x "$script_path" ]; then
            echo "OK: $script_path (referenced from $policy)"
        else
            echo "BROKEN: $script_path referenced from $policy but missing or not executable"
            errors=$((errors + 1))
        fi
    done < <(grep -oP 'scripts/[^ ]+\.sh' "$policy" 2>/dev/null)
done

if [ "$errors" -gt 0 ]; then
    echo "=== $errors broken anchors found ==="
    exit 1
fi

echo "=== All anchors valid ==="

Чекліст успіху

Створено каркас репозиторію з AGENTS.md, файлами політики, дорадчими файлами, runbooks і скриптами примусового виконання
AGENTS.md містить таблицю класів завдань із явними шляхами до файлів, а не прозовими описами
Принаймні один скрипт примусового виконання видає детермінований вивід успіх/невдача з кодами виходу
Кожен скрипт примусового виконання виводить посилання на виправлення в stderr при невдачі
Симуляція обходу агента розв’язує від AGENTS.md до скрипту примусового виконання менш ніж за 3 кроки
Скрипт передпольотної валідації якорів підтверджує, що всі шляхи за посиланнями існують

Джерела

https://openai.com/index/harness-engineering/ — канонічна публікація OpenAI про інженерію обв’язки як дисципліну (лютий 2026)
https://developers.openai.com/codex/guides/agents-md — документація OpenAI Codex CLI щодо AGENTS.md як поверхні керування
https://docs.anthropic.com/en/docs/claude-code/memory — документація Anthropic щодо CLAUDE.md та обмежених правил для Claude Code
https://agents.md/ — керована спільнотою специфікація та конвенції AGENTS.md
https://model-spec.openai.com/2025-09-12.html — специфікація моделі OpenAI, що визначає ієрархію авторитетності інструкцій (платформа, розробник, користувач)
https://modelcontextprotocol.io/docs/concepts/architecture — специфікація архітектури MCP, що описує патерни виявлення ресурсів клієнт-сервер
https://github.com/openai/symphony — репозиторій Symphony OSS, що демонструє оркестрацію «задача як площина управління» з контрактами WORKFLOW.md
https://raw.githubusercontent.com/openai/symphony/main/SPEC.md — специфікація Symphony, що визначає хуки життєвого циклу та семантику скінченного автомата для оркестрації агентів
https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions — документація GitHub Actions щодо обробки секретів (згадується в патернах сканування секретів на примусовому рівні)
https://aider.chat/docs/repomap.html — документація Aider щодо генерації мапи репозиторію та патернів прогресивного розкриття для агентів кодування
https://github.com/features/codespaces — документація GitHub Codespaces щодо патернів «репозиторій як середовище»
https://containers.dev/ — специфікація Development Containers, що визначає стандартизовані контракти середовища репозиторію

Наступний модуль

Модуль 3.2: Захисні бар’єри, ворота та застосунки, зрозумілі агентам — розширює трирівневу модель до конкретних механічних захисних бар’єрів: хуки, лінти, тести, помилки як виправлення, поверхні спостережуваності та підключення інструментів розробника, які роблять поведінку агента зрозумілою для людей, що володіють результатами.