AGENTS.md: инструкции проекта

Каждая сессия Codex начинается с чистого листа: агент не помнит, что вчера вы объясняли ему, как запускать тесты. Чтобы не повторять одно и то же, существует AGENTS.md — файл с инструкциями, который Codex автоматически подгружает в начале работы. Это главный инструмент, который превращает «иногда получается» в «обычно получается».

Что это за файл

AGENTS.md — обычный markdown-файл в репозитории. Документация Codex описывает его как открытый формат README для агентов: README пишут для людей, AGENTS.md — для агента. Формат открытый: его понимают и другие инструменты, не только Codex.

Если вы проходили курс по Claude Code, AGENTS.md — аналог CLAUDE.md.

Содержимое AGENTS.md попадает в запрос к модели перед вашим первым сообщением (вспомните урок «Как работает Codex»). Поэтому всё, что там написано, агент получает в каждой сессии без напоминаний. С правилами, которые вы дали только в переписке, так не выйдет: в новой сессии их не будет, а в длинной они могут потеряться при сжатии истории.

Как Codex находит файлы

Инструкции собираются с двух уровней.

Глобальный. В домашнем каталоге Codex (~/.codex, если не задана переменная CODEX_HOME) берётся AGENTS.override.md, а если его нет — AGENTS.md. Здесь ваши личные предпочтения для всех проектов: язык ответов, стиль коммитов.

Проектный. Codex идёт от корня проекта (обычно это корень git-репозитория) вниз до каталога, в котором вы его запустили. В каждом каталоге он ищет по порядку AGENTS.override.md, затем AGENTS.md и берёт не больше одного файла на каталог.

Найденные файлы склеиваются от общего к частному: глобальный, корневой, вложенные. Файл ближе к текущему каталогу идёт позже и поэтому имеет приоритет. Это удобно в монорепозитории: в корне — общие правила, в mobile/AGENTS.md — правила для мобильного приложения, в backend/AGENTS.md — для бэкенда.

Ограничения, о которых стоит знать:

• Суммарный объём инструкций ограничен настройкой project_doc_max_bytes, по умолчанию 32 KiB. Всё, что сверх лимита, просто не загрузится.
• Пустые файлы пропускаются.
• Инструкции собираются один раз при запуске сессии. Поправили AGENTS.md — начните новую сессию, чтобы агент увидел изменения.

Полное описание — в документации по AGENTS.md.

Что писать

Документация советует, чтобы хороший AGENTS.md покрывал:

• структуру репозитория и важные каталоги;
• как запустить проект;
• команды сборки, тестов и линтера;
• соглашения и ожидания к merge request;
• ограничения и запреты;
• что значит «готово» и как проверить работу.

Пример для сайта на OctoberCMS:

# AGENTS.md

## Проект
Корпоративный сайт на OctoberCMS (PHP 8.3) + тема на Twig, SCSS, Vite.
- `themes/site/` — тема: pages, partials, layouts, resources
- `plugins/acme/site/` — бэкенд-плагин: компоненты, модели, сервисы
- `tests/e2e/` — Playwright

## Команды
- Поднять окружение: `docker compose up -d` (сайт на http://localhost:8001)
- PHP-тесты: `docker compose exec app php artisan test`
- E2E: `npx playwright test`
- Сборка фронта: `cd themes/site && npm run build`

## Соглашения
- В каждом PHP-файле `declare(strict_types=1);`
- CSS-классы по BEM; стили страниц — в `resources/scss/pages/<slug>.scss`,
  не inline в шаблонах
- Входные данные компонентов валидировать через Validator

## Запреты
- Не менять файлы в `vendor/` и `modules/`
- Не коммитить `.env` и не выводить его содержимое
- Не делать `git push` и не трогать ветку `main`

## Готово, когда
- PHP-тесты и затронутые e2e проходят
- Фронт собран, если менялись `resources/`
- В ответе — список изменённых файлов и что не удалось проверить

Обратите внимание: здесь нет общих слов вроде «пиши чистый код». Каждая строка либо факт о проекте, либо проверяемое правило.

Чего не писать

• Очевидное. «Используй осмысленные имена переменных» агент делает и так, а место в лимите занимает.
• Энциклопедию. Документация советует: если файл разрастается, оставить в нём главное и ссылаться на отдельные markdown-файлы — про архитектуру, ревью, планирование. Агент откроет их, когда понадобится.
• Устаревшее. Неверная команда запуска тестов хуже отсутствующей: агент будет уверенно делать не то. Меняете процесс — правьте AGENTS.md в том же MR.
• Секреты. Файл лежит в репозитории и уходит в запрос к модели. Никаких паролей, токенов и адресов боевых баз.

Как начать: /init

Не пишите файл с нуля. В корне проекта запустите Codex и наберите:

/init

Агент изучит репозиторий и создаст заготовку AGENTS.md в текущем каталоге. Это хорошая отправная точка, но не финал: документация прямо советует отредактировать результат под то, как ваша команда на самом деле собирает, тестирует и выпускает код. Проверьте команды — агент мог угадать их по типичной структуре проекта.

Если вы сохранили конспект из урока «Первая сессия», используйте его: в нём уже есть карта проекта.

Как развивать файл

Лучший источник правил — реальные ошибки агента. Документация советует начинать с основ и добавлять правило, только когда заметили повторяющуюся ошибку. Агент второй раз поменял файлы в vendor/ — это строка в «Запретах». Агент снова запустил все тесты вместо нужного набора — уточните раздел «Команды».

Полезный приём: когда агент ошибся одинаково дважды, попросите его провести ретроспективу — «что в инструкциях проекта помогло бы избежать этой ошибки?» — и обновите AGENTS.md по итогам.

AGENTS.md коммитится в репозиторий, как обычный код: его ревьюят, и он общий для всей команды. Личные предпочтения держите в глобальном ~/.codex/AGENTS.md.

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

Попросите агента пересказать инструкции:

codex --sandbox read-only --ask-for-approval never "Summarize the current instructions."

Агент перечислит правила из глобального и проектных файлов в порядке приоритета. Чтобы проверить вложенный каталог, добавьте --cd:

codex --cd mobile --sandbox read-only --ask-for-approval never "Show which instruction files are active."

Если какого-то правила в пересказе нет — проверьте имя файла, его расположение и не превышен ли лимит.