AGENTS.md：把项目规则交给 Codex

中文实战指南 · 核验于 2026-11-14

每次让 Codex 接手项目，都要重新解释目录结构和测试命令？可以把这些约定写进 AGENTS.md，让它先读项目说明，再开始工作。

这个文件适合记录代码位置、开发习惯、测试方法和需要确认的操作。一次任务的临时要求仍放在任务说明里，方便长期维护。

哪个文件会生效

Codex 会读取全局说明，再从项目根目录向当前工作目录构建项目说明链。每层目录只选择一个说明文件；AGENTS.override.md 优先于 AGENTS.md，更靠近当前目录的规则处理局部差异。

默认项目说明预算为 32 KiB，由 project_doc_max_bytes 控制。规则很长时应提炼入口，按任务引用细节，不依赖末尾的大段材料一定被加载。启动目录改变时，生效的目录链也可能改变。

写入可以执行的信息

下面是项目规则的结构示例，命令必须换成仓库里真实存在的入口：

# Project guide

- Source: `src/`; focused tests: `tests/`.
- Run the package's documented test command after behavior changes.
- Preserve existing unrelated changes.
- Report the files changed, checks run, and unresolved failures.
- Publishing and production changes require explicit authorization.

不要写“遵守最佳实践”代替具体检查。若不同目录有不同语言或发布方式，把差异放在对应子目录的规则中。

如何确认规则被理解

新开任务后，让 Codex 先说明当前工作目录、已读规则和准备运行的检查入口。对照实际文件，而不是只看它说“已遵守”。出现冲突时先核对更近目录是否覆盖，以及文件是否超过读取预算。

AGENTS.md 提供指令，不直接改变沙箱和工具权限。涉及访问控制继续看 配置 与 权限。