Як автоматично підтримувати AGENTS.md актуальним у dox

Чому ваш AGENTS.md неправильний уже через три тижні

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

Агент читає цей файл і вважає його достовірним. Саме це створює проблему. У репозиторії без AGENTS.md агент спочатку перевіряє структуру перед виконанням дій. У репозиторії з неправильним AGENTS.md він припиняє перевірку, тому що вже має відповідь. Він виконує команду, указанy у вашому файлі, shell повертає Missing script: "test", і тепер агент починає вгадувати. Часто він змінює package.json, щоб додати скрипт, який обіцяла ваша документація. Застарілий файл не просто непомітно перестав працювати. Він спричинив небажану зміну.

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

Що таке dox і чим він не є

dox — це один файл Markdown. Репозиторій має адресу agent0ai/dox, він поширюється за ліцензією MIT, а станом на 11 August 2026 весь проєкт складається з одного файлу AGENTS.md розміром 3906 байт, README, LICENSE і двох зображень. Пакета для встановлення та середовища виконання немає.

Це важливо, оскільки слово generator створює враження програми, яка аналізує ваш код. Насправді ваш код ніхто не аналізує. dox — це контракт, який читає ваш coding agent: генератором є агент, а dox — це набір інструкцій, який визначає, коли агент має читати документацію, коли переписувати її та якою має бути структура кожного документа.

Файл має десять розділів, і два з них виконують основну роботу. "Read Before Editing" вказує агенту пройти від кореня репозиторію до кожного шляху, який він планує змінити, і в поточному сеансі прочитати кожен AGENTS.md на кожному такому шляху, не покладаючись на пам’ять. "Update After Editing" вказує, що кожна змістовна зміна потребує проходження DOX, тобто виконання кроку оновлення документації до завершення завдання. Під час цього проходження оновлюється найближчий документ-власник, якщо змінилися призначення, структура, робочий процес, дозволи або користувацькі налаштування.

Решта визначає структуру. Дочірній AGENTS.md має типовий порядок розділів: Purpose, Ownership, Local Contracts, Work Guidance, Verification і Child DOX Index. Кореневий файл містить загальні правила проєкту та верхньорівневий Child DOX Index, за яким агент знаходить дочірні документи. "Closeout" — це контрольний список, який агент виконує наприкінці завдання: повторно перевіряє змінені шляхи за ланцюжком, оновлює найближчі документи-власники, оновлює кожен зачеплений індекс, видаляє суперечності, запускає наявну перевірку та повідомляє, які документи він навмисно не змінював.

Pin dox до одного коміту, а не до main

У репозиторії немає тегів і релізів, тому немає номера версії, який можна зафіксувати. Замість цього зафіксуйте коміт. Поточний AGENTS.md — це коміт f34ec7ad1055d3393887e5a2670e8cb7320c9165 від 1 August 2026.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

Команда wc -c має вивести 3906. Інше значення означає, що ви отримали не той файл, який описано в цьому посібнику. Прочитайте його, перш ніж довіряти його вмісту. Якщо ви неправильно введете hash коміту, -f зупинить curl із curl: (22) The requested URL returned error: 404 і не запише жодного вмісту, а wc -c потім виведе 0. Обрізаний файл гірший за відсутність файлу, оскільки агент виконує лише частину контракту, не знаючи про це.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

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

Потім у репозиторії попросіть агента виконати перший прохід. У README наведено точне формулювання:

Initialize DOX tree for this project now.

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

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

Кожен файл у виводі find має бути зазначений десь вище в Child DOX Index. Якщо дочірній документ не згадано в жодному індексі, агент може його пропустити, оскільки саме індекс допомагає йому знаходити документи, які не розташовані безпосередньо на шляху обходу.

Що dox може бачити, а чого не може знати

Агент, який будує ваше дерево, читає репозиторій. Тому до інвентарю може потрапити все, що є в репозиторії: структура каталогів, маніфести пакетів і lock-файли, скрипти в package.json, Makefile або pyproject.toml, файли CI workflow, Dockerfiles, entry points і CODEOWNERS, якщо він у вас є. Інвентар, побудований на цих даних, справді самопідтримується. Коли пакет переміщується, наступний прохід перемістить і рядок, який його описує.

Усе наведене нижче потрібно вказати вручну, оскільки цього немає в репозиторії:

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

dox знає це про себе. У його власних правилах зазначено, що Work Guidance має відповідати поточним стандартам проєкту або інструкціям користувача, а якщо їх ще немає, розділ потрібно залишити порожнім. Розділ Verification має описувати наявну перевірку. Тому, якщо в репозиторії немає тестового фреймворку, цей розділ залишається порожнім, доки він не з’явиться. Згенерований файл, який вигадує стандарт, гірший за порожній розділ, оскільки агент тоді почне забезпечувати дотримання цієї вигадки.

Не змішуйте написані вручну правила з автоматично згенерованим описом

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

Потрібні два механізми, і використовуйте обидва.

По-перше, перенесіть довговічні правила в інший файл. Проєктні рішення та обґрунтування мають зберігатися в DESIGN.md, підготовленому для агента, а нотатки для людей — там, де ви виокремлюєте HUMAN.md з AGENTS.md. У AGENTS.md залишаються опис структури та локальні контракти. Саме ця частина має змінюватися разом зі змінами в коді.

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

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

Коментарі Markdown не відображаються на сторінці, але агент їх читає. Тепер зробіть збереження цього блока контрольованим, щоб під час проходу, який його видалить, перевірка завершувалася помітною помилкою. Виконуйте це в CI (continuous integration) для кожного pull request:

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

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

