AGENTS.md - это durable-контракт репозитория: инструкции, которые Codex читает до начала работы и строит из них цепочку один раз на запуск или сессию. В отличие от разового prompt, это отревьюенный источник истины, живущий в репозитории под контролем версий. Глобальные указания находятся в $CODEX_HOME, а проектная цепочка строится от корня репозитория до текущего рабочего каталога - то есть более общее задаётся выше, более конкретное ближе к коду.

Порядок построения цепочки важен, потому что определяет, что победит. В каждом каталоге сначала ищется AGENTS.override.md, затем AGENTS.md, затем имена из project_doc_fallback_filenames. На один каталог берётся не более одного непустого файла. Инструкции, более близкие к текущему каталогу, появляются в цепочке позже и поэтому переопределяют общие. Это та же логика приоритета, что и в config: конкретное перекрывает общее, а не наоборот.

Хороший AGENTS.md - это контракт проекта, а не пересказ структуры. Полезно один раз увидеть осмысленный пример. Ниже - карта репозитория, обязательные проверки и политика изменений: где код и тесты, какие команды запускать после правок, чего не делать без подтверждения. Именно то, что нельзя надёжно вывести по коду, - команды проверки, границы, определение готовности - и стоит записать, а очевидное из package.json повторять не нужно.

Смысл AGENTS.md - назвать то, что агент не выведет сам. Карта репозитория экономит ему исследование: где живёт код приложения, где интеграционные тесты. Обязательные проверки задают сигнал: запусти lint после правок TypeScript, прогони затронутые тесты при изменении поведения. Политика изменений ставит границы: не добавляй production-зависимости без подтверждения, сохраняй совместимость публичного API, пока задача явно не требует иного. Это контракт, по которому агент действует по умолчанию.

Держать AGENTS.md стоит коротким и проверяемым, а не растить в энциклопедию. Длинные инструкции занимают контекст и теряют salience - агент хуже следует размытому многословию, чем короткому чёткому списку. Общие факты оставляют в корневом файле, а специфичные для подкаталога требования переносят в его собственный AGENTS.md, который подхватится именно там. Вложенные overrides - это способ держать инструкцию рядом с кодом, к которому она относится, а не сваливать всё в корень.