Інженерія репозиторіїв для агентів

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

Час на виконання: 90-120 хв

Передумови: Модуль 2.1 Основи інженерії контексту або еквівалент; знайомство зі структурою репозиторію, робочими процесами Git та документацією Markdown.

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

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

• Спроєктувати стек читабельності репозиторію рівня агента та обґрунтувати, де знаходиться кожен рівень.
• Розмежувати файли системи записів від ефемерної пам’яті завдань та ефемерних журналів виконання.
• Створити інструкційні файли з прогресивним розкриттям, які запобігають дрейфу контексту та застарілим правилам.
• Скомпонувати структуровані поверхні docs/, які перетворюють політику, архітектуру та операції на машинно-зчитувані настанови.
• Зіставити, як репозиторій може «відповідати» агенту через кінцеві точки API, перевірки та поверхні стану.

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

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

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

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

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

У цьому модулі ви навчитеся задовольняти всі три, уникаючи класичних режимів відмови — крихких, перерослих файлів типу AGENTS та універсальних інструкцій.

Проблема, яку ми постійно вирішуємо в довготривалій роботі зі ШІ

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

1) Моноліт з одного файлу

Один файл типу AGENTS розростається, поки не стає музеєм. Він містить політику, стиль, правила гілок, гігієну секретів, етикет PR, порядок тестів, нотатки з розгортання та особливості платформи — все в одному місці. Файл зрештою стає шумом. Агенти все ще завантажують його, але співвідношення сигнал/шум падає.

2) Відсутня мапа

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

3) Застарілий цикл

Застаріле правило каже гілку main, але репозиторій перейшов на main плюс release та stage. Застарілий ритм рев’ю каже запускати одну перевірку, тоді як CI тепер вимагає три. Старий чекліст каже агенту пропустити дорогий, але тепер обов’язковий крок. Ця невідповідність не є гіпотетичною.

4) Репозиторій із зав’язаними очима

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

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

Чим AGENTS.md і CLAUDE.md насправді стають в агентній інженерії

AGENTS.md і CLAUDE.md — це парні контрактні рівні, а не дубльовані інструкційні книги. У KubeDojo AGENTS.md є крос-інструментальним bootstrap: він визначає, що кожна сесія повинна зробити перед кодуванням, включаючи онбординг на основі issues, необговорювані перевірки та межі антипатернів. CLAUDE.md є поверхнею пам’яті середовища виконання для інструментарію Anthropic, де оркестраційна поведінка та операційний намір можуть бути специфічними без перевантаження спільного bootstrap.

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

Посібник OpenAI з AGENTS.md описує пріоритетність за теками з конкатенацією від кореня до листя (щонайбільше один файл на теку). У межах кожної теки порядок виявлення такий: AGENTS.override.md → AGENTS.md → резервні імена файлів, налаштовані в project_doc_fallback_filenames. Якщо тека містить AGENTS.override.md, цей файл перемагає на цьому рівні та замінює AGENTS.md і будь-який налаштований резервний файл там. Якщо жоден із цих файлів не існує на цьому рівні, виявлення продовжується вгору; вибраний файл із кожної батьківської теки конкатенується від кореня до листя в комбінований набір інструкцій.

Посібник також робить явним один важливий момент щодо жорсткого обмеження: project_doc_max_bytes обрізає комбіновані інструкції. Типове значення — 32 KiB (32768 байтів); приклад конфігурації в посібнику показує підвищення ліміту до 65536, і поведінка полягає в тому, щоб зберігати лише найсвіжіші байти в межах області, коли комбіновані настанови перевищують цю межу. Це означає, що принцип проєктування KubeDojo — тримати AGENTS/CLAUDE стислими — не стилістичний, а вимога надійності, щоб критичні рядки не витіснялися обмеженням за байтами. Резервні імена файлів працюють, лише якщо вони вказані в конфігурації. Якщо проєкт використовує TEAM_GUIDE.md, але забуває його в project_doc_fallback_filenames, Codex мовчки ігнорує цей файл.

Цей механізм важливий, тому що він перетворює розмір інструкцій на жорсткий контракт середовища виконання. Уявіть, що файл типу AGENTS розростається до 20 тисяч слів, а потім гаряче виправлення додає 100 рядків на початку. Обмеження за байтами може мовчки відкинути вміст із нижчим пріоритетом у тому ж файлі, саме тому команди зазвичай резервують AGENTS і CLAUDE для інваріантів, а не для всього історичного контексту. Саме тому bootstrap має залишатися детермінованим: кожна недетермінована або довгоживуча деталь повинна бути делегована до обмежених файлів або перевірних кінцевих точок, а потім явно зазначена в кореневому контракті.

Сторона моделі OpenAI має ще один наслідок, який легко пропустити. AGENTS.md використовує пріоритетність за теками з конкатенацією від кореня до листя (AGENTS.override.md -> AGENTS.md -> резервні файли, щонайбільше один файл на теку), тоді як CLAUDE.md не зв’язаний цією ж моделлю пріоритетності. На практиці це означає, що AGENTS.md має чіткішу семантику переносності та резервного відновлення в крос-інструментальній диспетчеризації, тоді як CLAUDE.md може кодувати специфічну для Anthropic безперервність і поставу пам’яті для робочих процесів, які цього потребують. Ставлення до обох як до одного рівня створює ризик зв’язності, але ставлення до них як до взаємодоповнювальних рівнів дає вам передбачуваність: один стабільний крос-середовищний контракт запуску плюс один контракт операційної пам’яті з вищою кардинальністю.