Генеруйте зміни в pull request, а не за розкладом

Найкращий момент для оновлення документа — це коміт, через який документ став неправильним. Додайте етап DOX до того самого pull request, у якому змінюється структура, і diff залишиться достатньо малим для повноцінного перегляду.

Перевірка, яка блокує злиття та забезпечує це правило:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

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

Розклад — це резервний механізм, а не основний. Щотижневе завдання виявляє те, що ніхто не помітив у branch: файли, переміщені під час rebase, пакет, видалений під час merge, або документ, у якому вказано каталог, що більше не існує. Запускайте його на невеликому сервері — на тому самому, який можна використати, щоб запустити coding agent на VPS, — і налаштуйте його на створення pull request, а не на push у main.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

Цей коментар навмисно залишено як заповнювач. Кожен agent має власний CLI (інтерфейс командного рядка) і власний non-interactive flag, а команда, скопійована з вебсторінки та несумісна з вашою версією, завершується помилкою всередині cron, де ніхто не побачить цю помилку. Додайте потрібну команду та один раз запустіть script вручну, перш ніж налаштовувати розклад. Важливий також || exit 0: git commit завершується з ненульовим кодом через nothing to commit, working tree clean, коли tree уже актуальне, а в середовищі set -e це буде сприйнято як помилка успішного запуску.

Кожен запуск потребує tokens, оскільки правило "Read Before Editing" змушує agent щоразу читати весь ланцюжок під час виконання завдання. Це компроміс, за яким варто стежити, якщо ви вже підраховуєте вартість запусків вашого agent.

Монорепозиторії: багато контрактів, один індекс

Один кореневий файл AGENTS.md у репозиторії із сорока пакетами створює diff регенерації, який ніхто не читає, і документ, що здебільшого не стосується поточного завдання агента. Відповідь dox — Child DOX Index: кореневий файл містить загальні правила репозиторію та посилання на дочірні файли, а кожна стабільна межа має власний файл. Структуру цього дерева та інструменти, які взагалі читають вкладені файли, описано в вкладених файлах AGENTS.md для монорепозиторіїв.

dox змінює поверхню перевірки. Pull request, який змінює packages/api, має створювати diff документації лише всередині packages/api:

git diff --stat -- '*AGENTS.md'

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

Переглядайте diff як код

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

• команду, яку тепер наведено у файлі та яку слід самостійно виконати перед злиттям. Вигадані інструкції зі збирання — найпоширеніша помилка.
• видалений рядок, який містив важливу логіку або пояснював намір. Додавати легко. Саме під час видалення втрачається зміст.
• абсолютний шлях, hostname, внутрішній URL або будь-який рядок, схожий на облікові дані
• запис в inventory для об’єкта, якого більше не існує; ls дає змогу перевірити це за секунду

Потім перевірте розмір за допомогою wc -l AGENTS.md. Файл у корені, що містить понад двісті рядків, слід розділити. Уся цінність цього ланцюжка в тому, що агент читає невелику релевантну частину, а не все одразу.

Коли все ламається

Прохід видалив ваш блок інструкцій. Перевірка diff вище виводить видалені рядки. Відновіть файл зі стану в точці розгалуження за допомогою git restore --source=origin/main AGENTS.md, а потім повторно запустіть прохід із точнішою інструкцією, у якій зазначено розділи, які можна змінювати.

Обидві гілки повторно згенерували файл. У файлі з’являються CONFLICT (content): Merge conflict in AGENTS.md і маркери конфлікту <<<<<<< HEAD. Не редагуйте маркери вручну. Файл генерується автоматично, тому правильне розв’язання — повторно виконати прохід над об’єднаним деревом.

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

У дереві з’явилися дочірні елементи, які ніхто не проіндексував. Порівняйте вивід find . -name AGENTS.md із записами індексу в батьківських документах. Дочірній елемент, на який не посилається жоден індекс, агент може просто пропустити.

Коли генератор є надмірним

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

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

FAQ

Чи потрібно щось встановлювати, щоб використовувати dox?

Ні. dox — це один файл Markdown із ліцензією MIT, і станом на 11 August 2026 у репозиторії немає пакета та релізів. Скопіюйте його вміст до AGENTS.md вашого проєкту, після чого ваш coding agent виконуватиме правила з цього файла. Зафіксуйте коміт, який ви скопіювали, f34ec7ad1055d3393887e5a2670e8cb7320c9165 на момент написання, і вкажіть його у повідомленні коміту, щоб пізніше можна було визначити, на якій версії правил було побудовано ваше дерево.

Як запобігти видаленню власноруч написаних правил під час повторної генерації?

Відокремлюйте задум від інвентарю. Обґрунтування, яке має зберігатися, розміщуйте в окремому документі, а все, що повинно залишатися всередині AGENTS.md, — у позначеному блоці. Потім перевіряйте цей блок у CI: витягніть його з гілки та з origin/main за допомогою sed, порівняйте їх через diff і завершіть збірку помилкою за будь-якої відмінності. Після цього зміни схвалює або скасовує людина, а не пропускає їх непомітно всередині великого diff.

Як часто потрібно повторно генерувати AGENTS.md?

У pull request, який робить його неправильним. Структурна зміна та її документація мають входити до одного diff, оскільки лише в цей момент хтось має достатній контекст для перевірки обох. Запланований щотижневий запуск є резервним засобом для дрейфу, який пройшов повз перевірку гілки, і він має відкривати pull request, а не виконувати commit у main.

Чи мають команди збірки бути в кореневому AGENTS.md чи в дочірньому файлі?

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

Чи варто використовувати dox у невеликому репозиторії?

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