用 AGENTS.md 给 Codex 写规则

为什么值得花时间在这上面

官方对 AGENTS.md 的一句话说明是：Codex 在做任何工作之前读取 AGENTS.md 文件。通过把全局指导与项目专属覆盖分层，你可以让每次任务都从一致的预期开始，无论打开的是哪个仓库。

换句话说，这不是"文档"，是每次运行都会被注入的前置约束。你在这里写的东西，比你在每次对话开头重复粘贴的东西可靠得多。

发现顺序：三步，记住这三步就够了

Codex 在启动时构建一条指令链（每次运行一次；在 TUI 中通常意味着每个启动的会话一次）。

第一步，全局范围。 在你的 Codex home 目录（默认 ~/.codex，除非你设置了 CODEX_HOME）中，Codex 读取 AGENTS.override.md（如果存在），否则读取 AGENTS.md。这一层只使用第一个非空文件。

第二步，项目范围。 从项目根目录（通常是 Git 根）开始，Codex 向下走到你的当前工作目录。找不到项目根目录时，它只检查当前目录。 路径上的每个目录里，它依次检查 AGENTS.override.md、AGENTS.md，然后是 project_doc_fallback_filenames 里的备用名。每个目录最多包含一个文件。

第三步，合并顺序。 Codex 从根目录向下拼接这些文件，以空行连接。越靠近你当前目录的文件越靠后出现在合并提示里，因此覆盖更早的指导。

还有一条容量约束：Codex 跳过空文件，并在合并大小达到 project_doc_max_bytes（默认 32 KiB）后停止添加文件。碰到上限时，调高它，或者把指令拆分到嵌套目录里。

全局指导

在 Codex home 目录里建立持久的默认值，让每个仓库都继承你的工作约定。

mkdir -p ~/.codex

然后写 ~/.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.

验证它被加载了：

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

预期结果是 Codex 在提出工作方案之前，先引用 ~/.codex/AGENTS.md 里的条目。

需要临时的全局覆盖而又不想删掉基础文件时，用 ~/.codex/AGENTS.override.md；移除这个 override 即可恢复共享的指导。

分层项目指令

仓库级文件让 Codex 了解项目规范，同时仍然继承你的全局默认值。

仓库根目录：

# AGENTS.md

## Repository expectations

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

需要不同规则的嵌套目录，比如 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.

从该目录启动来验证：

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

预期结果是 Codex 先报告全局文件，然后是仓库根的 AGENTS.md，最后是 payments 的 override。

官方给了一条位置上的建议：Codex 到达你的当前目录就停止搜索，所以把覆盖放在尽可能靠近专门工作的位置。

代码评审规则

对 GitHub 上的 Codex 代码评审，在离被规则约束的代码最近的 AGENTS.md 中添加一个 ## Code Review Rules 小节。仓库级检查放根目录，服务专属检查放嵌套文件。

官方给的例子展示了一条好规则该有的形状：

## 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.

注意它有两部分：要标记的行为，加上一条安全路径。写法建议是三条——保持简洁、解释要标记的行为以及任何安全路径或例外，并且把格式和 lint 检查留给 CI。

最后这条值得听：让评审去做人才能做的判断，让 CI 去做机器擅长的检查。

自定义备用文件名

仓库已经在用别的文件名（比如 TEAM_GUIDE.md）时，把它加进备用列表，Codex 就会把它当作指令文件对待。

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

重启 Codex 或运行一条新命令，更新后的配置才会加载。

之后 Codex 在每个目录里按这个顺序检查：AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。不在这个列表中的文件名在指令发现时会被忽略。

顺带一提，上面那行 project_doc_max_bytes = 65536 把上限从 32 KiB 提到了 64 KiB，允许在截断前合并更多指导。

用 CODEX_HOME 切换配置档

想用不同的配置档——比如一个项目专属的自动化用户——设置 CODEX_HOME 环境变量：

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

预期输出会列出相对于这个自定义 .codex 目录的文件。

排查

什么都没加载。 确认你在预期的仓库里，并且 codex status 报告的工作区根目录符合预期。确保指令文件有内容——Codex 忽略空文件。

出现了错误的指导。 在目录树更上层或你的 Codex home 里找一个 AGENTS.override.md。重命名或移除这个 override，就会回落到常规文件。

Codex 忽略了备用文件名。 确认你在 project_doc_fallback_filenames 里写对了名字，然后重启 Codex 让更新后的配置生效。

指令被截断了。 调高 project_doc_max_bytes，或者把大文件拆分到嵌套目录里，以保住关键指导。

配置档混淆。 启动 Codex 之前先 echo $CODEX_HOME。非默认值意味着 Codex 指向的 home 目录和你编辑的那个不是同一个。

指令看起来是旧的。 在目标目录重启 Codex。官方明确说明：Codex 在每次运行时（以及每个 TUI 会话开始时）重建指令链，因此没有需要手动清理的缓存。