AGENTS.md: постоянные правила проекта для Codex

Файл AGENTS.md хранит долговечные инструкции для coding agents: устройство репозитория, команды запуска, инженерные соглашения, ограничения и критерии проверки.

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

Файл AGENTS.md хранит долговечные инструкции для coding agents: устройство репозитория, команды запуска, инженерные соглашения, ограничения и критерии проверки. Он избавляет от повторения одних и тех же правил в каждом промпте, но не должен превращаться в копию всей документации проекта.

Как Codex находит инструкции

Codex собирает цепочку инструкций перед началом работы. Сначала учитывается глобальная область в каталоге Codex, затем файлы от корня проекта до текущей рабочей директории. Более близкая инструкция появляется позже и может переопределить более общую.

На каждом уровне приоритет имеет AGENTS.override.md, затем AGENTS.md, затем настроенные fallback-имена. Пустые файлы пропускаются. Это позволяет хранить:

личные общие предпочтения глобально;
правила всего репозитория в корне;
специальные команды и ограничения рядом с отдельным сервисом;
временное переопределение через AGENTS.override.md.

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

Что стоит записывать

Хороший корневой файл отвечает на практические вопросы:

# Repository guide

## Layout
- frontend/ — Vue-приложение
- backend/ — NestJS API

## Commands
- pnpm typecheck
- pnpm test
- pnpm lint

## Working agreements
- Сохраняй незакоммиченные изменения пользователя.
- Для локальных правок используй существующие зависимости.
- После изменения API обновляй контракт и e2e-тест.

## Done
- Запусти проверки затронутого пакета.
- Просмотри итоговый diff и сообщи о непроверенных рисках.

Указывайте команды так, как они реально выполняются из текущей директории. Если backend использует другой runner, локальный AGENTS.md внутри backend должен это уточнить.

Что лучше оставить вне файла

Не помещайте в AGENTS.md:

секреты, токены и приватные ключи;
временные требования одной задачи;
длинные учебники по фреймворку;
правила, которые уже механически проверяет линтер без исключений;
противоречивые пожелания без приоритета;
описание несуществующих команд.

Одноразовое ограничение остаётся в промпте. Повторяемый сценарий можно оформить как skill. Жёсткое техническое ограничение, которое обязательно должно блокировать действие, лучше реализовать политикой доступа, CI или hook, а не надеяться только на текст.

Иерархия без конфликтов

Представьте монорепозиторий. Корневое правило требует запустить общий typecheck. В backend/AGENTS.md указано, что после миграций обязателен e2e-тест. В frontend/admin/AGENTS.override.md временно запрещено менять дизайн-систему.

Для задачи в frontend/admin действуют глобальные, корневые и локальные инструкции. Backend-правило не применяется, потому что оно не находится на пути от корня до текущей директории.

При конфликте формулируйте локальное правило явно:

## Verification override

Для этого пакета команда общего lint неприменима.
Запускай pnpm --filter @example/admin lint вместо корневой команды.
Остальные корневые проверки сохраняются.

Такой текст объясняет и исключение, и оставшуюся часть соглашения.

Поддержка инструкций как кода

AGENTS.md устаревает вместе с проектом. Проверяйте его после смены package manager, структуры каталогов, CI или процесса релиза. Полезный цикл:

1. заметить повторяющуюся ошибку агента; 2. выяснить, не вызвана ли она средой или неоднозначной задачей; 3. добавить короткое проверяемое правило; 4. испытать его на следующей задаче; 5. удалить правило, если оно не помогает.

Качество измеряется не длиной файла, а снижением повторных исправлений.

Практика: аудит AGENTS.md

Создайте или откройте файл проекта и отметьте:

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

Затем попросите Codex перечислить активные источники инструкций и кратко пересказать приоритеты. Сравните ответ с ожидаемой иерархией.

Частые вопросы

Нужно ли копировать AGENTS.md в каждую папку?

Нет. Корневые инструкции наследуются. Локальный файл нужен только там, где правила действительно отличаются: другой стек, команды, требования безопасности или процесс проверки.

Что важнее: промпт или AGENTS.md?

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

Почему Codex не увидел только что изменённый файл?

Цепочка инструкций собирается в начале запуска или сессии. Начните новую сессию в нужной директории и проверьте, что файл непустой, имеет поддерживаемое имя и попадает в область поиска.

Что важно запомнить

AGENTS.md хранит долговечные и проверяемые правила проекта.
Инструкции собираются от глобальной области к текущей директории.
Более близкие правила уточняют или переопределяют общие.
Секреты, одноразовые задачи и механические проверки не должны жить в AGENTS.md.

https://yadro-code.ru/lessons/without-university/codex-agent-workflows/codex-agent-04