Вкладені AGENTS.md для монорепозиторію
Один root AGENTS.md застаріває й витрачає контекст на зайві каталоги. Дізнайтеся, як розкласти правила по сервісах і залишити спільні в корені.
Що означають вкладені AGENTS.md у монорепозиторії
Вкладені AGENTS.md у монорепозиторії означають, що в корені репозиторію розміщено один невеликий файл, а в каталозі кожного сервісу — ще один файл. У кореневому файлі міститься кілька правил, чинних усюди, а також карта розташування інших файлів. У файлі кожного сервісу містяться команди та правила, що діють лише в цьому каталозі. Агент, який редагує services/worker/queue.py, потім читає кореневий файл і файл worker та не витрачає контекст на front end, якого він не змінюватиме.
Нічого встановлювати не потрібно. AGENTS.md — це домовленість, і upstream project прямо це зазначає:
AGENTS.md — це звичайний Markdown. Використовуйте будь-які потрібні заголовки; агент просто аналізує наданий вами текст.
Саме тому цей підхід варто опанувати належним чином. Формат не зміниться несподівано. Проблеми виникають через розміщення та супровід, і за обидва аспекти відповідаєте ви.
Чому один великий кореневий AGENTS.md перестає працювати?
Один файл AGENTS.md на 600 рядків у корені репозиторію, де містяться web-застосунок, background worker і каталог Terraform, має чотири окремі проблеми.
Він застаріває, бо ніхто за нього не відповідає. Інженер, який перейменовує тестовий скрипт у apps/web, редагує файли в apps/web. Кореневого AGENTS.md немає в цьому diff, тому жоден reviewer не бачить невідповідності. Через шість тижнів файл описує крок збірки, якого вже не існує, а людина, яка спричинила проблему, уже забула про цю зміну.
Він витрачає контекст під час кожного завдання. Ці файли завантажуються на початку сесії, ще до того, як agent дізнається, що саме ви попросите зробити. У документації Claude Code наведено конкретне обмеження: «для кожного файла CLAUDE.md рекомендовано не перевищувати 200 рядків. Довші файли споживають більше контексту та знижують дотримання інструкцій». Codex припиняє об’єднувати файли інструкцій, коли їхній загальний розмір досягає 32 KiB, тобто значення за замовчуванням project_doc_max_bytes. Кореневий файл, що документує чотири сервіси, витрачає цей бюджет на три з них під час кожного завдання.
Інструкції починають суперечити одна одній. Каталог web потребує pnpm test. Worker потребує pytest -q. В одному файлі кожне правило правильне лише в окремих випадках, тому agent має вгадувати, яке з них застосовується. У документації Claude Code описано результат: «якщо дві інструкції суперечать одна одній, Claude може довільно вибрати одну». Розділення файла не вилучає інше правило з контексту. Claude Code об’єднує кожен завантажений файл інструкцій, а не замінює один файл іншим. Тому кореневий файл завжди залишається в контексті, а коли agent відкриває файли і в apps/web, і в services/worker, обидва файли для цих каталогів одночасно потрапляють у контекст. Файл для окремого каталогу прив’язує кожне правило до каталогу, яким воно керує. На початку файла вкажіть назву каталогу, як у наведених нижче прикладах із # apps/web. Тоді кожна команда й надалі однозначно вказує, де вона застосовується, навіть коли одночасно завантажено кілька файлів. Якщо правило, яке ви точно сформулювали зрозуміло, все одно пропускається, корисніше розібратися з причинами, через які інструкція не спрацьовує, ніж переписувати формулювання вчетверте.
Він заповнюється відомостями, які agent може прочитати з коду. Дерево каталогів, список залежностей, короткий опис призначення кожного пакета. Перевірка /doctor у Claude Code призначена саме для вилучення таких відомостей. Вона «вилучає вміст, який Claude може визначити з codebase, наприклад структуру каталогів, списки залежностей і огляд архітектури», та залишає «проблемні місця, обґрунтування й домовленості, що відрізняються від типових налаштувань інструментів». Це найкращий відомий мені критерій, щоб визначити, чи варто взагалі додавати певний рядок у файл.
Чи читає агент root-файл чи лише найближчий?
Саме тут багато хто неправильно розуміє модель, тому варто навести upstream-конвенцію, а не переказувати її:
Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions.
А щодо конфліктів:
The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.
Для багатьох "takes precedence" означає, що root-файл ігнорується. Це не так. В інструментах, які реалізують цю конвенцію, читаються всі файли на шляху від root репозиторію до робочого каталогу, після чого їх об’єднано. Найближчий файл має перевагу лише тоді, коли два файли містять різні вказівки щодо одного питання.
Codex прямо описує цей механізм: "Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance." Claude Code проходить тим самим шляхом. На початку сесії він читає "every AGENTS.md and .claude/AGENTS.md in your working directory and the directories above it", а в документації модель завантаження описано однозначно: "All discovered files are concatenated into context rather than overriding each other." Каталоги нижче робочого каталогу працюють інакше: Claude Code завантажує AGENTS.md підкаталогу за потреби, "when Claude opens a file there with the Read tool."
З цього випливають два практичні наслідки. Root-файл є префіксом кожної сесії в репозиторії, тому кожен його рядок слід розглядати як рядок, за який ви платите сто разів на тиждень. Файл для окремого каталогу не створює витрат, доки агент не відкриє файл у цьому каталозі. Тому докладні вказівки вигідно зберігати саме там.
Цю поведінку перевірено за документацією Codex і Claude Code 27 October 2026. Інструменти реалізують конвенцію дещо по-різному, і правила можуть змінюватися, тому перевірте модель завантаження для агента, який використовується у вашій команді.
Приклад структури репозиторію з трьома сервісами
repo/
AGENTS.md rules true everywhere, plus the map
apps/web/AGENTS.md TypeScript client, Vite, Vitest
services/worker/AGENTS.md Python queue consumer, pytest
infra/AGENTS.md Terraform and the deploy scriptsКореневий файл навмисно короткий. У ньому вказано, де шукати потрібну інформацію, і містяться лише правила, чинні в кожному каталозі.
# AGENTS.md
This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.
- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts
## Rules for the whole repository
- The package manager is `pnpm`. `npm install` writes a second lockfile
that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
`schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
in the same commit.Файл для окремого каталогу містить деталі. Його обсяг може відповідати складності цього каталогу.
# apps/web
Browser client. Vite and React, TypeScript with `strict` on.
## Commands
- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.
## Conventions
- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
because the client attaches the auth header and retries on 429.
## Traps
- `pnpm build` does not type check. Vite strips the types instead of
checking them, so a broken type still produces a green build.
Run `pnpm typecheck` as a separate step.Файл worker має таку саму структуру, але інший вміст: команду встановлення, pytest -q, пояснення, чому consumer має залишатися ідемпотентним, і міграцію, яку потрібно виконати до успішного проходження тестів. У файлі infra задають правила, що не дають агенту завдати шкоди. Ніколи не запускайте terraform apply. Виконайте terraform plan і на цьому зупиніться. Також укажіть уже налаштований backend стану, щоб агент не намагався ініціалізувати новий.
Зверніть увагу, чого немає в жодному з цих файлів: опису призначення кожного сервісу. Це призначено для людей. Upstream проводить таку саму межу: «файли README.md призначені для людей: короткі інструкції з запуску, описи проєктів і рекомендації для учасників», тоді як AGENTS.md містить «додатковий, іноді докладний контекст, потрібний агентам кодування: кроки збирання, тести та правила». Розподіл між AGENTS.md і README для людей послідовно розглядає цю межу, а файл DESIGN.md, у якому записано причини структури коду присвячено третьому файлу — тому, що пояснює рішення, а не команди.
Хто оновлює файл, коли змінюється код?
У кореневому файлі має бути одне правило: той, хто змінює код у каталозі, оновлює AGENTS.md цього каталогу в тому самому коміті.
Це працює з механічної, а не культурної причини. Файл для конкретного каталогу міститься в тому самому diff, що й код, тому рев’юер pull request бачить їх одночасно. Кореневий файл стосується всіх, а отже, фактично не належить нікому. Він також ніколи не входить до diff, який хтось уже переглядає.
Підкріпіть це правило перевіркою pull request. Вона знаходить найближчий AGENTS.md вище кожного зміненого файлу, а потім повідомляє, якщо цей файл не було змінено.
#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)
nearest_doc() {
d=$(dirname "$1")
while [ "$d" != "." ]; do
if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
d=$(dirname "$d")
done
echo "AGENTS.md"
}
printf '%s\n' "$changed" | while read -r f; do
[ -n "$f" ] || continue
case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
doc=$(nearest_doc "$f")
printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
echo "note: $f changed but $doc was not updated"
doneУ гілці, де було перероблено API client без змін у документації, результат має такий вигляд:
note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updatedЗалиште це попередженням, а не помилкою. Жорстке блокування привчає додавати до файлу порожній рядок, щоб CI став зеленим. Файл, змінений лише для задоволення робота, менш цінний, ніж повна відсутність файлу. Попередження дає рев’юеру запитання, яке потрібно поставити. Саме це на практиці й працює.
Як виявити застарілий AGENTS.md?
Сьогодні можна виконати дві перевірки, а під час сесії ви побачите одну характерну ознаку.
Порівняйте вік кожного файла з віком коду, який він описує. %cs виводить дату коміту у форматі YYYY-MM-DD.
for f in $(git ls-files '*AGENTS.md'); do
d=$(dirname "$f")
printf '%s doc:%s code:%s\n' "$f" \
"$(git log -1 --format=%cs -- "$f")" \
"$(git log -1 --format=%cs -- "$d")"
doneapps/web/AGENTS.md doc:2026-02-11 code:2026-08-07
services/worker/AGENTS.md doc:2026-07-29 code:2026-08-09
infra/AGENTS.md doc:2026-08-01 code:2026-08-01Дата документа на шість місяців старіша за дату коду не доводить, що файл неправильний. Вона лише показує, який файл потрібно прочитати першим. Цього достатньо для перевірки, яка триває одну секунду.
Перевірте шляхи, яких більше не існує. Документація застаріває дуже конкретним способом: вона продовжує описувати видалений код. У цих файлах кожен шлях записано в backticks, тому їх легко витягнути й перевірити.
grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
[ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
doneЧитайте вивід, а не підключайте цю перевірку до CI. Вона також позначає glob-вирази, як-от src/**/*.ts, і будь-яку URL-адресу, узяту в лапки, оскільки і ті, і ті містять скісну риску, але не є файлами на диску. У Claude Code v2.1.283 або новішій версії /doctor prompt-audit виконує подібну перевірку автоматично: шукає «посилання на файли або команди, яких не існує», а також файли, що суперечать один одному, за замовчуванням охоплює ваші файли AGENTS.md і нічого не змінює, доки ви не попросите застосувати запропоновані зміни.
Ознака під час сесії. Агент читає файл, намагається відкрити src/api/client.ts, оскільки файл наказує йому це зробити, а інструмент повертає:
No such file or directoryТоді агент робить логічний висновок і пише власну оболонку fetch. У цьому полягає реальна вартість застарілого файла. Агент не ігнорує вашу документацію. Він дотримується її, переходить до шляху, який видалили три місяці тому, і повторно створює код, який у вас уже є. Skill на кшталт Ponytail, який змушує агента обмежуватися найменшою робочою зміною, зменшує ймовірність такого повторного створення, але не може знайти helper, на який ваш файл посилався за неправильним шляхом.
Чи читає Claude Code файли AGENTS.md?
Так, починаючи з Claude Code v2.1.277. Точне правило важливе, оскільки від нього залежить вкладена структура. Перевірено за документацією 27 October 2026: «Claude Code може читати AGENTS.md як інструкції вашого проєкту, тому репозиторій, уже налаштований для інших coding agents, працює без додавання CLAUDE.md, імпорту або налаштування». Значення Project instructions за замовчуванням, claude-md-or-agents-md, читає «ваші файли AGENTS.md, якщо у вашому робочому каталозі або вище немає CLAUDE.md чи CLAUDE.local.md». Вкладені файли також враховуються: Claude читає AGENTS.md підкаталогу «коли Claude відкриває файл у ньому за допомогою інструмента Read», якщо «цей підкаталог не має жодного з трьох власних файлів CLAUDE.md». Ці три файли — CLAUDE.md, .claude/CLAUDE.md і CLAUDE.local.md. Тому особистого CLAUDE.local.md у apps/web достатньо, щоб припинити завантаження apps/web/AGENTS.md.
Це перетворює стару пораду розміщувати CLAUDE.md поруч із кожним AGENTS.md на пастку. Якщо у вашому робочому каталозі або вище є AGENTS.md і CLAUDE.md чи CLAUDE.local.md, документація каже, що Claude читає «лише ваші файли CLAUDE.md». .claude/CLAUDE.md працює так само. Один супровідний файл у корені з одним рядком, специфічним для Claude, приховує кожен AGENTS.md на цьому шляху. Особистий CLAUDE.local.md діє так само. Якщо ви хочете зберегти один із них, введіть /config і встановіть для Project instructions значення claude-md-and-agents-md. Воно читає обидва файли: спочатку CLAUDE.md кожного каталогу, потім AGENTS.md.
Сам номер версії не підтверджує, що все запрацювало. Потрібна версія v2.1.277 або новіша. Однак до v2.1.281 деякі сесії, зокрема сесії на Amazon Bedrock або з вимкненою телеметрією, читали лише файли CLAUDE.md. У деяких випадках перша сесія після оновлення з v2.1.276 або старішої версії також пропускала AGENTS.md: документація каже, що «Claude читає AGENTS.md, починаючи з наступної сесії». Тому перевіряйте саму сесію. В інтерактивній сесії Claude Code виводить рядок на кшталт no CLAUDE.md found; AGENTS.md loaded:, після якого зазначається шлях. У поточних версіях /memory показує файл у списку. До v2.1.280 /memory і /context не показували AGENTS.md, який Claude прочитав безпосередньо. Тому в таких версіях запитайте Claude, що містять його інструкції проєкту.
Форма з імпортом залишається правильною там, де Claude не може безпосередньо читати AGENTS.md: у старішій версії; у сесії до v2.1.281 на Amazon Bedrock або з вимкненою телеметрією; у сесії, де вимкнено вбудований plugin, який його читає; або в проєкті, де зберігається CLAUDE.md, а для Project instructions встановлено claude-md. Додайте це до services/worker/CLAUDE.md:
@AGENTS.md
## Claude Code
Use plan mode for changes under `services/worker/migrations/`.Форма із symlink підходить, коли не потрібно додавати нічого специфічного для інструмента.
git ls-files '*AGENTS.md' | while read -r f; do
ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.mdln не виводить нічого в разі успіху, тому перевірте список: apps/web/CLAUDE.md -> AGENTS.md. Потім запустіть сесію та виконайте /context. Завантажені файли з’являться в розділі Memory files. У Windows для створення symlink потрібні права Administrator або Developer Mode. Git перевіряє закомічений symlink як звичайний текстовий файл, якщо не ввімкнено core.symlinks. У такому разі цей клон міститиме замість ваших інструкцій однорядковий CLAUDE.md. Якщо хтось, хто клонує репозиторій, працює у Windows, використовуйте імпорт @AGENTS.md. Якщо ви налаштували будь-який із цих обхідних варіантів до того, як Claude Code почав самостійно читати AGENTS.md, його можна залишити. Документація каже, що збереження імпорту «ніколи не змушує Claude читати AGENTS.md двічі», а symlink для CLAUDE.md читається один раз.
Є ще одна особливість. Після /compact кореневий для проєкту CLAUDE.md повторно читається з диска, але вкладені файли в підкаталогах не вставляються повторно. Claude Code завантажує їх за потреби — наступного разу, коли агент працює з файлом у цьому каталозі. У документації це прямо зазначено для файлів CLAUDE.md. Окремо поведінку під час compaction для AGENTS.md, прочитаного безпосередньо, не описано. Тому очікуйте однакової поведінки вкладених файлів обох назв. Якщо правило для окремого каталогу припиняє діяти в середині тривалої сесії, зазвичай причина саме в цьому. Відкриття будь-якого файлу в каталозі завантажує правило знову.
Налаштування, які вказують іншим агентам на AGENTS.md
Codex нативно читає AGENTS.md. На кожному рівні він спочатку перевіряє AGENTS.override.md. Це дає змогу створити локальне перевизначення для одного каталогу без редагування спільного файлу. Він припиняє об’єднання, коли загальний розмір досягає 32 KiB — значення за замовчуванням для project_doc_max_bytes. Це ще одна причина зберігати кореневий файл невеликим.
Aider використовує його через .aider.conf.yml із рядком read: AGENTS.md.
Gemini CLI використовує його через .gemini/settings.json із { "context": { "fileName": "AGENTS.md" } }.
Upstream документує сумісне перейменування для репозиторіїв, які досі використовують стару назву в однині: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.
У дуже великому monorepo налаштування claudeMdExcludes у Claude Code пропускає файли з батьківських каталогів за шляхом або glob-шаблоном. Це корисно, коли каталог іншої команди розташований вище за ваш. Його шаблони також застосовуються до файлів AGENTS.md, які читає Claude Code.
Чим це відрізняється від пам’яті агента або skill?
Ці механізми виглядають подібними, але виходять з ладу з різних причин. Тому важливо точно визначити, який саме механізм вам потрібен.
AGENTS.md створюєте ви, фіксуєте в git і перевіряєте в pull request. Його вміст однаковий для всіх, хто клонує репозиторій. Пам’ять агента створює агент, зберігає поза репозиторієм і використовує лише на одній машині. Документація Claude Code проводить таку саму межу: CLAUDE.md містить «інструкції та правила», які пишете ви, а auto memory містить «отримані знання та шаблони», які записує Claude. Каталог пам’яті не спільний для різних машин. Перевірка проста. Якщо факт має бути чинним для колеги після свіжого клонування репозиторію, його не можна зберігати в пам’яті. У розділі Як пам’ять агента зберігається між сеансами описано цю частину питання.
Skill — це третій механізм. Контекст з AGENTS.md завантажується в кожному сеансі, а skill завантажується лише за потреби. Документація Claude Code містить практичне правило: «Якщо запис є багатоетапною процедурою або стосується лише однієї частини кодової бази, перенесіть його до skill або правила, обмеженого шляхом». Друга частина цього речення описує саме те, що вирішує вкладений AGENTS.md. Перша частина стосується skill для агентів. Якщо та сама процедура потрібна в кількох репозиторіях, скористайтеся підходом поширити skill між репозиторіями, а не вставляйте однакові абзаци в десять різних файлів AGENTS.md.
В upstream зазначено, що «на момент написання основний репозиторій OpenAI має 88 файлів AGENTS.md». Це число саме по собі є аргументом. Великому репозиторію не потрібен більший файл. Йому потрібно більше невеликих файлів. Кожен файл має розташовуватися поруч із кодом, який він описує, і належати тому, хто востаннє змінював цей код.
FAQ
Чи замінює вкладений AGENTS.md кореневий файл чи доповнює його?
Він доповнює його. Upstream зазначає, що «пріоритет має найближчий файл». Це описує поведінку в разі конфлікту, а не те, які файли завантажуються. Codex «об’єднує файли від кореневого каталогу вниз, розділяючи їх порожніми рядками», а Claude Code об’єднує кожен файл, який знаходить під час переходу від робочого каталогу вгору, а не замінює їх. Найближчий файл має перевагу лише тоді, коли два файли містять різні вказівки щодо одного питання. Один раз запишіть спільні правила в кореневому файлі й не дублюйте їх у кожному каталозі.
Яким має бути розмір кореневого AGENTS.md?
Він має бути достатньо малим, щоб ви не заперечували проти його додавання на початку кожного запиту, який надсилаєте в цьому репозиторії, оскільки саме так і відбувається. Документація Claude Code радить орієнтуватися на менше ніж 200 рядків у кожному файлі та попереджає, що довші файли «знижують дотримання інструкцій». Codex за замовчуванням припиняє об’єднувати файли інструкцій після досягнення загального розміру 32 KiB. Якщо кореневий файл описує чотири сервіси, більша його частина буде зайвою для будь-якого окремого завдання. Перенесіть докладну інформацію до файлів у відповідних каталогах і залиште покажчик.
Як запобігти застаріванню цих файлів?
Додайте до кореневого файлу одне правило: той, хто змінює код у каталозі, оновлює AGENTS.md цього каталогу в тому самому коміті. Розміщення файлу поруч із кодом допомагає дотримуватися цього правила, оскільки така зміна потрапляє до diff того самого pull request, який уже переглядає людина. Додайте до CI попередження, яке зіставляє кожен змінений шлях із найближчим AGENTS.md над ним, і час від часу порівнюйте git log -1 --format=%cs у кожному файлі з тією самою командою, виконаною для каталогу, який він описує.
Чи читає Claude Code файли AGENTS.md?
Так, починаючи з v2.1.277. За документацією, перевіреною 27 October 2026, Claude Code за замовчуванням читає AGENTS.md, якщо у вашому робочому каталозі або вище нього немає CLAUDE.md чи CLAUDE.local.md, а також читає AGENTS.md підкаталогу, коли відкриває файл у ньому за допомогою інструмента Read і цей підкаталог не має власних CLAUDE.md, .claude/CLAUDE.md або CLAUDE.local.md. Не додавайте CLAUDE.md поруч із кожним AGENTS.md: якщо один файл розташований у робочому каталозі або вище, Claude читає лише «Your CLAUDE.md files». Якщо вам також потрібен CLAUDE.md, установіть Project instructions у значення claude-md-and-agents-md у /config або розмістіть @AGENTS.md у його першому рядку. Запустіть /memory у сесії та переконайтеся, що шлях AGENTS.md є у списку.
Куди додати правило, яке потрібне лише іноді?
Не в AGENTS.md. Цей файл завантажується в кожній сесії, тому кожен його рядок конкурує за увагу із запитом, який ви фактично ввели. Процедура з кількома кроками, потрібна час від часу, має належати до skill, який завантажується на вимогу. Правило, що стосується одного каталогу, має належати до AGENTS.md цього каталогу. Факт, який агент може безпосередньо прочитати з коду, наприклад дерево каталогів або список залежностей, не належить ні до одного, ні до іншого.