Це означає, що файли, специфічні для Codex, та екосистеми CLAUDE.md повинні компонуватися, а не дублюватися. Кореневі AGENTS.md і CLAUDE.md визначають те, що ніколи не змінюється між сесіями. .claude/rules/* несе змінну, обмежену поведінку, яка все ще залишається близькою до шляху коду. Коли обидва еволюціонують разом, агенти отримують стабільні умови входу з AGENTS/CLAUDE та актуальні операційні деталі з правил без дрейфу контексту.

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

У цій моделі CLAUDE і AGENTS не є конкурентами; вони є суміжними межами. Там, де вони перетинаються, вони повинні вказувати на тих самих обмежених нащадків, а потім дозволяти одному модель-специфічному та одному крос-модельному рівню підтримувати узгоджену поведінку без суперечностей.

Прогресивне розкриття як принцип проєктування

Прогресивне розкриття — це дисципліна впорядкування контексту за стабільністю, перевикористанням та очікуваним дрейфом. Це не концепція UI, скопійована в документацію. Це принцип безпеки пам’яті для роботи зі ШІ.

Уявіть контекст як ієрархію пам’яті. Перший рівень завжди повинен бути безпечним для зберігання. Другий рівень повинен підтримувати повторювані операції. Третій рівень повинен залишатися вузьким та обмеженим у часі.

+--------------------------------------------------------------+
| Рівень | Стабільність        | Ритм змін     | Політика читання агентом |
+--------+---------------------+----------------+---------------------------+
| L0     | Висока              | Повільний      | Завжди завантажувати      |
| L1     | Середня             | Помірний       | Завантажувати при вході в піддерево |
| L2     | Низька              | Частий         | Завантажувати лише на вимогу |
| L3     | Ефемерна            | Реального часу | Завантажувати з поточного завдання |
+--------+---------------------+----------------+---------------------------+

L0: Завжди завантажувані файли мапи

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

• один шлях до основного контракту робочого процесу,
• один шлях до політики безпеки та гілок,
• один шлях до індексу документації,
• та один шлях до перевірок виконання.

AGENTS.md і кореневий CLAUDE.md є поширеними мешканцями L0. Але вони повинні залишатися компактними. Компактний L0 означає 100–250 високоефективних рядків, а не 3000-рядкову інструкційну книгу.

L1: Локально виявлювані зрізи репозиторію

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

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

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

L2: Документи, специфічні для ролей та робочих процесів

L2 містить цільові інструкції, прив’язані до ролей, функцій або повторюваних доменів. Кілька прикладів: Використовуйте L2, коли поведінка відрізняється за функцією, часовою лінією або набором дозволів, і завжди кодуйте, хто може виконувати кожен крок і який результат підтверджує відповідність.

• документація для онбордингу,
• документація для рев’ю PR,
• документація для публікації модулів,
• документація для сортування issues,
• документація для гігієни релізів.

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

L3: Динамічні поверхні виконання

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

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

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

Стек bootstrap для цього репозиторію

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

Рівень політики bootstrap починається в AGENTS.md і CLAUDE.md. AGENTS.md забезпечує поведінку запуску, сумісну з Codex, для всіх ланцюгів інструментів і робить явною відмову від невиконання інструкцій: жодного git log першим, онбординг на основі issue та обов’язкові ворота перед поданням. CLAUDE.md потім визначає ритм виконання для сесій Anthropic: контекст issue, орієнтація на основі API, обізнаність про пайплайн, дисципліна handoff та формат handoff модуля. Оскільки обидва файли малі та стабільні, їх можна швидко завантажити, і вони залишаються довговічними при повторних викликах.

scripts/cold-start.sh є першою конкретною реалізацією цієї політики. Він орієнтований на API: запускає сервіси, виводить git status, перелічує docs/decisions/pending та видає /api/briefing/session, /api/orient та /api/session/current. Це дає одну детерміновану поставу сесії перед будь-яким дослідженням репозиторію. Якщо KUBEDOJO_ISSUE встановлено або передано --issue, він спочатку виводить контекст завдання, специфічний для issue; якщо використано --manifest, він додає /api/state/manifest. При відмові API він не блокує завдання; він деградує до STATUS.md та останнього шляху handoff, виводить явний блок резервного відновлення та виходить з кодом 0. Явний код виходу сам по собі є частиною контракту, оскільки він уникає неоднозначних глухих кутів запуску.

Цей ланцюг не є деталлю реалізації, це машина станів онбордингу. Якщо /api/briefing/session?compact=1 досяжний, cold-start.sh дає одну канонічну форму, якій наступний рівень може довіряти: нагадування про issue, стан робочого простору, рішення, що очікують на розгляд, компактний брифінг, орієнтація та ланцюг сесії. Якщо він не може досягти API після п’яти спроб, скрипт все одно повертає придатний контекст, виводячи уривки з STATUS.md та видобутий шлях handoff з docs/session-state/. Ця гілка навмисно безпечна, оскільки вона пріоритезує рух уперед, роблячи джерело істини явно видимим, коли мережева довіра падає.

Стек середовища виконання потім зшиває цей вивід запуску з обмеженими файлами. CLAUDE.md вказує на .claude/rules/module-quality.md та .claude/rules/new-content-checklist.md, обидва з яких визначають конкретні, машинно-перевірні обмеження для структури модуля, результатів та наборів команд. Рівень правил потім зіставляє поставу bootstrap з локальними інструкціями виконання: список перевірок перед поданням, перевірки лабораторних робіт та очікування щодо воріт на рівні модуля. Якщо один із цих файлів застарів, це вже спостережувано як зламаний інтерфейс, оскільки кожне завдання тепер повинно пройти через ці перевірки, перш ніж продовжити.

Це композиційна модель. AGENTS.md дає вам інваріанти запуску. .claude/rules/* дає вам поточні процедурні обмеження. Рівень скриптів та API дає вам живі докази. Ви тримаєте одну відповідальність на рівень, і при відмові режим відмови завжди включає, де ремонтувати.

Рівень обмежених обмежень закріплений у .claude/rules/*. AGENTS.md посилається на .claude/rules/module-quality.md для воріт якості та .claude/rules/new-content-checklist.md для вимог до публікації. module-quality.md визначає структурні перевірки (кількість «Чи знали ви?», очікування щодо кількості розділів, анти-псевдокод), тоді як файл чекліста зіставляє їх із конкретними воротами командного рядка, такими як перевірки frontmatter, перевірки здоров’я та кроки збірки. Це тримає очікування високої стабільності в кореневих файлах, а операційні обмеження з низькою затримкою — в обмежених правилах.

Рівень істини середовища виконання для цієї лабораторної роботи поєднує скрипти та контракти кінцевих точок. scripts/agent_onboarding.md надає виконувані рецепти для запитування стану через curl (/api/pipeline/leases, /api/module/.../state, /api/reviews) та відомих переходів відмови. scripts/print-run-contract.sh — це створений у лабораторній роботі скрипт-парсер, який ви будуєте в практичній вправі та використовуєте для детермінованої перевірки контрактних шляхів. Разом ці скрипти замикають цикл bootstrap, перетворюючи очікування на перевірний стан.

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

Модель «документація як система записів»

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

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

1. Стабільний авторитет: твердження повинні бути істинними для модуля до навмисного перегляду.
2. Машинна читабельність: достатньо заголовків розділів, якорів та передбачуваних імен для інструментарію та пошуку.
3. Тиск рев’ю: кожна зміна в документації повинна відображатися в чеклістах, шаблонах PR або поверхнях стану.

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

+----------------------+----------------------------------------------+
| Призначення теки      | Основний споживач                             |
+----------------------+----------------------------------------------+
| src/content/docs     | Довгострокові записи навчання, політики та проєктування |
| .claude/rules        | Обмежені операційні обмеження агента          |
| scripts/*            | Операційні контракти та поверхні автоматизації |
| docs/research        | Стратегічні дослідження та короткі резюме      |
+----------------------+----------------------------------------------+

Цей репозиторій уже використовує цю структуру за проєктом. docs/ не є єдиним джерелом істини. Але це джерело найвищої цінності для постійних знань репозиторію.

Проєктування ланцюга AGENTS

Вам не потрібен один гігантський стратегічний документ AGENTS. Вам потрібен передбачуваний ланцюг. Ось надійна послідовність:

Крок 1: коренева картка bootstrap

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

• де знаходяться перевірки,
• який порядок команд керує кожним запуском,
• які заборонені виводи заборонені,
• та де пов’язані глибші інструкції.

Крок 2: теки областей

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

Крок 3: зв’язування від стабільного до динамічного

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

Крок 4: періодичні аудити

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

• застарілі виклики процесів,
• застарілі інструменти,
• переміщені теки,
• змінені імена власників.

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

Крок 5: хуки зворотного зв’язку

Ланцюг повинен включати, де виявляються порушення. Якщо правило існує і не перевіряється, це не інструкція, а лише переказ.

CLAUDE.md як багаторівнева пам’ять у цій моделі

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

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

• кореневий CLAUDE.md: постава запуску та крос-проєктні конвенції,
• вкладений CLAUDE.md: специфічний для домену контекст,
• посилання на сторінки docs/ для довговічного проєктування та політики,
• посилання на локальні кінцеві точки для поточного стану.

Важливе розрізнення: Стабільний контракт bootstrap не повинен бути збірником для швидкозмінної поведінки; він повинен володіти лише принципами, які залишаються дійсними в багатьох запусках і командах.

• CLAUDE.md — це bootstrap пам’яті.
• AGENTS.md — це часто bootstrap на рівні екосистеми та індекс, орієнтований на агента.
• сторінки docs — це довговічні записи та контракти поведінки.

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

Як репозиторій повинен «відповідати»

Репозиторій відповідає, коли він надає машинно-зчитувані сигнали про відмову з тією ж швидкістю, з якою агент приймає рішення. У KubeDojo це означає, що три кінцеві точки пов’язані в один операційний цикл: паралельність (/api/pipeline/leases), стан (/api/module/{key}/state) та історичне рев’ю (/api/reviews?module={key}). Це не просто спостережуваність; це потік управління.

Сценарій відмови 1: дубльоване володіння перед захопленням. Робочий процес агента: GET /api/pipeline/leases → вирішити, чи модуль наразі захоплений. Якщо список містить цільовий модуль, /api/module/{key}/state все ще надає підтвердження в lease з held, leased_by та seconds_to_expiry. Це означає, що репозиторій уже вирішив, що це ризик паралельного запису. Правильний шлях — перервати спроби захоплення, або чекати до завершення терміну дії, або вибрати інший модуль. Лише після цього той самий агент переходить до валідації та патчингу. Ця одна перевірка запобігає дубльованим колізіям гілок без людського арбітражу.

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

Сценарій відмови 2: недійсний стан модуля перед редагуванням. Той самий виклик /api/module/{key}/state може повернути записи diagnostics[] зі стабільними значеннями code, такими як frontmatter_no_title, rubric_poor, uk_state_missing або lease_held. Кожен діагностичний запис містить severity, summary та опціонально next_action. Це ключовий сигнал проєктування: відмови — це не просто булеві значення. Коли next_action каже GET /api/labs/status, агент може перемкнутися на перевірки здоров’я лабораторних робіт. Коли він каже GET /api/tracks/readiness або маршрутизацію, пов’язану з рев’ю, агент може перейти від редагування вмісту до завдань управління без вгадування. Саме так diagnostics[] перетворює невідомі відмови на детерміновані кроки виправлення. Те саме корисне навантаження також містить english_path, ukrainian_path та прапори наявності fact_ledger. Це дозволяє агенту припинити вгадування й натомість розгалужуватися за доказами: якщо у frontmatter відсутній title, відкрити вихідний шлях першим; якщо переклад застарів, перевірити GET /api/translation/v2/status; якщо факти відсутні, запустити pipeline enqueue. Кожна гілка має наступну дію, підкріплену кінцевою точкою, тому виправлення є машинно-узгодженим.

Сценарій відмови 3: застарілий шлях рев’ю або невирішені докази. Агент запитує /api/reviews?module={key} перед внесенням фінальних редагувань. Якщо модуль ніколи не рецензувався, API повертає {"error":"review_not_found"}, і це стає сигналом жорсткої зупинки для спроб злиття. Якщо рев’ю існує, але не має доказів, fact_check_unverified у стані та діагностичне попередження вказують на необхідність додаткового проходу виправлення перед тим, як можна буде продовжити переробку. Цей сценарій зберігає цілісність рев’ю, залишаючи відмову локальною та машинно-зчитуваною.

Сценарій відмови 4: недійсний ключ модуля. Кінцеві точки забезпечують валідацію ключів через _validate_module_key. Якщо агент надсилає /api/reviews?module=bad value, API повертає {"error":"invalid_module_key"} з 400. Ця помилка не косметична; це жорсткий сигнал нормалізувати або виправити ключ модуля перед повторним запуском захоплень або перевірок стану. Якщо /api/module/{key}/state отримує той самий некоректний ключ, він також повертає 400. Це уникає дорогого класу відмов «працював над неправильним файлом».

Сценарій відмови 5: застарілий вивід у стані пайплайну. Якщо /api/module/{key}/state показує frontmatter_* або english_missing плюс pipeline_rejected у діагностиці, та сама кінцева точка вже вказує на /api/pipeline/v2/events?module=..., тож другий виклик API пояснює, чи проблема в порядку черги, конфлікті залежностей або dead-letter. Це антишумовий патерн: кожен шлях відмови має вузький і явний наступний виклик, замість широкого циклу повторного запуску та ручного полювання за логами.

У здоровому потоці всі три відмови сходяться до явних станів: leases запобігає конфлікту, state пояснює, чому модуль заблоковано, а reviews підтверджує, чи останнє обґрунтування є надійним. Лише коли всі три узгоджуються, агент може перейти від діагностичного режиму до режиму патчу з упевненістю, що дублікати та застарілий стан обидва вирішені.

Від інструкцій до виконуваних контрактів

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

Мінімальний контрактний патерн: твердження, команда, ворота та крок виправлення — все в одній родині файлів, щоб кожне твердження можна було аудитувати без крос-файлової тріангуляції.

1. Твердження в інструкційному файлі.
2. Відповідна команда в scripts/*.
3. Автоматизована перевірка зі стабільним іменем команди.
4. Ворота CI або локальної перевірки.
5. Шлях рев’ю, коли перевірка не проходить.
6. Інструкція з виправлення, коли статус стає червоним.

Інтерфейс репозиторію для агентів: рамка проєктування

Використовуйте цю архітектурну лінзу під час аудиту репозиторію, оскільки кожен рядок повинен пов’язувати видиме питання з повторюваним вимірюванням та шляхом відновлення.

+----------------------+---------------------------+-------------------------------+
| Поверхня              | Поставлене питання         | Тест якості                   |
+----------------------+---------------------------+-------------------------------+
| Bootstrap-файли       | Чи може агент безпечно     | Завантажується без            |
|                      | запуститися?               | суперечностей                 |
| Правила та норми      | Чи явні обмеження?         | Покрито перевірками/рев'ю     |
| Структуровані docs    | Де живе істина?            | Пошукоспроможність + свіжість |
| Скриптовий зворотний  | Чи може повідомити         | Стабільність API + команд      |
| зв'язок              | поточний стан?             |                               |
| Поверхні              | Чи може пояснити відмови?  | Логи + підсумковий вивід       |
| спостережуваності     |                           |                               |
+----------------------+---------------------------+-------------------------------+

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

Чотири обов’язкові питання проєктування

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

1. Що завжди істинне для цього репозиторію?
2. Що зазвичай істинне, але підлягає зміні?
3. Що є тимчасовим для цієї конкретної роботи?
4. Що репозиторій повідомляє після кожного запуску?

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

Репозиторій як контракт із кількома читачами

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

• Люди хочуть обґрунтування та наратив.
• Агенти хочуть стабільні точки видобування.
• CI хоче інваріанти, які можна перевірити командами.
• Рецензенти хочуть аудитопридатність та детерміновані чеклісти.

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

Багаторівневий інструкційний патерн для реальних модулів

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

ModuleRoot/
  module-name/
    module.md          # компактний навчальний контракт рівня модуля
    tasks/
      hands-on.md      # опціонально, якщо потік завдань великий
    checklists/
      preflight.md     # опціональний чекліст середовища виконання

Не вимагайте від кожного модуля включати всі теки. Вимагайте від кожного модуля вказувати щонайменше один стабільний шлях до:

• як почати,
• як перевірити,
• як повідомити про завершення.

Що не повинно потрапляти до AGENTS.md

Сильний антипатерн — завантажувати AGENTS.md одноразовими або швидкозмінними інструкціями. Використовуйте цільову документацію натомість, оскільки кореневі рівні повинні зберігати стабільну семантику, а рольові та задачеві документи можуть еволюціонувати, не ламаючи контракт запуску кожної сесії.

• імена рецензентів, специфічні для PR,
• деталі одноразових issues,
• тимчасові експерименти з іменування локальних гілок,
• невирішені проєктні чернетки.

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

• промпт завдання,
• коментарі до issue,
• нотатки на рівні модуля,
• тимчасові логи виконання.

Коли CLAUDE.md слід розділити

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

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

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

Анти-крихкість репозиторію: проєктування з усвідомленням застарілості

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

Приклад політики застарілості

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

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

Ці поля слід переглядати щоразу, коли змінюється командна поверхня.

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

Оцінку застарілості файлу можна обчислити вручну. Використовуйте це як щоквартальну перевірку здоров’я для поверхонь типу AGENTS, перш ніж дрейф проявиться як відмови середовища виконання.

+-------------------+----------------+------------------+--------------------------+
| Файл              | Остання зміна  | Остання дія      | Дія                       |
+-------------------+----------------+------------------+--------------------------+
| AGENTS.md         | старіше 60 днів | без змін 30 днів  | потрібен перегляд         |
| CLAUDE.md         | старіше 45 днів | змінено 2 р/міс   | оновити розділи зіставлення|
| docs/ модулі      | старіше 120 днів| без змін 60 днів  | звірити зі скриптами       |
| .claude/rules     | старіше 30 днів | змінено 10 днів   | обов'язковий перегляд власниками|
+-------------------+----------------+------------------+--------------------------+

Поверхні репозиторію на практиці: креслення

Репозиторій, який можуть використовувати агенти, повинен надавати чотири основні документи:

1. Документ орієнтації.
2. Документ стандартів та рев’ю.
3. Документ стану та здоров’я.
4. Документ ескалації та перевизначення.

Документ орієнтації

Це перший файл, який агент завжди повинен мати змогу визначити. У KubeDojo кореневий CLAUDE.md та точки входу скриптів виконують цю роль.

Документ стандартів та рев’ю

Тут живуть довгоживучі правила поведінки та де фіксуються довговічні обмеження, а потім прив’язуються до перевірок, які запобігають випадковому дрейфу. Наприклад:

• робочий процес на основі issue,
• очікування щодо гілок,
• конвенції PR.

Документ стану та здоров’я

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

• стан пайплайну на рівні модуля,
• стан якості,
• активні блокування,
• попередження локального API.

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

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

• які настанови перемагають при конфлікті,
• які ручні перевірки є обов’язковими,
• де повідомляти та закривати суперечності.

Приклад архітектури: як навчити агента, що ігнорувати

Агенти погано справляються, коли їх просять міркувати над згенерованими файлами, директоріями вендорів та одноразовими виводами без явних виключень. Включайте явні виключення в bootstrap та в чеклісти завдань.

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

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

У цьому репозиторії згенеровані артефакти виконання вже зазначені в обмеженнях типу AGENTS. Та сама ідея повинна з’явитися у вашому власному проєкті.

Проєктування читабельності репозиторію з контрактами на рівні файлів

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

# Контрактний патерн A — Незмінний базовий рівень
Файл: src/content/docs/<шлях>/index.md
Контракт: ця сторінка визначає навігацію модуля та призначення.
Власник: керівник модуля.
Оновлення: коли змінюється структура навчальної програми.

# Контрактний патерн B — Інваріант виконання
Файл: scripts/*
Контракт: вивід команди та режим відмови повинні залишатися машинно-передбачуваними.
Власник: автор скрипту.
Оновлення: перед кожним релізом.

# Контрактний патерн C — Когнітивна мапа
Файл: CLAUDE.md
Контракт: контракт bootstrap та інструкції першого порядку.
Власник: супроводжувачі.
Оновлення: щотижня для активних репозиторіїв.

Для кожного файлу вкажіть як «що він робить», так і «чому він це робить», потім дайте посилання на команду перевірки.

Проєктування практичного чекліста для авторів репозиторіїв

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

1. Почніть з issue.
2. Складіть чернетку контрактних поверхонь.
3. Додайте посилання та виключення.
4. Додайте команди верифікації.
5. Додайте поверхні зворотного зв’язку.
6. Запустіть перевірки.
7. Оновіть індекс.

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

Мінімальний контрактний набір для здорового репозиторію

Ефективний мінімальний набір у цій моделі має сім файлів/компонентів, і видалення будь-якого одного зазвичай створює нетестований розрив або в онбордингу, або в примусовості, або в закритті.

• AGENTS.md або еквівалент.
• CLAUDE.md або еквівалент.
• еквівалент scripts/cold-start.
• один local API або скрипт для запиту поточного контексту виконання.
• один чекліст модуля для рев’ю.
• одна точка входу перевірки якості.
• одна перевірка здоров’я.

Якщо репозиторію бракує хоча б одного компонента, репозиторій наразі не є «дружнім до агентів».

Опрацьований приклад: покроковий розбір проєктування репозиторію

KubeDojo є конкретним прикладом тієї самої багаторівневої моделі, яку цей модуль намагається навчити. KubeDojo дає повний стек життєвого циклу в одному репозиторії. На кореневому рівні AGENTS і CLAUDE визначають послідовність онбордингу, дисципліну перед поданням та межі операційних антипатернів. Шлях ескалації, специфічний для проєкту, видно на практиці через docs/decisions/pending/, STATUS.md та вказівник handoff, виведений scripts/cold-start.sh. Іншими словами, розмова про те, що робити далі, ніколи не прихована в одній застарілій нотатці; вона виводиться на поверхню через контрактні файли, знімки кінцевих точок та явні артефакти handoff.

Щоб побачити це як конкретний ланцюг управління, простежте один запуск онбордингу з застарілого стану. cold-start.sh спочатку виводить статус гілки, рішення, що очікують на розгляд, корисне навантаження орієнтації та стан сесії. Якщо щось із цього відсутнє через те, що API не працює, той самий скрипт все одно видає STATUS.md та розібраний шлях handoff, замість того щоб примусово зупинятися. Це дає детермінований шлях резервного відновлення та запобігає тому, щоб репозиторій зупиняв агента посеред проблеми через те, що одна сервісна кінцева точка тимчасово нездорова.

scripts/agent_onboarding.md пов’язує ці ідеї разом у конкретному сценарії: холодний старт з урахуванням issue, компактний брифінг, орієнтація, виявлення рев’ю та визначена політика перед захопленням. Він явно посилається на поведінку кінцевих точок (/api/pipeline/leases, /api/module/{key}/state, /api/reviews) та очікувані оболонки відмови для кожної. Це робить цей репозиторій читабельним, тому що контракт можна перевірити з одного місця без вгадування пріоритетності команд.

Патерн проєктування модуля поглиблюється, коли ви порівнюєте модель стану scripts/local_api.py. /api/module/{key}/state об’єднує перевірки файлової системи, статус перекладу, статус рев’ю та дані активної оренди в одне корисне навантаження. Це означає, що агенти не зшивають стан із випадкових файлів лише для того, щоб визначити, чи безпечно захоплювати модуль. Натомість вони читають одну відповідь і розгалужуються детерміновано. Це саме той контракт «відповіді», якого навчає цей модуль.

У цьому корисному навантаженні стану три деталі є особливо практичними: lease запобігає перекриттю, diagnostics[] замінює розпливчасту мову статусу, а next_action дає наступну конкретну кінцеву точку для запиту. Це означає, що репозиторій не просто повідомляє агенту, що не так; він приписує, який крок верифікації повинен відбутися далі. Різниця важлива, тому що один виклик state може замінити десятки неформальних правил команди.

Сильним контрастом є learn-ukrainian, де патерн організований навколо виконання на основі ролей. У дереві agents_extensions/ KubeDojo (перейменованому з claude_extensions/ для відображення багатоагентного використання) рольова поведінка кодується як дані, а не лише проза: shared/skills/ містить агентно-агностичні контракти (автори, рецензенти, доменні експерти), тоді як claude/skills/ містить накладання оркестратора Claude, такі як curriculum-orchestrator та dispatch-router. deploy.sh об’єднує спільні джерела плюс джерела на агента в приховану директорію кожного агента (.claude/ сьогодні; .codex/, .cursor/, .gemini/, коли ці агенти отримають вміст). Обмежені .claude/rules/ забезпечують деталі робочого процесу; межі виконання стають примусовими в settings.json та settings.local.json, які розділяють дозволи read, write, edit та bash за категорією операцій і маршрутизують з allow/ask. Цей репозиторій не центрує рольові межі заради них самих; він робить це, щоб плутанина ролей не могла стати мовчазною помилкою репозиторію.

Контраст корисний, тому що він виявляє дві дійсні траєкторії проєктування. KubeDojo тримає логіку запуску та перевірки пайплайну в корені репозиторію й дозволяє обмеженим правилам виражати деталі робочого процесу. learn-ukrainian тримає рольову та диспетчерську політику у своїй теці розширень, а потім просуває дозволи виконання вниз через settings.json та класи команд. Обидва можуть працювати для великих багатоагентних систем, і обидва залишаються супроводжуваними, тому що кожен рівень зберігає один вид істини та виставляє семантику відмови. Глибший урок проєктування — не вибір одного репозиторію над іншим; це вибір того, де живуть істини запуску, ідентичності та дозволів, щоб той самий контракт кінцевої точки міг залишатися стабільним з часом.

Обидва репозиторії є реальними та порівнюваними, але вони пріоритезують різні шви. KubeDojo веде з довговічною політикою bootstrap плюс обмеженою валідацією середовища виконання. learn-ukrainian веде з рольовою ідентичністю плюс операційними дозволами. Урок проєктування — не «виберіть одну модель». Він у тому, що: якщо відповідальність зміщується від онбордингу до виконання, ви повинні змістити розташування контракту від кореневої політики до специфічних для ролі дозволів і все одно тримати хуки зворотного зв’язку ідентичними: запуск, стан, рев’ю та детерміновані наступні дії.

Порівнева рубрика проєктування

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

+--------------------+-------------------------+--------------------------+-------------------+
| Рівень             | Індикатор проєктування  | Перевірка доказу         | Сигнал відмови     |
+--------------------+-------------------------+--------------------------+-------------------+
| Орієнтація         | Один файл вас запускає  | перевірка bootstrap      | повторювані уточнення |
| Пам'ять            | Інструкції багаторівневі| завантаження вкладеної    | конфліктуючі правила |
|                    |                        | пам'яті                  |                   |
| Вміст              | мапа docs актуальна     | версіоновані посилання    | застаріле копіювання |
|                    |                        | docs                     |                   |
| Зворотний зв'язок  | стан виконання видимий  | запит кінцевої точки      | мовчазні відмови   |
|                    |                        | API/state                |                   |
| Управління         | винятки явні            | нотатки рев'ю + логи      | мовчазний дрейф    |
|                    |                        |                          | правил            |
+--------------------+-------------------------+--------------------------+-------------------+

Проєктування для масштабування між багатьма типами issues

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

Патерн для кількох команд

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

Патерн для кількох моделей

Різні моделі ШІ та інструменти аналізують інструкції по-різному. Тримайте стабільні команди та імена узгодженими. Це зменшує специфічну для моделі варіативність.

Патерн для кількох середовищ виконання

Один запуск відбувається локально. Один запуск відбувається в CI. Один запуск відбувається в рев’ю. Репозиторій повинен видавати той самий очікуваний стан для кожного середовища виконання.

Практичні контрактні артефакти, які ви повинні побудувати

Зрілий репозиторій має щонайменше ці артефакти:

1. Навігаційна картка: з чого почати.
2. Картка виконання: що запускати і коли.
3. Картка ризиків: чого не робити.
4. Картка відновлення: де перевіряти відмови і як перезапустити.
5. Картка закриття: що становить успішний запуск.

Кожна картка може жити в документації або у виводі команд, але посилання повинні існувати з файлів bootstrap.

Уникнення інструкційного боргу

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

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

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

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

• Власник: супроводжувач модуля,
• Рецензент: рецензент якості,
• Дата завершення рев’ю,
• Нотатка про міграцію.

Інженерія репозиторіїв як соціальний контракт

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

Репозиторій, який відповідає агенту, створює кращу співпрацю, тому що:

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

Вправа з проєктування: зіставте цей репозиторій із чотирма рівнями

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

• Рівень 0: який файл завжди завантажується і чому.
• Рівень 1: який файл обмежується текою і хто ним володіє.
• Рівень 2: де живуть специфічна для ролі поведінка та вибір інструментів.
• Рівень 3: де публікуються стан поточного запуску та телеметрія.

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

Чи знали ви?

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

Поширені помилки репозиторіїв та антипатерни найкорисніші, коли їх ранжувати за тим, як швидко вони ламають надійність агента.

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

Поширені помилки та шляхи відмови, які вони створюють, коли інструкційні рівні стають неточними

Помилка	Чому це шкодить агентам	Типовий симптом
Один гігантський файл AGENTS без розділів	Перевантаження та неоднозначний пріоритет	Агенти пропускають критичні обмеження
Відсутність вкладених перевизначень інструкцій	Глобальні правила мовчки перевизначають локальні потреби	Специфічні для команди завдання провалюються через локальні конвенції
Інструкції, продубльовані в багатьох місцях	Конфліктуючі застарілі копії	Різні запуски суперечать один одному
docs/ використовується як звалище	Відсутність стабільного індексу істини	Агенти раз за разом відкривають неправильний файл
Відсутність машинно-зчитуваної поверхні стану	Приховані відмови залишаються мовчазними	Повторення того самого циклу виправлення
Згенеровані артефакти змішані з вихідними документами	Шум у результатах пошуку	Агенти поглинають сміттєвий контекст
Відсутність періодичного перегляду інструкційних файлів	Дрейф контексту стає системним	Застаріла політика виглядає «актуальною»

Що поверхня репозиторію повинна містити в межах цього модуля

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

• компактна мапа рівня репозиторію,
• обмежена ієрархія пам’яті,
• структуровані записи docs/,
• та операційні кінцеві точки зворотного зв’язку.

Для навчання це означає, що мінімальна реалізація — це:

• один кореневий файл bootstrap,
• один ієрархічний файл пам’яті,
• один набір структурованих документів,
• одна перевірка якості,
• одна перевірка здоров’я,
• та один маршрут ескалації.

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

Патерни проєктування для файлів типу AGENTS

Використовуйте наступний шаблон компонування та зберігайте його як перевикористовуваний аудиторський шаблон для майбутніх модулів.

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

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

# Стабільні інваріанти
- політики гілок,
- обов'язкові перевірки,
- обмеження організації коду.

# Маршрут середовища виконання
- релевантні API,
- кінцеві точки здоров'я,
- шлях рев'ю.

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

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

Проєктування чекліста для супроводжувачів

Стислий чекліст супроводжуваності для інженерії репозиторіїв: Цей список слід переглядати кожен спринт, оскільки одне застаріле припущення може вимкнути цілі потоки автоматизації.

1. Чи точка входу достатньо коротка для швидкого читання?
2. Чи шляхи команд явні та детерміновані?
3. Чи тимчасові нотатки обмежені завданнями?
4. Чи згенеровані директорії явно виключені?
5. Чи є маршрут «наступний крок після відмови»?
6. Чи індекс документації виявлюваний з файлів bootstrap?
7. Чи багаторівневі файли взаємно узгоджені?

Якщо будь-яка відповідь — ні, потрібен тріаж файлів, і ви повинні оновити власника розділу перед продовженням виконання завдання.

Як спроєктувати це для реальної команди за один тиждень

Тиждень 1: Запустіть це як операційний мікро-план, де кожен день або звужує неоднозначність, або усуває ризик застарілого контракту.

• День 1: інвентаризуйте наявні правила та дублікати.
• День 2: визначте кореневі AGENTS/CLAUDE лише з мапою.
• День 3: перемістіть стабільні факти в структуру документації.
• День 4: розділіть вкладені обмежені інструкції.
• День 5: виставте команди стану та здоров’я.
• День 6: додайте відсутні поверхні рев’ю.
• День 7: запустіть перевірки та зберіть перший патерн відмови.

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

• додайте перевірки застарілості,
• додайте метадані володіння,
• додайте автоматизоване нагадування про видалення застарілих розділів.

Знання як перевикористовувані модулі

Репозиторій, спроєктований для агентів, повинен підтримувати як швидкий старт, так і глибокі занурення. Шлях швидкого старту дає короткострокову швидкість. Шлях глибокого занурення дає довгострокову коректність.

Шлях швидкого старту: Використовуйте цей шлях, коли репозиторій завантажується вперше і вам потрібен детермінований базовий рівень упевненості перед будь-якими редагуваннями вмісту.

• запустіть cold-start,
• перегляньте стан,
• відкрийте індекс модуля,
• запустіть перевірки модуля.

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

• перевірте історію рев’ю,
• перевірте дельти інструкцій,
• перевірте статус пайплайну,
• та простежте послідовності відмов між запусками.

Правило «якщо не представлено — примусово виконуй»

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

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

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

Різні моделі та фреймворки завантажують контекст по-різному. Ви можете зменшити варіативність, використовуючи:

• стислі інструкції L0,
• стабільні імена файлів,
• низьку плинність для bootstrap,
• детерміновані команди перевірки,
• та явні поверхні стану.

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

Як виражати модельно-агностичні контракти

Не пишіть інструкції як синтаксис команд одного інструменту. Пишіть їх як очікування поведінки та очікувані стани. Для специфіки інструментів надавайте приклади для кожного інструменту як приклади, а не як єдині визначення.

Наприклад: Використовуйте цей розділ, щоб уникнути прив’язки інструкцій до синтаксису та зберегти очікування поведінки стабільними в різних інструментах.

• «Не виконуйте команди, які змінюють прихований стан без плану відкату.»
• потім опціонально:
  • «Для Git використовуйте стандартні команди в режимі рев’ю.»
  • «Для локальних API використовуйте явні кінцеві точки.»

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

Операційно безпечні типові значення

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

• явні виключення,
• явні області,
• явні шляхи оновлення,
• та явні повідомлення про відмови.

Практична лабораторна робота: спроєктуйте дворівневий bootstrap для цього модуля

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

Щоб зберегти це корисним поза навчальним середовищем, цей скрипт-парсер повинен бути детермінованим: він читає repo-contract.md, видобуває лише маркери рівнів L0–L3, перевіряє кожен зазначений файл/шлях відносно кореня репозиторію та виходить із чітким, машинно-перевірним кодом. Перевірка навмисно вузька, щоб вона ловила застарілі посилання рано й не претендувала на валідацію кожного довільного рядка в контрактному файлі. Коли шлях проходить, вона виводить OK EXISTS <шлях>. Коли шлях відсутній, вона виводить MISSING <шлях>. Коли сам маніфест контракту відсутній, вона видає MISSING_FILE repo-contract.md. Код виходу — це контракт, який ви можете безпосередньо підключити до воріт CI або перевірок перед комітом.

1. Створіть repo-contract.md з явними посиланнями на рівні, використовуючи парсовний формат, який можна надійно аналізувати за допомогою awk і валідувати як контракт перед будь-якою мутацією вмісту.

# Repository Run Contract

- L0: AGENTS.md
- L1: CLAUDE.md
- L2: .claude/rules/
- L3: src/content/docs/ai/ai-engineering-foundations/module-2.2-repository-engineering-for-agents.md

2. Створіть scripts/print-run-contract.sh з цією орієнтованою на парсер версією, зберігаючи суворі виводи та детерміновані коди виходу, щоб кожна відмова була видимою перед початком виконання патчу.

#!/usr/bin/env bash
set -euo pipefail # суворе виконання оболонки тримає перевірки контракту детермінованими для запобіжників перед записом у цій лабораторній роботі

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
REPO_CONTRACT="${ROOT_DIR}/repo-contract.md" # стабільний шлях маніфесту, спільний для всіх перевірок

if [[ ! -f "${REPO_CONTRACT}" ]]; then
  echo "MISSING_FILE repo-contract.md" >&2
  exit 2
fi

declare -a refs
mapfile -t refs < <(
  awk '/^- [Ll][0-3]:[[:space:]]*/ {gsub(/^- [Ll][0-3]:[[:space:]]*/, "", $0); print $0}' "${REPO_CONTRACT}"
)

