Если в каждой задаче приходится объяснять, как запустить проект, чем проверять код и какие модули не нужно трогать, эти договорённости стоит вынести в AGENTS.md. Это обычный Markdown-файл с инструкциями для Codex, а не специальный язык программирования.

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

Для чего нужен AGENTS.md

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

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

Где разместить файл

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

Глобальный файл по умолчанию находится в ~/.codex/AGENTS.md; расположение зависит от CODEX_HOME. В одной директории AGENTS.override.md имеет приоритет над AGENTS.md. Не создавайте override без необходимости: иначе легко забыть, почему основной файл больше не задаёт ожидаемые правила.

Не рассчитывайте, что любой файл в любой подпапке автоматически прочитается при старте из корня. Учитывайте рабочую директорию задачи. После изменения инструкций начните новую сессию и попросите перечислить применяемые правила. Документированный размер объединённых инструкций по умолчанию ограничен 32 KiB, поэтому огромный файл — плохая замена короткой структуре.

Что написать в первой версии

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

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

## Назначение
Внутренний инструмент учёта заявок небольшой компании.
В тестах и примерах использовать только вымышленные данные.

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

## Проверки
- Команды запуска и тестов брать из README и конфигурации.
- Для изменённого поведения проверять основной сценарий
  и существенные ошибки ввода.
- Не называть непроведённую проверку успешной.

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

## Отчёт
Кратко указать изменения, выполненные проверки
и оставшиеся ограничения.

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

Как добавить команды без путаницы

Предположим, в вашем проекте уже настроены npm run dev, npm run lint и npm test. Тогда можно перечислить их с назначением. Но копировать такие команды в Python-проект или приложение с другим менеджером пакетов бессмысленно.

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

Когда нужны правила для отдельных частей проекта

В небольшом приложении обычно достаточно одного файла. Разделение становится полезным, когда части системы действительно работают по-разному: например, интерфейс проверяется браузерными тестами, а обработчик документов — набором входных файлов.

В локальных правилах описывайте только различия. Не копируйте весь корневой документ. Иначе при изменении одного требования придётся искать несколько несовпадающих версий.

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

Какие ошибки встречаются чаще всего

Слишком много запретов. Исполнитель видит ограничения, но не понимает допустимый способ решить задачу.
Расплывчатые требования. «Делай безопасно» не объясняет, что нельзя публиковать и какие данные использовать.
История вместо правил. Длинная переписка о прошлых ошибках затрудняет поиск актуальных требований.
Несуществующие команды. Инструкции отправляют агента запускать проверки, которых нет.
Противоречия. Один документ требует менять общий компонент, другой запрещает его трогать без пояснения исключений.

AGENTS.md не является защитой доступа

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

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

Как проверить, что файл полезен

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

Для разовых заданий используйте шаблон постановки задачи Codex. Если только начинаете разработку, вернитесь к инструкции по первому приложению. Постоянные правила и конкретная задача дополняют друг друга: один документ задаёт условия работы, другой — нужный результат.

Как писать AGENTS.md для Codex