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

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

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

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

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

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

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

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

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

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

Зафіксуйте 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. Інше значення означає, що ви отримали не той файл, який описано в цьому посібнику, тому прочитайте його, перш ніж йому довіряти. Якщо ви неправильно введете хеш коміту, -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 може побачити, а чого не може знати

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

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

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

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

Не змішуйте рукописні пояснення зі згенерованим inventory

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

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

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

По-друге, виділіть маркерами пояснення, які мають залишатися в 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 не відображаються на сторінці, але агент їх читає. Тепер зробіть збереження цього блока перевірюваним, щоб pass, який його видалить, явно завершувався помилкою. Запускайте цю перевірку в 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, якщо блок не змінено. Будь-який вивід означає, що pass перезаписав текст, який належить людині. У такому разі людина має схвалити зміни або скасувати їх. Перевірка працює без потреби комусь про неї пам’ятати.

Повторно генеруйте під час pull request, а не за таймером

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

Ось blocking check, який це забезпечує:

#!/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 (command line interface) і власний non-interactive flag. Команда, скопійована з вебсторінки, яка не відповідає вашій версії, завершується помилкою всередині cron, де ніхто не побачить помилку. Заповніть її та один раз запустіть скрипт вручну перед додаванням до розкладу. Значення || 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 документації легко схвалити, не прочитавши його. Так у реліз потрапляє неправильний файл. Читайте його з такою самою підозрою, як згенерований код, і перевіряйте чотири речі.

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

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

Коли щось виходить з ладу

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

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

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

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

Коли генератор є зайвим

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

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

FAQ

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

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

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

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

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

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

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

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

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

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