Вложенные файлы AGENTS.md в монорепозитории
Использование одного файла AGENTS.md в корне монорепозитория ведет к потере контекста и ошибкам. Узнайте, как распределить правила по директориям для оптимизации работы LLM.
Что означает вложенный AGENTS.md в монорепозитории
Вложенный AGENTS.md в монорепозитории означает наличие одного небольшого файла в корне репозитория и еще по одному файлу внутри каждой директории сервиса. Корневой файл содержит несколько правил, актуальных для всего проекта, а также карту расположения остальных файлов. Каждый файл сервиса содержит команды и соглашения, относящиеся только к этой директории. Агент, редактирующий services/worker/queue.py, считывает корневой файл и файл рабочего сервиса, не тратя контекст на фронтенд, с которым он не будет работать.
Ничего устанавливать не нужно. AGENTS.md — это соглашение, и в исходном проекте об этом сказано прямо:
AGENTS.md — это обычный Markdown. Используйте любые заголовки; агент просто парсит предоставленный вами текст.
Именно поэтому стоит правильно освоить этот метод. Формат не изменится. То, что может нарушиться — это размещение и поддержка, и то и другое входит в ваши обязанности.
Почему один большой файл AGENTS.md в корне перестает работать?
Один файл AGENTS.md объемом 600 строк в корне репозитория, содержащего веб-приложение, фоновый обработчик и директорию Terraform, дает сбои по четырем причинам.
Он устаревает, так как у него нет владельца. Инженер, переименовывающий тестовый скрипт в apps/web, редактирует файлы в apps/web. Корневой файл AGENTS.md не попадает в этот diff, поэтому никто из проверяющих не видит несоответствия. Через шесть недель файл описывает этап сборки, которого больше не существует, а человек, который внес изменения, уже забыл об этом.
Он расходует контекст при каждой задаче. Эти файлы загружаются в начале сессии, еще до того, как агент узнает, о чем вы собираетесь спросить. В документации Claude Code указано: «старайтесь не превышать 200 строк на файл CLAUDE.md. Более длинные файлы потребляют больше контекста и снижают точность выполнения инструкций». Codex перестает объединять файлы инструкций, как только их суммарный размер достигает 32 KiB — это значение по умолчанию для project_doc_max_bytes. Корневой файл, описывающий четыре сервиса, тратит этот лимит на три из них при выполнении любой задачи.
Инструкции начинают противоречить друг другу. Веб-директория требует pnpm test. Обработчик требует pytest -q. Если записать это в один файл, каждое правило будет верным лишь частично, поэтому агенту приходится угадывать, какое из них применимо. Документация Claude Code описывает результат: «если две инструкции противоречат друг другу, Claude может выбрать одну из них произвольно». Разделение файла не исключает попадание другого правила в контекст. Claude Code объединяет все загруженные файлы инструкций, а не заменяет один другим, поэтому корневой файл присутствует всегда. Как только агент открывает файлы в apps/web и services/worker, оба файла из директорий оказываются в контексте одновременно. Файл для каждой директории привязывает правило к той области, которой оно управляет. Укажите название директории в начале файла, как это сделано в примерах ниже с # apps/web, и каждая команда будет содержать указание на область действия, даже если загружено несколько файлов. Если правило, которое вы четко сформулировали, все равно игнорируется, лучше разобраться в причинах, по которым инструкция не применяется, чем переписывать формулировку в четвертый раз.
Он заполняется фактами, которые агент может прочитать из кода. Дерево директорий, список зависимостей, краткое описание функций каждого пакета. Проверка /doctor в Claude Code существует именно для того, чтобы исключить подобное. Она «удаляет контент, который Claude может извлечь из кодовой базы самостоятельно, например, структуру директорий, списки зависимостей и обзоры архитектуры», и оставляет «подводные камни, обоснования и соглашения, отличающиеся от стандартных настроек инструментов». Это предложение — лучший критерий для проверки того, стоит ли вообще включать строку в файл.
Читает ли агент корневой файл или только ближайший?
Здесь большинство людей ошибаются в понимании модели, поэтому стоит процитировать официальную конвенцию, а не пересказывать её:
Размещайте отдельный AGENTS.md внутри каждого пакета. Агенты автоматически считывают ближайший файл в дереве каталогов, поэтому самый близкий имеет приоритет, и каждый подпроект может поставлять специализированные инструкции.
И о конфликтах:
Файл AGENTS.md, ближайший к редактируемому файлу, имеет приоритет; явные запросы пользователя в чате переопределяют всё остальное.
Многие воспринимают «имеет приоритет» как «корневой файл игнорируется». Это не так. В инструментах, реализующих эту конвенцию, каждый файл на пути от корня репозитория до рабочей директории считывается и объединяется с остальными. Ближайший файл побеждает только в том случае, если два файла содержат противоречивые указания по одному и тому же вопросу.
Codex прямо описывает механизм: «Codex объединяет файлы от корня вниз, соединяя их пустыми строками. Файлы, расположенные ближе к вашей текущей директории, переопределяют более ранние указания». Claude Code следует тому же пути. При запуске сессии он считывает «каждый AGENTS.md и .claude/AGENTS.md в вашей рабочей директории и директориях выше неё», а его документация чётко описывает модель загрузки: «Все обнаруженные файлы объединяются в контекст, а не переопределяют друг друга». Директории ниже рабочей директории ведут себя иначе: Claude Code загружает AGENTS.md поддиректории по требованию, «когда Claude открывает там файл с помощью инструмента Read».
Из этого следуют два практических вывода. Корневой файл является префиксом для каждой сессии в репозитории, поэтому относитесь к каждой строке в нём как к строке, за которую вы платите сто раз в неделю. Файл в конкретной директории ничего не стоит, пока агент не откроет файл в этой директории, а значит, детали там обходятся дёшево и должны находиться именно там.
Это поведение было проверено по документации Codex и Claude Code 27 октября 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.Файл рабочего процесса имеет ту же структуру, но другое содержание: команду установки, pytest -q, причину, по которой потребитель должен оставаться идемпотентным, и миграцию, которая должна выполниться до прохождения тестов. В файле инфраструктуры вы прописываете правила, которые не позволяют агенту нанести вред. Никогда не запускайте terraform apply. Выполняйте terraform plan и останавливайтесь на этом, указывая бэкенд состояния, который уже настроен, чтобы агент не пытался инициализировать новый.
Обратите внимание, чего нет ни в одном из этих файлов: описания того, для чего предназначен каждый сервис. Это информация для людей. 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Если дата документации отстает от даты кода на шесть месяцев, это не доказывает, что файл содержит ошибки. Это лишь указывает, какой файл следует прочитать в первую очередь. Это всё, что требуется от проверки, занимающей одну секунду.
Ищите пути, которые больше не существуют. Документация устаревает вполне конкретным образом: она продолжает описывать код, который был удален. Каждый путь в этих файлах заключен в обратные кавычки, поэтому их легко извлечь и проверить.
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. Она также помечает шаблоны (globs), такие как src/**/*.ts, и любые процитированные URL, поскольку оба содержат косую черту и не являются файлами на диске. В Claude Code версии 2.1.283 или новее /doctor prompt-audit выполняет аналогичную проверку: она ищет «ссылки на файлы или команды, которых не существует», а также файлы, противоречащие друг другу. Она по умолчанию охватывает ваши файлы AGENTS.md и ничего не меняет, пока вы не попросите применить предложенные правки.
Симптом во время сессии. Агент читает файл, пытается открыть src/api/client.ts, потому что файл дал ему такую инструкцию, и инструмент возвращает:
No such file or directoryВ результате агент поступает логично и пишет свою собственную обертку fetch. В этом и заключается реальная цена устаревшего файла. Агент не игнорирует вашу документацию. Он следует ей, переходит по пути, который был удален три месяца назад, и пересоздает код, который у вас уже есть. Такой навык, как Ponytail, который ограничивает агента минимально необходимыми изменениями, делает подобный инстинкт пересоздания более редким, но он не может найти вспомогательный инструмент, на который ваш файл указал неверно.
Читает ли Claude Code файлы AGENTS.md?
Да, начиная с Claude Code v2.1.277, и точное правило имеет значение, так как от него зависит вложенная структура. Согласно документации на 27 октября 2026 года: «Claude Code может читать AGENTS.md в качестве инструкций к вашему проекту, поэтому репозиторий, уже настроенный для других агентов кодирования, работает без добавления 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 или с отключенной телеметрией, в сессии, где встроенный плагин для чтения этого файла отключен, или в проекте, где хранится CLAUDE.md с настройкой Project instructions, установленной в claude-md. Добавьте это в services/worker/CLAUDE.md:
@AGENTS.md
## Claude Code
Use plan mode for changes under `services/worker/migrations/`.Формат символической ссылки подходит, когда нет специфических для инструмента дополнений.
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 для символической ссылки требуются права администратора или режим разработчика, а Git извлекает закоммиченную символическую ссылку как обычный текстовый файл, если не включен core.symlinks, что оставляет в клоне однострочный CLAUDE.md вместо ваших инструкций. Если кто-либо, кто клонирует репозиторий, работает в Windows, используйте импорт @AGENTS.md. Если вы настроили любой из этих обходных путей до того, как Claude Code начал читать AGENTS.md самостоятельно, вы можете оставить их: документация гласит, что сохранение импорта «никогда не заставляет Claude читать AGENTS.md дважды», а символическая ссылка CLAUDE.md считывается один раз.
С этим связана одна ловушка. После /compact файл CLAUDE.md в корне проекта считывается с диска заново, но вложенные файлы в подкаталогах не перечитываются. Claude Code перезагружает их по требованию, в следующий раз, когда агент работает с файлом в этом каталоге. Документация разъясняет это для файлов CLAUDE.md и не описывает отдельно процесс сжатия для 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" } }.
В официальной документации указан способ переименования с обратной совместимостью для репозиториев, все еще использующих старое единственное имя: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.
В очень больших монорепозиториях настройка claudeMdExcludes в Claude Code позволяет пропускать файлы предков по пути или шаблону, что полезно, когда каталог другой команды находится выше вашего. Эти шаблоны применяются и к файлам AGENTS.md, которые читает Claude Code.
Чем это отличается от памяти агента или навыка?
Эти механизмы выглядят похожими, но их сбои имеют разную природу, поэтому важно точно понимать, какой из них вам нужен.
Файл AGENTS.md создается вами, фиксируется в git, проходит проверку в pull request и является идентичным для всех, кто клонирует репозиторий. Память агента создается самим агентом, хранится вне репозитория и привязана к одной конкретной машине. Документация Claude Code проводит ту же границу: CLAUDE.md содержит «Инструкции и правила», которые пишете вы, автоматическая память хранит «Изученное и шаблоны», которые записывает Claude, а директория с памятью не синхронизируется между машинами. Проверка проста. Если факт должен быть верным для коллеги, работающего с чистой копией репозитория, он не может находиться в памяти. Как память агента сохраняется между сессиями описывает эту часть процесса.
Навык — это третий элемент. AGENTS.md — это контекст, который загружается в каждой сессии; навык — это процедура, которая загружается по мере необходимости. Документация Claude Code предлагает полезное правило: «Если запись представляет собой многошаговую процедуру или важна только для одной части кодовой базы, перенесите ее в навык или правило, ограниченное путем». Вторая часть этого предложения — именно то, что решают вложенные файлы AGENTS.md. Первая часть — это то, для чего предназначены навыки агента, а если одна и та же процедура требуется в нескольких репозиториях, используйте общий навык для разных репозиториев вместо того, чтобы копировать одни и те же абзацы в десять разных файлов AGENTS.md.
Разработчики upstream отмечают, что «на момент написания в основном репозитории OpenAI содержится 88 файлов AGENTS.md». Это число — главный аргумент. Большому репозиторию не нужен один огромный файл. Ему нужно больше маленьких файлов, каждый из которых находится рядом с кодом, который он описывает, и за каждый из которых отвечает тот, кто последним вносил изменения в этот код.
FAQ
Заменяет ли вложенный AGENTS.md корневой файл или дополняет его?
Он дополняет его. Разработчики указывают, что «приоритет имеет ближайший файл», что описывает поведение при конфликте, а не процесс загрузки. 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 октября 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 читает «только ваши файлы CLAUDE.md». Если вам также нужен CLAUDE.md, установите Project instructions в значение claude-md-and-agents-md в /config или добавьте @AGENTS.md в его первую строку. Выполните /memory в сессии и убедитесь, что путь AGENTS.md появился в списке.
Где разместить правило, которое важно лишь иногда?
Не в AGENTS.md. Этот файл загружается в каждой сессии, поэтому каждая строка в нем конкурирует за внимание с запросом, который вы ввели. Процедура из нескольких шагов, которая требуется изредка, относится к навыку (skill), который загружается по требованию. Правило, применимое к одной директории, относится к AGENTS.md этой директории. Факт, который агент может прочитать непосредственно из кода, например дерево директорий или список зависимостей, не относится ни к тому, ни к другому.