missing=0
for ref in "${refs[@]}"; do
  if [[ -e "${ROOT_DIR}/${ref}" ]]; then
    echo "OK EXISTS ${ref}"
  else
    echo "MISSING ${ref}"
    ((missing += 1))
  fi
done

if (( missing > 0 )); then
  echo "contract_check: FAILED with ${missing} missing references" >&2
  exit 1
fi

echo "contract_check: PASSED"

3. Встановіть одну явну політику застарілих правил:

Перед будь-яким кроком запису завдання запустіть scripts/print-run-contract.sh. Успіх визначається як вихід 0, рівно один contract_check: PASSED і кожен запис контракту, що відображається як OK EXISTS. Відмова повинна негайно зупинити виконання:

• Якщо repo-contract.md відсутній, скрипт виходить із кодом 2 з MISSING_FILE repo-contract.md.
• Якщо щонайменше одне посилання контракту застаріле, скрипт виходить із кодом 1, виводить один або більше рядків MISSING <шлях> і виводить contract_check: FAILED with N missing references. В обох випадках завдання не повинно продовжуватися, доки посилання не буде виправлено і скрипт не стане чистим. Ця семантика відмови є навмисною: сам контракт стає передумовою, а не посмертною нотаткою. Ви все ще можете запускати редагування патчів після того, як скрипт пройде, але не раніше.

