AGENTS.md: как записать правила проекта для кодового агента

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

Представь небольшой веб-проект, где приложение лежит в src/, тесты — в tests/, а для проверки используют команду npm test. Если поручить агенту «добавь страницу», он может выбрать не тот каталог или забыть о проверке. Короткая инструкция может сказать: «Новые страницы находятся в src/pages/. После изменения пользовательского поведения запускай npm test. Не редактируй dist/: это результат сборки».

Что записать

Начни с нескольких конкретных разделов:

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

Рабочие правила. Укажи команды проверки, соглашения об именах или порядок изменений, который важен для команды.

Границы. Запиши запреты с причиной: «Не меняй generated/, потому что файлы собираются автоматически» полезнее, чем одно слово «не трогать».

Проверка готовности. Определи, какие проверки относятся к какому типу изменения. Например, тесты нужны для логики, а визуальная проверка — при изменении макета.

Пиши так, чтобы правило можно было выполнить или проверить. «Код должен быть качественным» не подсказывает действия; «не добавляй зависимость без объяснения в описании изменения» задаёт понятное ожидание. Если правило относится только к одной папке, размести его ближе к этой части проекта и проверь поведение инструмента с вложенными файлами инструкций по его официальной документации.

Чего избегать

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

Избегай конфликтов: «всегда запускать полную сборку» и «никогда не запускать сборку» не могут одновременно помогать. Разделяй общие правила и исключения по контексту. Объясняй, какое правило важнее при несовпадении. Важные ограничения должны быть рядом с описанием участка, к которому они относятся.

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

Пример короткой инструкции

# Правила проекта

- UI-компоненты находятся в src/ui/; API-клиенты — в src/api/.
- Запускай npm test после изменений логики.
- Не редактируй dist/ и generated/: это результаты сборки.
- Перед завершением перечисли изменённые файлы и выполненную проверку.

Этот пример условный: команды и каталоги нужно сверить со своим репозиторием. Сначала добавь одну-две проверяемые инструкции, проверь их на реальной небольшой задаче и поправь двусмысленности. Если команда регулярно уточняет одно и то же правило, добавь его. Если правило никто не использует или оно устарело, удали или обнови.

В официальном руководстве Codex по AGENTS.md объясняется, как инструмент находит и применяет проектные инструкции. Перед тем как полагаться на вложенные файлы, приоритет или размер контекста, проверь там актуальные детали.

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

Нужно ли писать AGENTS.md до первого запуска Codex? Нет. Добавляй его, когда появляются повторяемые правила или важно объяснить структуру проекта.

Можно ли записать все инструкции в корневой файл? Можно, но слишком длинный общий текст труднее поддерживать. Группируй проектные и локальные правила согласно действующей документации инструмента.

Файл гарантирует соблюдение правил? Нет. Он даёт контекст. Проверяй изменения, команды и доступы отдельно.