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

Коротко: зачем нужен AGENTS.md

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

Codex читает AGENTS.md до начала работы и использует его вместе с вашим текущим заданием. Промпт отвечает на вопрос «что сделать сейчас», а AGENTS.md — «как мы работаем в этом проекте всегда».

• Меньше повторяющихся объяснений в каждом новом чате.
• Меньше случайных изменений за пределами задачи.
• Одинаковые команды сборки, тестов и проверки результата.
• Постоянные правила контента, дизайна, безопасности и работы с данными.

Когда пора создавать AGENTS.md

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

• Вы постоянно напоминаете, какую команду запускать после изменений.
• Codex читает слишком много файлов и долго ищет нужный раздел проекта.
• Нельзя менять опубликованные URL, фирменный стиль или определённые папки.
• После каждой задачи нужен одинаковый набор проверок и отчёт.
• Команда повторяет одни и те же замечания при ревью.

Промпт, AGENTS.md, Skill и config.toml: что выбрать

Эти инструменты решают разные задачи. Не стоит превращать AGENTS.md в универсальное хранилище всего проекта.

• Промпт — одноразовая цель, контекст и критерии текущей задачи.
• AGENTS.md — постоянные правила проекта, команды и ожидания от результата.
• Skill — повторяемый рабочий процесс с подробной инструкцией, примерами, файлами и скриптами.
• config.toml — технические настройки Codex: модель, песочница, MCP, hooks и другие параметры среды.

Куда положить файл

Для начала создайте AGENTS.md в корне проекта — рядом с основными файлами конфигурации и папками приложения. Такой файл удобно хранить в Git и использовать всей командой.

• Глобальный файл в каталоге Codex home задаёт ваши личные правила для всех проектов.
• Корневой AGENTS.md содержит общие правила конкретного репозитория.
• Вложенный AGENTS.md уточняет правила для своей папки и её дочерних каталогов.
• AGENTS.override.md временно заменяет обычный файл на соответствующем уровне.

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

Как Codex собирает и применяет инструкции

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

1. Сначала проверяются глобальные AGENTS.override.md или AGENTS.md.
2. Затем Codex ищет инструкции в корне проекта.
3. После этого он проходит по вложенным папкам до текущей директории.
4. В каждой папке используется не больше одного подходящего файла.
5. Более близкие инструкции добавляются позже и имеют практический приоритет при расхождении.

Минимальный шаблон AGENTS.md

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

# AGENTS.md

## О проекте
- Цель: [что создаём и для кого]
- Важные папки: [пути и назначение]

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

## Проверки
- Сборка: [команда]
- Тесты: [команда]
- Проверь основной пользовательский сценарий.

## Границы
- Не удаляй данные и не публикуй результат без подтверждения.

## Готово, когда
- Требование выполнено, проверки пройдены, риски перечислены.

Блок 1. Карта проекта и источники истины

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

• Назначение проекта и его основная аудитория.
• Две-пять важных папок с коротким объяснением.
• Файлы, которые нельзя дублировать или обходить.
• Источник истины для контента, данных, дизайна или конфигурации.

Добавь в AGENTS.md раздел «Карта проекта». Включи только пути, подтверждённые текущей структурой. Для каждого пути дай одно предложение: что там находится и когда туда обращаться.

Блок 2. Команды запуска и проверки

Codex не должен угадывать менеджер пакетов, команду сборки или способ запуска тестов. Запишите точные команды и объясните, когда каждая обязательна.

• Установка зависимостей и локальный запуск.
• Сборка проекта перед публикацией.
• Быстрые тесты для обычных изменений.
• Дополнительные проверки для критических разделов.
• Что делать, если проверка недоступна или падает по внешней причине.

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

Блок 3. Границы и действия с подтверждением

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

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

Блок 4. Что считается готовым результатом

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

• Требование из задания выполнено без расширения объёма.
• Обязательные команды завершились успешно.
• Основной пользовательский сценарий проверен.
• Изменения, проверки, риски и допущения перечислены.
• Для публичной страницы проверены URL, мобильная версия и код ответа.

Пример AGENTS.md для SEO-блога

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

## Правила SEO-блога
- Один URL отвечает одному основному поисковому намерению.
- Не меняй URL опубликованной страницы без отдельного решения о редиректе.
- Не выдумывай факты, цифры, отзывы и источники.
- Перед публикацией проверь title, description, H1, canonical, sitemap и структурированные данные.
- Добавь внутренние ссылки на главный материал кластера и следующий полезный шаг.
- Не отправляй отдельную статью на переобход, если партия публикаций ещё не завершена.

Глобальный AGENTS.md: личные правила для всех проектов

Глобальный файл подходит для ваших личных предпочтений: язык ответа, формат отчёта, необходимость сначала показать план или правило спрашивать разрешение перед установкой зависимостей.

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

Вложенные правила и AGENTS.override.md

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

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

Как проверить, что Codex прочитал AGENTS.md

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

1. Сохраните AGENTS.md в корне проекта.
2. Перезапустите Codex или откройте новую сессию в этой папке.
3. Попросите перечислить активные источники инструкций.
4. Попросите кратко пересказать обязательные команды и запреты.
5. Дайте небольшую тестовую задачу и проверьте, выполнил ли Codex правила.

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

Как улучшать файл после каждой ошибки

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

1. Зафиксируйте конкретную ошибку, а не общее недовольство.
2. Опишите правильное поведение и безопасный путь.
3. Решите, относится правило к одной задаче, проекту или отдельной папке.
4. Добавьте одну короткую инструкцию и проверьте её на следующей задаче.
5. Удаляйте устаревшие правила, когда проект меняется.

Семь частых ошибок

Большинство проблем возникает не из-за формата файла, а из-за слишком общих, непроверенных или устаревших инструкций.

• Скопировать универсальный шаблон и не заменить плейсхолдеры.
• Записать расплывчатые пожелания вроде «делай качественно».
• Продублировать в AGENTS.md всю документацию проекта.
• Добавить команды, которые никто не проверил.
• Смешать личные предпочтения и обязательные правила команды.
• Положить секреты или персональные данные в файл репозитория.
• Продолжать старую сессию и ожидать, что новые инструкции уже загрузились.

Чек-лист хорошего AGENTS.md

Перед сохранением и после каждого заметного изменения проекта пройдите этот список.

• Файл находится в правильной папке и имеет точное имя.
• Каждое правило относится к повторяющейся ситуации.
• Команды существуют и были запущены хотя бы один раз.
• Границы называют конкретные запрещённые действия.
• Критерии готовности можно доказать проверкой или результатом.
• В файле нет секретов и лишних персональных данных.
• Вложенные правила не дублируют корневые без необходимости.
• После изменения файл проверен в новой сессии Codex.