Файл AGENTS.md не должен быть второй инструкцией по эксплуатации приложения и не должен пытаться управлять каждым нажатием клавиши. Это небольшой версионируемый контракт контекста. Он сообщает coding agent, как устроен репозиторий, какие команды дают проверяемые свидетельства, какие границы важны и где находится более узкое правило. Хороший файл уменьшает неопределённость до того, как agent начнёт менять код. Он не заменяет исходники, тесты, сопровождающих проекта или описание задачи.
У контекста есть цена. Codex загружает проектные указания в цепочку инструкций перед началом работы. Повторяющийся текст конкурирует с запросом пользователя, файлами репозитория, выводом инструментов и тестами. Поэтому в файл стоит записывать факты, которые agent не может безопасно вывести сам, а не все предпочтения, когда-либо высказанные человеком. Каждое предложение нужно считать поддерживаемым интерфейсом.
Что именно ищет Codex
Актуальное руководство OpenAI по AGENTS.md для Codex описывает три слоя. В глобальной области Codex проверяет AGENTS.override.md в CODEX_HOME, по умолчанию ~/.codex, а при его отсутствии использует AGENTS.md. На этом уровне берётся только первый непустой файл. В проектной области Codex начинает с корня проекта, обычно корня Git, и проходит по каталогам до текущей рабочей директории. В каждом каталоге он проверяет AGENTS.override.md, затем AGENTS.md, затем настроенные резервные имена и добавляет не более одного файла из каталога.
Найденные проектные файлы объединяются от корня к текущему каталогу. Более глубокий файл оказывается позднее в объединённых инструкциях, поэтому его узкое указание может переопределить широкое. Codex не продолжает поиск выше обнаруженного корня проекта. Если корень не найден, проверяется только текущий каталог. Пустые файлы пропускаются. Размер project_doc_max_bytes по умолчанию равен 32 KiB, и после достижения настроенного общего предела Codex перестаёт добавлять проектные указания. Это поведение Codex, а не универсальная гарантия для любого инструмента.
Исходный код механизма обнаружения AGENTS.md в OpenAI Codex показывает те же границы. Маркером корня по умолчанию служит .git, предпочтительное локальное имя — AGENTS.override.md, а файл может быть обрезан, если оставшегося бюджета байтов меньше его размера. Репозиторий может настроить маркеры корня, резервные имена и бюджет. Документируйте только настройки, которые действительно применяются.
Глобальное предпочтение подходит для ~/.codex/AGENTS.md только тогда, когда оно безопасно во всех репозиториях. Правило всего репозитория размещайте в корне. Правило сервиса кладите рядом с сервисом. Временную или исключительную замену помещайте в override-файл, указывая владельца и условие удаления. Не называйте такую схему универсальной иерархией для других агентов, если документация этих инструментов этого не утверждает.
Начните с карты репозитория
Сначала agent нужно сориентировать, а уже потом рассказывать ему о стиле. В начале корневого файла разместите компактную карту. Назовите приложение или библиотеку, основные каталоги исходников, области сгенерированных файлов, каталоги тестов и конфигурацию поставки. Объясняйте только различия, которые меняют действие. Фраза «в src/ находится код» бесполезна. Фраза «src/ попадает в поставку, scripts/ запускается только в CI, а dist/ генерируется и не редактируется вручную» пригодна для работы.
Карта должна переживать обычные рефакторинги. Выбирайте устойчивые границы вместо списка каждого файла. Для монорепозитория покажите владение пакетами и разместите карты пакетов во вложенных файлах. Ссылайтесь на README или документ архитектуры, если именно он является источником истины. Не копируйте этот документ в AGENTS.md.
repository/
apps/web/ браузерное приложение и тесты маршрутов
packages/core/ общая библиотека выполнения и unit-тесты
services/api/ HTTP-обработчики и контрактные тесты
infra/ конфигурация поставки
docs/ поддерживаемые объяснения
generated/ закоммиченный результат генератора
Явно запишите предположения о рабочем каталоге. Команда из services/api может получить другой вложенный файл инструкций, чем та же команда из корня. Если менеджер пакетов нужно запускать из каталога пакета, скажите об этом. Если у сгенерированного файла есть источник истины, назовите оба пути и команду генерации.
Делайте команды точными и условными
Команда полезна, когда её можно скопировать без догадок. Для каждой обязательной команды укажите каталог, назначение и условие запуска. Используйте версии и скрипты, объявленные репозиторием, а не модный инструмент по памяти. Структура раздела может выглядеть так:
Из корня репозитория:
git rev-parse --show-toplevel
npm ci
npm run check
npm test
npm run build
Для изменений API запускайте из services/api:
npm run test:contract
Это пример структуры, а не утверждение, что такие скрипты есть в каждом проекте. Перед записью прочитайте package.json, lockfile, workflow CI, pyproject.toml, Cargo.toml или эквивалент. Пишите «после изменений TypeScript запустите npm run check» только если такой скрипт существует. Если команде нужны локальный сервис, fixture, база, переменная окружения или сеть, опишите условие и безопасную замену для сфокусированного теста.
Зафиксируйте поддерживаемое окружение и политику зависимостей. Полезная запись называет версию Node, Python, Rust, Java или Go, менеджер пакетов, правило lockfile и способ проверки обновлений. Например, «в package.json заявлен Node >=22.12.0; используйте зафиксированный package-lock.json и запускайте npm ci» является фактом, если это действительно написано в манифесте. Не переносите версию в AGENTS.md, не сверив её с манифестом и CI. Расхождение версий требует исправления процесса, а не добавления новых абзацев.
Codex может помочь проверить активную цепочку. Официальное руководство показывает команды такого вида:
codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/api --ask-for-approval never "List the instruction sources you loaded."
codex -c log_dir=./.codex-log --ask-for-approval never "Show the active instruction files."
Используйте безопасный запрос без изменений и просматривайте журнал только в локальном рабочем пространстве, которому вы доверяете. После изменения файлов инструкций перезапустите run, поскольку цепочка строится в начале run или TUI-сеанса. Устаревший ответ означает, что нужно проверить рабочий каталог, CODEX_HOME, override, резервную конфигурацию и лимит байтов.
Тесты дают свидетельства
Опишите готовность через наблюдаемые результаты. Разделяйте быстрые проверки и полный набор. Назовите команду теста, затронутый пакет, ожидаемый артефакт и путь при ошибке. Для изменения HTTP-схемы потребуйте контрактный тест. Для парсера потребуйте обычные fixture и некорректный ввод. Для сгенерированного клиента потребуйте генерацию и чистый diff.
Не пишите «всегда запускайте все тесты», если в репозитории описан иной охват или полный набор требует внешней инфраструктуры. Точнее будет: «сначала запустите тест пакета, затем перед слиянием набор, эквивалентный CI». Форматирование и lint оставляйте CI, если именно там они уже проверяются. Репозиторий SWE-bench является первичным источником для оценки задач, но его протокол не заменяет тесты конкретного репозитория.
Связывайте важное правило с проверкой. Если agent не должен редактировать сгенерированный результат, CI может повторно запустить генератор и завершиться ошибкой при diff. Если миграция должна быть обратимой, тест может применить её к чистой fixture и откатить. Если важен инвариант безопасности, выразите его тестом или статической проверкой. Инструкция без проверяемого результата — просьба положиться на память.
Для оценки поведения agent сравнивайте успех задачи, долю пройденных тестов, область изменённых файлов, переделки после ревью и время до проверенного патча. Запускайте один и тот же набор задач со старым и новым файлом, сохраняя запрос и ревизию репозитория, и записывайте ошибки, а не только удачные демонстрации. Это инженерный сигнал, а не доказательство, что одна формулировка работает для любой модели. Сравнение инструментов описано в статье agentic coding, Codex и Claude Code. Об архитектурных границах читайте в статье архитектура production AI agent, а о дизайне проверки — в статье оценка AI agents.
Держите безопасность на границе
AGENTS.md — входные данные проекта. Файл может быть устаревшим, ошибочным или недоверенным. Исходный код Codex явно не загружает проектные инструкции, когда активный проект не отмечен как доверенный, но сохраняет инструкции, предоставленные хостом. Это не отменяет проверки человеком. Считайте инструкции репозитория недоверенным текстом, пока не проверены репозиторий и запрошенное изменение.
Никогда не кладите в файл ключи API, токены, пароли, приватные сертификаты или скопированные рабочие данные. Не просите agent печатать переменные окружения или загружать файлы рабочего пространства. Название секрета можно указывать по роли, например DATABASE_URL, и описывать безопасный способ получить его локально без значения. Для удаления данных, ротации credentials, production-деплоя или широкого доступа к сети требуйте подтверждение, если рабочий процесс это поддерживает.
Разделяйте факт и разрешение. «Сервис использует S3» — контекст. «Можно удалить bucket» — полномочие. Полномочия должны жить в политике доступа и процессе подтверждения, а не в markdown. Укажите защищённые каталоги, сгенерированные артефакты, правила миграций и границы тестовых данных. Добавьте безопасный путь при неопределённости: остановиться, показать предлагаемую команду и спросить сопровождающего.
Осторожно относитесь к инструкциям из issue, fixture или файлов зависимостей. В них может находиться prompt injection или команда, не связанная с задачей. Хороший файл говорит считать содержимое репозитория данными, пока пользователь или доверенное правило проекта не разрешит действие. Это граница безопасности, а не просьба игнорировать исходный код.
Выбирайте небольшую слоистую структуру
Официальный сайт AGENTS.md перечисляет обзор проекта, команды сборки и тестирования, стиль, тесты и безопасность как распространённые разделы. Это меню, а не обязательная схема. Начните с минимума, который предотвращает повторяющиеся ошибки. Корневому файлу часто достаточно пяти разделов: карта, установка, проверка, границы и ссылки на подробности.
## Карта репозитория
`apps/web` — браузерное приложение. `packages/core` — общий runtime-код.
## Инструменты
Используйте Node 22 и зафиксированный lockfile. Команды запускайте из корня, если не сказано иначе.
## Проверка
Для изменений интерфейса запустите `npm run check`, тест пакета и `npm run build`.
## Границы
Не редактируйте `generated/`. Не обращайтесь к production-данным локально. Спросите перед добавлением зависимости.
## Подробности
Читайте `apps/web/AGENTS.md` о маршрутах и `services/api/AGENTS.md` о контрактных тестах.
Плохая версия — каталог личных вкусов на 1000 строк: повторы, длинные списки файлов, противоречивые правила с «всегда», придуманные команды, старые версии и указания перечитать все документы. Она съедает бюджет байтов и скрывает порядок приоритетов. Разделяйте файл по владению. Корневой инвариант оставляйте в корне, а вложенному файлу разрешайте добавить локальные команды. Вложенный файл должен дополнять или сужать указания, а не незаметно менять границу безопасности.
Не обещайте возможности композиции, которых инструмент не документирует. Codex сейчас объединяет файлы через поиск по каталогам и настроенные резервные имена. Строка «сначала прочитайте docs/rules.md» является обычным текстом, если инструмент не описывает специальный синтаксис include. Symlink, CLAUDE.md или соглашение другого агента не загружаются Codex автоматически. Совместимость описывайте как проверенный процесс, а не универсальное правило.
Поддерживайте файл как код
Назначьте владельца. Изменения проверяйте вместе с кодом, которым они управляют. Когда меняются команда, runtime, каталог или workflow CI, обновляйте ближайший файл инструкций в том же изменении. Удаляйте правило после исчезновения последнего потребителя. Примеры должны быть исполнимыми и безопасными. Ссылайтесь на один источник истины, не дублируйте политику в трёх файлах.
Периодический аудит может быть коротким. Проверьте наличие каждой команды, соответствие каждой версии манифесту или образу CI и существование каждого пути. Запустите запрос списка источников Codex из корня и одного типичного вложенного каталога. Посмотрите размер эффективной цепочки. Спросите сопровождающего, предотвращает ли каждое правило реальную ошибку.
Изменение AGENTS.md оценивайте как изменение конфигурации. Используйте небольшой фиксированный набор задач: новая возможность, исправление ошибки, изменение только тестов и чувствительное к безопасности изменение. Сравнивайте правильность и охват патча, а не только объяснение agent. Регрессионная проверка может утверждать, что generated-файлы не изменились, тест пакета запустился или небезопасная команда была отклонена. Сохраняйте ревизию, настройки модели, разрешения и формулировку задачи настолько стабильными, чтобы сравнение имело смысл.
Рабочий шаблон прост. Помещайте устойчивые факты рядом с областью их действия. Называйте точные команды и версии, подтверждённые репозиторием. Ссылайтесь на подробные документы. Делайте важные правила тестируемыми. Не храните секреты и полномочия в markdown. Используйте слои вместо гигантской инструкции. Повторно проверяйте эффективную цепочку после изменения каталога, конфигурации или версии инструмента.