Codex AGENTS.md
AGENTS.md — это файл пользовательских инструкций Codex, который позволяет задавать глобальные указания и соглашения о рабочем процессе для Codex.
В этом разделе подробно описано, как создать и использовать AGENTS.md.
Что такое AGENTS.md?
Codex автоматически читает при запускеAGENTS.mdфайл, использующий иерархический механизм "глобальная конфигурация + переопределения на уровне проекта", чтобы каждая задача наследовала согласованные рабочие соглашения независимо от того, какой репозиторий кода вы открываете.
AGENTS.md — это файл инструкций, который Codex читает перед выполнением любой работы, что позволяет вам:
- Задавать глобальные стандарты кодирования
- Определять рабочие процессы для конкретного проекта
- Предоставлять разные указания для разных каталогов
- Стандартизировать практики командной разработки
С AGENTS.md вы можете гарантировать, что Codex соблюдает единообразные соглашения по всей кодовой базе.
Как Codex обнаруживает руководства
Codex строит цепочку инструкций в соответствии со следующими приоритетами.
Трёхуровневый механизм загрузки
| Уровень | Правило загрузки | Описание |
|---|---|---|
| Глобальный уровень | Читает~/.codex/AGENTS.override.md |
Если его нет, читает~/.codex/AGENTS.md, берёт только первый непустой файл |
| Уровень проекта | Сканирует от корневого каталога Git уровень за уровнем до текущего каталога | Проверяет каждый уровень по порядкуAGENTS.override.md → AGENTS.md → project_doc_fallback_filenamesальтернативные имена файлов в |
| Уровень объединения | Объединяет от корня к листу по порядку | Файлы ближе к текущему каталогу появляются позже и имеют более высокий приоритет |
Ограничение общего размера по умолчанию после объединения составляет 32 KiB (управляется с помощью
project_doc_max_bytes), а избыточная часть будет обрезана.
Шаг 1: Создание глобальной конфигурации
Глобальная конфигурация применяется ко всем проектам и подходит для универсальных рабочих соглашений.
Создайте каталог конфигурации
mkdir -p ~/.codex
Убедитесь, что домашний каталог Codex существует; все глобальные конфигурации размещаются в этом каталоге.
Запишите глобальные соглашения
Создайте~/.codex/AGENTS.mdфайл, запишите соглашения, общие для всех проектов:
# ~/.codex/AGENTS.md ## 全局工作约定 - 修改 JavaScript 文件后，始终运行 npm test - 安装依赖时优先使用 pnpm - 新增生产依赖前先请求确认
Проверьте, что конфигурация вступила в силу
Выполните следующую команду; Codex должен вывести записи, которые вы написали:
codex --ask-for-approval never "Summarize the current instructions."
Если вам нужно временное глобальное переопределение, можно создать
AGENTS.override.md, а удаление этого файла восстанавливает исходную конфигурацию.
Шаг 2: Уровневая конфигурация по репозиториям
Файлы уровня проекта заставляют Codex следовать соглашениям, специфичным для репозитория, при этом наследуя глобальную конфигурацию.
Добавьте соглашения уровня репозитория
Создайте в корневом каталоге проектаAGENTS.md：
# AGENTS.md ## 仓库约定 - 提 PR 前运行 npm run lint - 修改公共工具行为时，同步更新 docs/ 中的文档
Добавьте переопределения для подкаталогов
Для подкаталогов с особыми потребностями (таких какservices/payments/), создайтеAGENTS.override.mdчтобы выполнить локальные переопределения:
# services/payments/AGENTS.override.md ## 支付服务规则 - 使用 make test-payments 替代 npm test - 轮换 API Key 前必须通知安全频道
Полная структура каталогов
Ниже приведена типичная структура каталогов после загрузки репозиторияAGENTS.md:
repo/
├── AGENTS.md # 仓库级约定（加载）
└── services/
├── payments/
│ ├── AGENTS.md # 被跳过（override 优先）
│ └── AGENTS.override.md # 支付服务覆写（加载）
└── search/
└── AGENTS.md # 搜索服务约定（加载）
В том же каталоге,
AGENTS.override.mdесли он существует, соседнийAGENTS.mdбудет пропущен.
Проверьте порядок загрузки
Запустите Codex из подкаталога и просмотрите источники загруженных инструкций:
codex --cd services/payments --ask-for-approval never \ "List the instruction sources you loaded."
Ожидаемый результат: перечислите по порядку глобальный файл, файл корня репозитория и файл переопределения платежного сервиса.
Дополнительные параметры
Следующие две возможности применяются в сценариях, когда необходимо дополнительно настроить поведение загрузки инструкций.
Пользовательское имя файла
Если в проекте уже есть привычныйTEAM_GUIDE.md, вы можете добавить его в список резервных вариантов в файле конфигурации, и Codex будет рассматривать его как файл инструкций:
# ~/.codex/config.toml # 追加回退文件名并提高合并上限 project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] project_doc_max_bytes = 65536
После изменения порядок проверки для каждого каталога становится:AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md, берётся первый существующий файл.
После изменения конфигурации необходимо перезапустить Codex, чтобы
config.tomlизменения вступили в силу.
Переключить каталог конфигурации
ЧерезCODEX_HOMEпеременная среды, вы можете использовать независимые профили конфигурации для разных проектов или автоматизированных процессов:
CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"
На этом этапе Codex будет использовать.codexподкаталог в текущем каталоге для чтения глобальной конфигурации, а не стандартный~/.codex。
Проверка и отладка
Следующая команда позволяет быстро проверить источник текущих активных инструкций.
Быстрая проверка
# 从仓库根目录检查全局 + 项目指令 codex --ask-for-approval never "Summarize the current instructions." # 从子目录检查嵌套覆写 codex --cd subdir --ask-for-approval never "Show which instruction files are active."
Включить подробные журналы
Если вам нужно детально проверить процесс загрузки инструкций, можно включить журналирование TUI:
# 输出 TUI 日志到本地目录 codex -c log_dir=./.codex-log # 日志文件位于 ./.codex-log/codex-tui.log
Устранение типичных проблем
В следующей таблице приведены возможные проблемы при конфигурации и направления устранения неполадок.
| Симптом | Направление устранения неполадок |
|---|---|
| Ничего не загружено | Убедитесь, что файл не пуст; запуститеcodex statusПроверьте, корректен ли корневой каталог рабочей области |
| Появились неверные инструкции | Проверьте, не осталось ли лишнегоAGENTS.override.md |
| Имя резервного файла не применяется | Убедитесьconfig.tomlв правильности написания в , и перезапустите Codex, чтобы это вступило в силу. |
| Содержимое инструкции обрезано | Увеличьтеproject_doc_max_bytes, или разделите большие файлы на несколько уровней каталогов |
| Путаница с профилем | Запуститеecho $CODEX_HOME, убедитесь, что он указывает на ожидаемый каталог |