Чому це сильніший патерн, ніж зіставлення рядків: рядкові перевірки легко пройти з дрейфом форматування. парсинг примусово вимагає, щоб сам формат контракту розумівся верифікатором, тому кожен рядок під L0–L3 валідується узгоджено. Це та сама причина, чому cold-start.sh використовує scripts/services-up, AGENTS.md та поставу API перед виконанням завдання: кожна фаза видає машинно-зчитувані передумови перед мутацією.

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

Очікувана стенограма відмови, коли CLAUDE.md зникає: Короткий запуск відмови повинен виглядати так:

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

$ scripts/print-run-contract.sh
MISSING CLAUDE.md
contract_check: FAILED with 1 missing references

Якщо сам контрактний файл видалено, стенограма повинна виглядати так:

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

$ scripts/print-run-contract.sh
MISSING_FILE repo-contract.md

Обидві стенограми є очікуваними шляхами відмови під час воріт перед записом, і обидві повинні блокувати автоматизоване виконання патчу до виправлення.

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

Виклик проєктування: уникнення хибної безпеки в інструкціях

Хибно-безпечна інструкція — це та, яка виглядає суворою, але не зупиняє поганих результатів, особливо коли вона визначає поведінку без визначення детермінованого відновлення, воріт валідації та чіткої обробки відмов. Це трапляється, коли:

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

