交流群即将上线
05 · 用 AGENTS.md 交代项目规矩
为什么需要它
第一天你会在每次对话开头打一遍：「这个项目用 pnpm，改完 JS 要跑 npm test， 不要随便加生产依赖。」第五天你会烦。第十天你会漏掉一条，然后它给你装了个新包。
AGENTS.md 就是把这些话写进仓库，让它每次自己读。 Codex 在执行任何工作前都会读 AGENTS.md。
它是怎么找的
Codex 启动时构建一条指令链（每次运行只构建一次；在 TUI 里通常是每次开会话时构建一次），顺序是：
第一层，全局。 在 Codex 主目录（默认 ~/.codex，除非你设了 CODEX_HOME）： 如果 AGENTS.override.md 存在就读它，否则读 AGENTS.md。 这一层只用按顺序找到的第一个非空文件。
第二层，项目。 从项目根目录（通常是 Git 根）开始，沿目录树往下逐级走到当前工作目录。 每一级依次找 AGENTS.override.md、AGENTS.md，再找 project_doc_fallback_filenames 里配的回退名。 每个目录最多纳入一个文件。 找不到项目根就只看当前目录。
第三层，合并。 从根往下拼接，用空行分隔。 越靠近当前目录的文件在合并后出现得越晚，因此会覆盖前面的指令。
空文件会被跳过；合并后的大小一到 project_doc_max_bytes 上限（默认 32 KiB）就不再往里加。
三层怎么分工
~/.codex/AGENTS.md ← 你个人的习惯，跨所有仓库
<repo>/AGENTS.md ← 这个仓库的规矩，提交进版本库
<repo>/services/payments/AGENTS.override.md ← 这个子目录的特殊规矩全局那份写你自己的偏好，别写项目相关的东西：
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.仓库根目录那份写团队约定，跟着代码一起提交：
md
# AGENTS.md
## Repository expectations
- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.子目录那份只写这块地方跟别处不一样的地方：
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.从 payments 目录启动的话，它会先报告全局文件，然后是仓库根的 AGENTS.md，最后是这份覆盖文件。
Codex 找到当前目录就停了
所以覆盖文件要放在离相关工作最近的目录里。放在爷爷目录上， 从孙子目录启动时它照样能读到（因为是从根往下走），但放太靠上就没有「只对这块生效」的意思了。
验证它确实读到了
bash
codex --ask-for-approval never "Summarize the current instructions."预期是它先引用 ~/.codex/AGENTS.md 里的条目，再说方案。 想看得更细：
bash
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."AGENTS.override.md 是干什么的
需要临时全局覆盖、又不想删掉基础文件时用它——建一个 ~/.codex/AGENTS.override.md， 删掉它就恢复原来的共享指令。同一层里 override 存在就完全取代 AGENTS.md，不是叠加。
该写什么，不该写什么
该写：
- 跑什么命令（测试、lint、构建），特别是跟惯例不一样的
- 硬性红线（别改生成的文件、别加依赖、别动某个目录）
- 项目里那些不成文的约定（错误处理风格、日志格式、目录职责）
别写：
- 代码本身能说明的事（技术栈、目录结构，它自己会看）
- 长篇的架构介绍——32 KiB 上限不是给你写文档用的，写多了后面的指令会被截掉
- 格式和 lint 规则——那是 CI 的活，写进
AGENTS.md只是让它多花 Token
顺手加一节代码审查规则
如果你用 GitHub 上的 Codex 代码审查， 可以在最贴近相关代码的 AGENTS.md 里加一节 ## Code Review Rules：
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.写法上保持简洁：说清楚要标记什么行为、安全的做法是什么或例外在哪。 仓库范围的检查放根目录，服务专属的放嵌套文件。
已经有别的文件名了
如果团队已经在用 TEAM_GUIDE.md 之类的名字，把它加进回退列表：
toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536改完重启 Codex 或跑一条新命令加载配置。之后每个目录的检查顺序变成 AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md， 不在列表里的文件名一律忽略。
顺便一提：规则（rules）是另一回事
AGENTS.md 说的是「怎么干活」，规则管的是 「哪些命令能在沙盒外跑」——是权限，不是指令。规则文件放在生效配置层旁的 rules/ 目录里（比如 ~/.codex/rules/default.rules），用 Python 风格的 prefix_rule 写：
python
prefix_rule(
pattern = ["gh", "pr", "view"],
decision = "prompt",
justification = "Viewing PRs is allowed with approval",
)在 TUI 里把某条命令加进允许列表时，Codex 就是把它写进 ~/.codex/rules/default.rules。 这个功能还处于实验阶段，可能会变。