Codex

Что такое AGENTS.md в Codex CLI?

Разберите роль AGENTS.md в Codex CLI, hierarchy инструкций, что туда писать и каких ошибок избегать. Включает настройку, ожидаемое поведение и частые ошибки.

Короткий ответ

AGENTS.md — это project instruction file для Codex. Он рассказывает Codex о структуре репозитория, командах, тестах, code style, commit rules и collaboration preferences.

Он подходит для стабильных project rules, а не для разовых задач. Разовые требования оставляйте в текущем диалоге.

Что стоит включить

Как установить dependencies, запустить проект и тесты
Common validation commands
Coding style и naming conventions
Директории, которые нельзя менять без необходимости
Required checks before finishing
Team preferences по communication и output

Что не стоит включать

API Keys, tokens, passwords или private credentials
Temporary task instructions
Длинные product background stories
Generic prompts, не связанные с репозиторием
Outdated commands и paths

Область действия и приоритет

Codex формирует начальную цепочку инструкций при запуске. Каталог запуска влияет на набор файлов:

Сначала загружаются глобальные правила из CODEX_HOME, по умолчанию ~/.codex: первый непустой AGENTS.override.md, иначе AGENTS.md.
Затем проверяются каталоги от корня проекта, обычно корня Git, до текущего рабочего каталога. Если корень проекта не найден, для правил проекта проверяется только текущий каталог.
В каждом каталоге проекта используется не более одного непустого файла: сначала AGENTS.override.md, затем AGENTS.md, затем имена из project_doc_fallback_filenames.

При конфликте более конкретные правила в конце цепочки имеют приоритет; остальные родительские правила продолжают действовать. Файл override заменяет обычный файл в том же каталоге, а не все инструкции родителей.

Пример каталогов

~/.codex/AGENTS.md
repo/AGENTS.md
repo/services/payments/AGENTS.override.md
repo/services/payments/AGENTS.md
repo/services/search/AGENTS.md

Допустим, глобальные правила требуют npm test, файл репозитория требует проверки линтером, а override для payments заменяет тестовую команду на make test-payments. При запуске из repo/services/payments Codex загружает глобальный файл, файл репозитория и override для payments. Проверка линтером сохраняется, используется команда тестов payments, а обычный файл payments пропускается. Соседний файл search не входит в эту начальную цепочку.

Проверка пропущенных и конфликтующих правил

После изменения инструкций запустите новую сессию в нужном каталоге и попросите Codex перечислить загруженные источники и применимые команды:

codex -C /path/to/repo/services/payments "List the instruction files you loaded and the test command that applies here. Do not edit files."

Проверьте рабочий каталог и CODEX_HOME. Запуск из корня репозитория не загружает заранее правила всех вложенных каталогов.
Проверьте точное имя файла, наличие содержимого и AGENTS.override.md на том же уровне. Резервное имя должно быть указано в project_doc_fallback_filenames.
При обрезании длинных инструкций проверьте project_doc_max_bytes. Удалите повторы и поместите важные правила в начало.
При конфликте определите оба исходных файла и область действия каждого правила. Опишите узкое исключение в нужном каталоге вместо копирования противоречащих правил повсюду. Файлы инструкций не изменяют права песочницы.

Частые ошибки

Превращать AGENTS.md в очень длинный universal prompt.
Записывать secrets в файл.
Не обновлять его после изменения project commands.
Смешивать AGENTS.md с user-level config.toml.
Думать, что rules отменяют необходимость смотреть diff и tests.

О BetterToken

Если команда использует BetterToken для unified model routing, AGENTS.md все равно важен. API layer отвечает за model requests и usage records. AGENTS.md отвечает за project context и execution norms.

Оба слоя вместе уменьшают configuration confusion и collaboration cost.