`AGENTS.md`: постоянные инструкции для Codex

Цель: отделить личные правила работы от правил конкретного проекта, создать маленький проектный AGENTS.md и проверить, что Codex действительно его загрузил.

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

1. Три уровня инструкций

глобальный ~/.codex/AGENTS.md
  ↓ личные рабочие соглашения для всех проектов
AGENTS.md в корне репозитория
  ↓ общие правила именно этого проекта
AGENTS.md или AGENTS.override.md в подкаталоге
  ↓ локальные правила для конкретной части проекта
текущая задача пользователя

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

Важно:

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

2. Глобальный AGENTS.md

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

~/.codex/AGENTS.md

В Windows ~ обычно означает каталог профиля пользователя:

C:\Users\<пользователь>\.codex\AGENTS.md

Глобально стоит хранить только устойчивые личные договорённости:

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

Минимальный пример:

# Мои рабочие соглашения

- Общайся со мной по-русски.
- Перед нетривиальным изменением сначала исследуй фактическое состояние.
- Сохраняй несвязанные пользовательские изменения.
- Не публикуй и не изменяй production без моего явного запроса.
- Не объявляй PASS, если обязательное runtime-доказательство недоступно.
- В конце перечисляй изменения, проверки и оставшиеся ограничения.

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

3. Проектный AGENTS.md

Проектный файл лежит в корне Git-репозитория и хранится вместе с кодом:

Demo83-Sources\
├─ AGENTS.md
├─ src\
├─ openspec\
└─ ...

Он отвечает на вопросы:

1. Что это за проект и где его границы?
2. Где исходники конфигурации и расширений?
3. Что разрешено менять, а что является типовым или внешним кодом?
4. Какие команды исследования и проверки реально приняты?
5. Какие данные и базы разрешены?
6. Что является достаточной приёмкой?
7. Когда работа должна остановиться как BLOCKED?

Пример для учебного проекта:

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

## Контекст

- Это XML-исходники официальной Demo83.
- Основная конфигурация является неизменяемым baseline.
- Изменения выполняются только в расширении AI_Course_Lab.

## Границы безопасности

- Не использовать рабочие базы, клиентские данные и реальные интеграции.
- Не запускать 1С и не изменять базу без отдельного разрешения.
- Обычная копия рабочей базы не считается безопасным test-контуром.

## Рабочий цикл

- Сначала исследовать реализацию и привести пути к доказательствам.
- До записи показать план и предполагаемый scope.
- После записи показать фактический diff.
- Не расширять задачу без согласования.

## Проверка

- Статика, загрузка, обновление базы и runtime являются разными гейтами.
- Отсутствующее обязательное доказательство означает BLOCKED, а не PASS.
- Не придумывать неизвестные команды.

Это стартовый пример, а не файл для слепого копирования. Оставь только правила, которые относятся к проекту и которые команда действительно готова соблюдать.

4. Почему проектный файл полезен

Проектный AGENTS.md:

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

Но это не энциклопедия. Архитектуру, большие runbook и спецификации храни отдельно, а из AGENTS.md давай короткую карту и ссылки.

Хорошее правило предотвращает повторяющуюся ошибку, делает решение однозначнее или не даёт забыть обязательную проверку. Иначе оно, вероятно, только съедает контекст.

5. Вложенные файлы и override

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

AGENTS.md
src/
  extensions/
    AGENTS.md
tests/
  AGENTS.md

В tests/AGENTS.md можно описать fixtures и команды YAxUnit, а в src/extensions/AGENTS.md — правила CFE. Не создавай файл в каждой папке без реальных различий.

AGENTS.override.md используй для осознанной замены правил на конкретном уровне, а не как постоянный способ скрыть противоречие. Временный глобальный override удаляется после эксперимента.

6. Что нельзя перекладывать на AGENTS.md

Файл не должен:

• хранить секреты или персональные данные;
• автоматически разрешать опасные команды;
• заменять спецификацию конкретного изменения;
• заменять тесты, review и runtime-приёмку;
• содержать весь накопленный опыт команды.

AGENTS.md задаёт соглашения. Skill описывает повторяемый процесс. MCP предоставляет инструменты. Память помогает вспомнить опыт. Эти механизмы дополняют друг друга, но не взаимозаменяемы.

7. Практика

Шаг 1. Инвентаризация

В новой задаче попроси:

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

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

Шаг 2. Маленький проектный файл

В корне Demo83-Sources создай AGENTS.md из 5–10 уже доказанных правил:

• основная конфигурация не изменяется;
• работа идёт в учебном расширении;
• сначала read-only исследование;
• diff проверяет человек;
• runtime требует отдельного разрешения и доказательства;
• отсутствие обязательной проверки даёт BLOCKED.

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

Шаг 3. Проверка в новой задаче

Кратко перескажи активные правила этого проекта.
Затем подготовь read-only план исследования документа РасходТовара.
Ничего не изменяй и не запускай.

Если Codex не видит файл, проверь workspace, корень Git, имя файла и наличие AGENTS.override.md.

Шаг 4. Сравнение

В отдельной безопасной папке без проектного AGENTS.md задай ту же read-only задачу. Сравни:

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

Сравнивай соблюдение границ, а не длину ответа.

8. Что проверить перед продолжением

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

Дальше не заполняй AGENTS.md «на будущее». После повторяющейся ошибки или нового доказанного процесса добавляй одно правило, а устаревшие правила удаляй через обычное review.