Використовуйте цю аудиторську фразу під час рев’ю будь-якого інструкційного рівня:

«Чи можна порушити це правило, не проваливши перевірку?»

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

Перевірка знань

1) Яке твердження найкраще описує прогресивне розкриття для читабельності репозиторію?

Яке твердження найкраще описує прогресивне розкриття для читабельності репозиторію?

A) Розмістити всі інструкції в одному файлі, щоб агенти ніколи не мусили перестрибувати. B) Відокремити короткоживучі деталі від стабільних контрактів, щоб агенти могли завантажувати правильний рівень першим. C) Тримати все в згенерованих логах, тому що вони завжди актуальні. D) Зберігати все в коментарях PR, щоб це завжди було видно.

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

2) Який рівень повинен містити високочастотні операційні політики?

Який рівень повинен містити високочастотні операційні політики?

A) Один кореневий файл AGENTS з кожним можливим обмеженням, незалежно від тривалості життя. B) Багаторівневі обмежені файли плюс стабільна коренева мапа, яка посилається на них. C) Лише ефемерні промпти завдань, які скидаються щосесії. D) Лише згенерований журнал змін.

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

3) Чому структура docs/ вважається системою записів у цьому модулі?

Чому структурована `docs/` вважається системою записів?

A) Тому що вона може зберігати всі інструкції агента в сирому двійковому форматі. B) Тому що це перше місце, яке кожен агент читає автоматично. C) Тому що вона може містити довговічні, придатні для рев’ю та версіоновані інструкції, на які можна посилатися й переглядати навмисно. D) Тому що вона вимагається кожною родиною моделей і автоматично замінює всі правила.

