AGENTS.md в большом репозитории

Первый AGENTS.md вы написали в курсе «Codex с нуля» (урок «AGENTS.md: инструкции проекта»). В небольшом проекте одного файла хватает. В репозитории, где рядом живут PHP-бэкенд, тема на Vite, мобильное приложение и e2e на Playwright, единый файл быстро разрастается, противоречит сам себе и перестаёт помещаться в лимит. Разберём, как Codex на самом деле находит инструкции и как этим пользоваться.

Как собирается цепочка

Codex строит цепочку инструкций один раз при запуске (в TUI — в начале сессии):

1. Глобальный уровень — $CODEX_HOME, по умолчанию ~/.codex. Берётся AGENTS.override.md, если он есть и не пустой, иначе AGENTS.md. Только один файл.
2. Проектный уровень — от корня проекта (обычно корня git) вниз до текущего каталога. В каждом каталоге по порядку ищутся AGENTS.override.md, AGENTS.md, затем имена из project_doc_fallback_filenames. Из каталога берётся не больше одного файла.
3. Склейка — файлы объединяются от корня к текущему каталогу через пустую строку. Ближний к вам файл идёт позже и поэтому «перекрывает» общие правила.

Пустые файлы пропускаются. Кэша нет: чтобы подхватить изменения, достаточно перезапустить Codex.

Из алгоритма следует важная деталь: в стартовую цепочку попадают только каталоги на пути от корня до текущего. Если вы запустили Codex из корня, а агент работает в mobile/, файл mobile/AGENTS.md в эту цепочку не входит. Решения два: запускать Codex из нужного каталога (codex --cd mobile) или явно написать в корневом файле, что перед работой в подпроекте нужно прочитать его инструкции.

Override и запасные имена

AGENTS.override.md в каталоге полностью заменяет AGENTS.md этого же каталога — обычный файл тогда игнорируется. Применения:

• Временное изменение правил без правки общего файла: на время миграции базы попросить агента не трогать определённые таблицы. Удалили override — вернулись к обычным правилам.
• Личные поправки к проектным правилам. Положите AGENTS.override.md в .gitignore, и он не попадёт в репозиторий. Помните, что override заменяет, а не дополняет файл каталога: скопируйте в него содержимое AGENTS.md и допишите своё. Игнорируемый git'ом AGENTS.override.md Codex сам копирует в worktree, которые создаёт.
• Глобальный override ~/.codex/AGENTS.override.md — временно заменить ваши личные правила для всех проектов.

Если в репозитории уже есть файл инструкций под другим именем, не нужно его переименовывать — добавьте имя в список запасных:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", "CLAUDE.md"]
project_doc_max_bytes = 65536

Теперь в каждом каталоге порядок поиска — AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, CLAUDE.md. Это удобно, если часть команды работает с другим агентом: если вы проходили курс по Claude Code, CLAUDE.md — аналог AGENTS.md. Но надёжнее держать один источник правды: например, короткий CLAUDE.md, который ссылается на AGENTS.md, а не два файла с расходящимися правилами.

Лимит объёма

Суммарный объём проектных инструкций ограничен ключом project_doc_max_bytes, по умолчанию 32 KiB. Когда лимит достигнут, Codex перестаёт добавлять файлы. Обратите внимание на порядок: склейка идёт от корня, поэтому при переполнении теряются как раз самые близкие к задаче, самые конкретные файлы.

Поднять лимит можно, но это лечение симптома. Всё, что лежит в AGENTS.md, загружается в каждую сессию и занимает контекст, даже если к задаче не относится. Лучше:

• держать корневой файл коротким — карта проекта, команды, главные запреты;
• выносить правила подсистем во вложенные файлы;
• длинные процедуры (релиз, миграция данных, генерация посадочной страницы) упаковывать в навыки: они загружаются, только когда нужны;
• справочники — схему базы, описание API, гайд по стилю — держать в docs/ и ссылаться на них из AGENTS.md.

Подробнее о том, почему AGENTS.md должен быть оглавлением, а не энциклопедией, — в курсе «Harness engineering».

Раскладка по монорепозиторию

Пример структуры для типового проекта агентства:

AGENTS.md                      карта, команды, общие запреты
docs/                          справочники, на которые ссылаются инструкции
backend/AGENTS.md              PHP, strict_types, миграции, команды тестов
frontend/AGENTS.md             BEM, сборка Vite, правило «стили страниц — в отдельные файлы»
mobile/AGENTS.md               сборка, симулятор, что нельзя менять без дизайнера
tests/e2e/AGENTS.md            как поднять стенд, как запускать Playwright, правила фикстур

Корневой файл в такой раскладке:

# Проект: сайт и мобильное приложение

## Карта
- `backend/` — плагин OctoberCMS (PHP). Перед работой прочитай `backend/AGENTS.md`.
- `frontend/` — тема, SCSS и JS, сборка через Vite. Правила — `frontend/AGENTS.md`.
- `mobile/` — приложение. Правила — `mobile/AGENTS.md`.
- `tests/e2e/` — Playwright. Правила — `tests/e2e/AGENTS.md`.

## Команды
- Поднять окружение: `docker compose up -d`, сайт на http://localhost:8001
- Тесты бэкенда: `docker compose exec app php artisan test`
- Сборка фронта: `cd frontend && npm run build`

## Всегда
- Ветка `task-<ID>` от `main`, один MR на задачу.
- Не коммить `.env` и не печатай его содержимое.
- Готово = тесты зелёные, сборка проходит, дифф без посторонних файлов.

## Code Review Rules
- Миграции без отката (`down`) — блокирующее замечание.
  Безопасный путь: описать откат или явно обосновать в MR, почему он невозможен.

Раздел ## Code Review Rules читает ревью Codex в GitHub, а правила применяются из корневого и вложенных AGENTS.md, которые покрывают изменённый файл. Начинайте с двух-трёх правил, описывайте последствия и безопасный путь, а форматирование и линтеры оставьте CI. Ревью подробно разбирается в курсе «Codex в ежедневной разработке».

Корень проекта и не-git репозитории

Корень по умолчанию — каталог с .git. Если проект живёт в Mercurial или Sapling, или вы хотите, чтобы корнем считался текущий каталог, настройте маркеры:

project_root_markers = [".git", ".hg", ".sl"]
# project_root_markers = []   # корень — текущий каталог, родители не просматриваются

Инструкции не только в AGENTS.md

Для полноты — ещё два ключа конфигурации, которые влияют на инструкции:

• developer_instructions — дополнительные инструкции, которые Codex добавляет в сессию из config.toml. Удобно для профиля: например, в профиле для ревью попросить отвечать списком находок по приоритету.
• model_instructions_file — путь к файлу, который заменяет встроенные базовые инструкции модели. Инструмент для экспериментов с обвязкой агента, а не для повседневной работы: заменив базовые инструкции, легко потерять полезное поведение.

Как проверить, что загрузилось

codex --sandbox read-only --ask-for-approval never "Перечисли источники инструкций, которые ты загрузил, по порядку"
codex --cd tests/e2e --sandbox read-only --ask-for-approval never "Какие файлы инструкций сейчас активны?"
codex debug prompt-input

Первые две команды просят агента пересказать цепочку — Codex должен назвать глобальный файл, затем корневой, затем вложенный. Третья (экспериментальная) показывает в JSON, что именно уходит модели. Если инструкции выглядят устаревшими, перезапустите Codex; если загрузилось не то — поищите AGENTS.override.md выше по дереву или в ~/.codex и проверьте echo $CODEX_HOME.