Пользовательские инструкции с AGENTS.md

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

Как Codex находит указания

При запуске Codex формирует цепочку инструкций (один раз за запуск; в TUI это обычно означает один раз для каждого запущенного сеанса). Поиск выполняется в следующем порядке приоритета:

1. Глобальная область: В домашнем каталоге Codex (по умолчанию ~/.codex, если не задано значение CODEX_HOME) Codex читает AGENTS.override.md, если такой файл существует. В противном случае Codex читает AGENTS.md. На этом уровне Codex использует только первый непустой файл.
2. Область проекта: Начиная с корневого каталога проекта (обычно это корневой каталог Git), Codex последовательно проходит по каталогам до текущего рабочего каталога. Если Codex не удаётся найти корневой каталог проекта, он проверяет только текущий каталог. В каждом каталоге на этом пути он ищет сначала AGENTS.override.md, затем AGENTS.md, а после — резервные имена из project_doc_fallback_filenames. Codex включает не более одного файла из каждого каталога.
3. Порядок объединения: Codex объединяет файлы от корневого каталога к текущему, разделяя их пустыми строками. Файлы, расположенные ближе к текущему каталогу, переопределяют более ранние указания, поскольку находятся ниже в объединённом запросе.

Codex пропускает пустые файлы и прекращает добавлять новые, когда общий размер достигает ограничения, заданного параметром project_doc_max_bytes (по умолчанию 32 КиБ). Подробнее об этих параметрах см. в разделе Поиск инструкций проекта. Если вы достигли ограничения, увеличьте его или распределите инструкции по вложенным каталогам.

Создание глобальных указаний

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

1. Убедитесь, что каталог существует:

   mkdir -p ~/.codex

2. Создайте ~/.codex/AGENTS.md с повторно используемыми предпочтениями:

   # ~/.codex/AGENTS.md
   
   ## Working agreements
   
   - Always run `npm test` after modifying JavaScript files.
   - Prefer `pnpm` when installing dependencies.
   - Ask for confirmation before adding new production dependencies.

3. Запустите Codex в любом каталоге и убедитесь, что файл загружается:

   codex --ask-for-approval never "Summarize the current instructions."

   Ожидаемый результат: прежде чем предложить план работы, Codex цитирует пункты из ~/.codex/AGENTS.md.

Используйте ~/.codex/AGENTS.override.md, когда требуется временно переопределить глобальные настройки, не удаляя основной файл. Удалите файл переопределения, чтобы восстановить общие указания.

Многоуровневые инструкции проекта

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

1. В корневом каталоге репозитория добавьте AGENTS.md с основными инструкциями по настройке:

   # AGENTS.md
   
   ## Repository expectations
   
   - Run `npm run lint` before opening a pull request.
   - Document public utilities in `docs/` when you change behavior.

2. Добавляйте переопределения во вложенные каталоги, если отдельным командам нужны другие правила. Например, в каталоге services/payments/ создайте AGENTS.override.md:

   # services/payments/AGENTS.override.md
   
   ## Payments service rules
   
   - Use `make test-payments` instead of `npm test`.
   - Never rotate API keys without notifying the security channel.

3. Запустите Codex из каталога платежей:

   codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

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

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

Вот как может выглядеть репозиторий после добавления глобального файла и переопределения для платежей:

<FileTree class="mt-4" tree={[ { name: "AGENTS.md", comment: "Требования репозитория", highlight: true, }, { name: "services/", open: true, children: [ { name: "payments/", open: true, children: [ { name: "AGENTS.md", comment: "Игнорируется, поскольку существует переопределение", }, { name: "AGENTS.override.md", comment: "Правила сервиса платежей", highlight: true, }, { name: "README.md" }, ], }, { name: "search/", children: [{ name: "AGENTS.md" }, { name: "…", placeholder: true }], }, ], }, ]} />

Добавление правил проверки кода

Для проверки кода с помощью Codex в GitHub добавьте раздел ## Code Review Rules в файл AGENTS.md, расположенный ближе всего к коду, к которому применяются правила. Поместите проверки для всего репозитория в корневой файл, а проверки для конкретного сервиса — во вложенный файл.

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

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

Настройка резервных имён файлов

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

1. Измените конфигурацию Codex:

   # ~/.codex/config.toml
   project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
   project_doc_max_bytes = 65536

2. Перезапустите Codex или выполните новую команду, чтобы загрузилась обновлённая конфигурация.

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

После настройки списка резервных имён Codex воспринимает альтернативные файлы как инструкции:

<FileTree class="mt-4" tree={[ { name: "TEAM_GUIDE.md", comment: "Обнаружен благодаря списку резервных имён", highlight: true, }, { name: ".agents.md", comment: "Резервный файл в корневом каталоге", }, { name: "support/", open: true, children: [ { name: "AGENTS.override.md", comment: "Переопределяет резервные указания", highlight: true, }, { name: "playbooks/", children: [{ name: "…", placeholder: true }], }, ], }, ]} />

Задайте переменную окружения CODEX_HOME, если требуется другой профиль, например пользователь автоматизации для конкретного проекта:

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

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

Проверка настройки

• Выполните codex --ask-for-approval never "Summarize the current instructions." из корневого каталога репозитория. Codex должен вывести указания из глобальных файлов и файлов проекта в порядке приоритета.
• Используйте codex --cd subdir --ask-for-approval never "Show which instruction files are active.", чтобы убедиться, что вложенные переопределения заменяют более общие правила.
• Чтобы проверить, какие файлы инструкций загрузил Codex, включите текстовый журнал TUI с помощью codex -c log_dir=./.codex-log и проверьте ./.codex-log/codex-tui.log либо изучите последний файл session-*.jsonl, если включено журналирование сеансов.
• Если инструкции выглядят устаревшими, перезапустите Codex в целевом каталоге. Codex заново формирует цепочку инструкций при каждом запуске (и в начале каждого сеанса TUI), поэтому вручную очищать кеш не требуется.

Устранение проблем с поиском

• Ничего не загружается: Убедитесь, что находитесь в нужном репозитории и что codex status сообщает ожидаемый корневой каталог рабочей области. Проверьте, что файлы инструкций не пусты: Codex игнорирует пустые файлы.
• Отображаются неверные указания: Проверьте, нет ли файла AGENTS.override.md выше в дереве каталогов или в домашнем каталоге Codex. Переименуйте или удалите файл переопределения, чтобы вернуться к обычному файлу.
• Codex игнорирует резервные имена: Убедитесь, что имена без опечаток перечислены в project_doc_fallback_filenames, а затем перезапустите Codex, чтобы обновлённая конфигурация вступила в силу.
• Инструкции усечены: Увеличьте project_doc_max_bytes или распределите большие файлы по вложенным каталогам, чтобы сохранить важные указания целиком.
• Путаница с профилем: Перед запуском Codex выполните echo $CODEX_HOME. Значение, отличное от стандартного, указывает Codex на домашний каталог, отличный от того, который вы редактировали.

Дальнейшие действия

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