Правильна відповідь: C, тому що docs/ забезпечує довговічну структуру, відстежувані оновлення та придатність для рев’ю. A неправильна, тому що модель вмісту залишається людино-читабельним текстом, а не двійковими інструкціями. B неправильна, тому що bootstrap може включати інші файли, а перше завантаження не гарантує повноти. D неправильна, тому що заміна є контекстно-специфічною та небезпечною.

4) Яка найточніша інтерпретація «репозиторій відповідає» в цьому контексті?

Яка найточніша інтерпретація «репозиторій відповідає»?

A) Репозиторій завжди повинен виводити дружні повідомлення. B) Репозиторій повинен показувати статус, перевірки та обмеження, які можуть спостерігати агенти до і після дії. C) Репозиторій повинен блокувати всі автоматизовані редагування. D) Репозиторій повинен уникати сигналів середовища виконання, щоб зменшити шум.

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

5) Який елемент найкраще відповідає антипатерну застарілого правила?

Який елемент найкраще відповідає антипатерну застарілого правила?

A) Правило, що переглядається щотижня, з володінням та нотатками про міграцію. B) Команда, скопійована в один файл роки тому й ніколи не оновлена, незважаючи на змінений інструментарій. C) Кореневий файл, який посилається на обмежені документи для глибших деталей. D) Промпт завдання, який посилається на поточну гілку issue.

