14 AGENTS.md 项目规则
AGENTS.md 是 Codex 开始工作前读取的持久项目说明。它适合记录项目约定、测试命令、代码风格、禁止改动范围，以及任务完成前必须执行的验证。规则离目标文件越近，优先级越高。
::: tip 官方资料核对 本文根据 OpenAI 当前 AGENTS.md 文档于 2026-07-26 核对。Codex 通常在一次运行或新会话开始时构建规则链；修改规则后建议新建任务或重新启动会话验证。 :::
AGENTS.md 加载顺序
Codex 会从全局范围走到当前工作目录，并把找到的规则合并起来：
| 顺序 | 位置 | 用途 |
|---|---|---|
| 1 | ~/.codex/AGENTS.override.md 或 ~/.codex/AGENTS.md | 所有项目共用的个人规则 |
| 2 | Git/项目根目录的 AGENTS.override.md 或 AGENTS.md | 整个仓库的约定 |
| 3 | 当前目录路径上的子目录规则 | 某个模块或团队的更具体要求 |
同一目录最多读取一个规则文件，优先检查 AGENTS.override.md，再检查 AGENTS.md。越靠近当前工作目录的内容越晚加入，因此可以覆盖上层规则。空文件会被跳过；默认合并大小上限是 32 KiB。
适合写什么
- 项目技术栈和主要目录说明
- 常用开发、测试、构建命令
- 代码风格、命名规则、提交规范
- 哪些文件或目录不能随便改
- 任务完成前需要跑哪些验证
- 团队希望 Codex 汇报结果的格式
可复制的 AGENTS.md 模板
## 项目说明
这是一个 Nuxt 内容站点，文档在 content/1.codex 下。
## 修改边界
- 只修改当前任务涉及的目录
- 保留用户已有的未提交改动
- 不修改生成产物，除非任务明确要求
## 常用命令
- 类型检查：npm run typecheck
- 内容检查：npm run seo:check
- 构建：npm run generate
## 编码要求
- 修改 Markdown 时保持中文表达简洁
- 不要提交真实 API Key、兑换码或账号信息
- 修改前先查看同目录已有文档风格
## 完成标准
- 运行类型检查和内容检查
- 检查内部链接和生成结果
- 完成后说明验证命令和结果
这个模板刻意只写可执行规则。像“写出高质量代码”这类无法验证的口号帮助很小，最好改成明确的命令、路径或验收条件。
全局规则和项目规则怎么分
- 全局
~/.codex/AGENTS.md：个人长期习惯，例如包管理器、汇报格式和新增依赖前确认。 - 仓库根目录
AGENTS.md：所有贡献者都需要遵守的测试、目录和安全要求。 - 子目录
AGENTS.md：只对某个应用、服务或内容目录生效的规则。 AGENTS.override.md：需要临时或明确覆盖同目录基础规则时使用。
不要把仅对一次任务有效的要求长期写入仓库规则；这类限制直接写在当前提示中更合适。
子目录规则示例
repo/
├─ AGENTS.md
├─ web/
│ ├─ AGENTS.md
│ └─ src/
└─ api/
├─ AGENTS.override.md
└─ src/
在 web/src 工作时，Codex 会组合根目录与 web/AGENTS.md；在 api/src 工作时，同目录优先读取 api/AGENTS.override.md。
怎么验证 Codex 已读取规则
不要只根据文件存在就认为生效。新建会话后，让 Codex 列出加载到的规则来源：
codex --ask-for-approval never "列出当前加载的指令来源，并总结每个文件的关键要求。"
如果子目录规则没有出现，检查：
- Codex 的当前工作目录是否真的位于该子目录下。
- 文件是否为空、名称是否写错。
- 同目录是否存在优先级更高的
AGENTS.override.md。 - 规则总长度是否超过配置的
project_doc_max_bytes。 - 修改规则后是否仍在使用启动前创建的旧会话。
已有其他规则文件怎么办
如果仓库已经使用 TEAM_GUIDE.md 等名称，可以在 config.toml 中设置回退文件名：
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
Codex 仍会优先检查 AGENTS.override.md 和 AGENTS.md，之后才检查回退名称。调整大小上限前，优先删除重复说明或拆到更靠近代码的子目录。
AGENTS.md 最佳实践
- 写真实存在的命令，并说明何时运行。
- 用绝对明确的目录边界代替“不要乱改”。
- 把安全、迁移和发布限制写在相关模块附近。
- 规则与 CI 保持一致，避免要求无法执行的检查。
- 示例只放最短必要片段，详细背景链接到已有文档。
- 发生误改后，把真正缺失的约束补进规则，不要无限堆叠泛化提醒。
AGENTS.md 不需要一开始写得很长。先写最容易出错且可以验证的规则，再随着项目迭代沉淀重复提醒。