Правильна відповідь: B, тому що застарілі скопійовані правила вводять агентів в оману та підривають довіру. A неправильна, тому що це означає активний супровід. C неправильна, тому що це підтримує виявлюваність і свіжість. D неправильна, тому що промпти завдань є тимчасовими, а не застарілою базовою політикою.

6) У моделі проєктування цього модуля, що слід уникати розміщувати в постійно завантажуваному файлі?

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

A) Стабільне управління та обмеження гілок. B) Нотатки одноразових issues. C) Посилання на специфічну для модуля документацію. D) Основні перевірки виконання.

Правильна відповідь: B, тому що нотатки одноразових issues стають застарілими й повинні бути локальними для завдання. A неправильна, тому що стабільні обмеження належать до завжди завантажуваних посилань. C неправильна, тому що посилання на область є високоцінними шляхами виявлюваності. D неправильна, тому що основні перевірки є центральними для безпечної роботи й повинні бути виявлюваними.

7) Яке твердження відображає найкращий патерн володіння для інструкційних файлів?

Яке твердження відображає найкращий патерн володіння для інструкційних файлів?

A) Лише одна людина володіє кожним інструкційним файлом глобально. B) Володіння не потрібне, якщо файли є описовими. C) Кожен файл має область, власника та шлях оновлення, причому вкладені файли перевизначають конфлікти. D) Кореневого володіння достатньо для всіх обмежених тек.

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

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

• Проведіть аудит кореневого bootstrap вашого репозиторію, перелічивши перші п’ять файлів, завантажених перед будь-якою роботою над завданням, потім позначте, які є стабільними L0, а які — обмеженими L1.
• Побудуйте «Аркуш читабельності репозиторію» в одному файлі Markdown з чотирма рівнями, посиланнями та однією командою перевірки здоров’я для кожного рівня.
• Додайте один запис docs/ як довговічний контракт для виконання агента та один явний список виключень для згенерованих артефактів.
• Визначте короткий цикл зворотного зв’язку про відмову: визначте одну кінцеву точку або команду, яка повинна запускатися після кожного завдання, і поясніть, як вона змінює наступні дії.
• Складіть правило ротації застарілості, яке призначає власника та ритм для кожного файлу bootstrap та обмеженого інструкційного файлу.

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

Наступний модуль незабаром.

Джерела

• Harness engineering (OpenAI)
• Give Claude context with CLAUDE.md (Anthropic Support)
• Claude Code memory model (Anthropic docs)
• Custom instructions with AGENTS.md — Codex (OpenAI Developers)
• AGENTS.md project format
• AGENTS.md repository (GitHub)
• AGENTS.md example source file
• KubeDojo CLAUDE.md
• KubeDojo module-quality rules
• KubeDojo new-content checklist
• Starlight sidebar architecture
• Starlight frontmatter reference
• Astro routing guide
• KubeDojo configuration file
• scripts/print-run-contract.sh у цьому модулі навмисно керується контрактом: repo-contract.md є кореневим контрактним файлом, а його посилання — це канонічний список, який скрипт перевіряє перед запуском.