AGENTS.md 怎么写才有用：Codex 的发现顺序、内容清单与排错

先看结论

AGENTS.md 是给 Codex 看的“README”：官方的说法是一种开放格式，会自动载入上下文，是把“你和团队希望 Codex 在这个仓库里怎么干活”固定下来的最佳位置。几个要点：

• 分层生效：全局一份放在 ~/.codex，仓库根一份，子目录还可以各有一份；离当前目录越近的文件，优先级越高。
• 短而准胜过长而空：官方明确说，一份简短、准确的 AGENTS.md 比一份满是模糊规则的长文件更有用。先写基础内容，同一类错误反复出现后再加规则。
• 有大小上限：合并后的内容默认最多 32 KiB（project_doc_max_bytes），超过的部分不会再加入。
• 能验证：官方提供了确认是否载入的命令，见下文。

内容整理自 OpenAI 官方文档，核验日期 2026-10-23；界面与命令以你当前版本为准。

Codex 怎么找到它

Codex 在启动时（每次运行一次；在 TUI 里通常是每次启动会话一次）构建指令链，顺序如下：

1. 全局：在 Codex 主目录（默认 ~/.codex，可用 CODEX_HOME 改）里，先找 AGENTS.override.md，没有再找 AGENTS.md。这一层只用第一个非空文件。
2. 项目：从项目根（通常是 Git 根目录）向下走到你当前的工作目录；找不到项目根就只看当前目录。每一层依次检查 AGENTS.override.md、AGENTS.md，再到 project_doc_fallback_filenames 里配置的备用文件名。每个目录最多取一个文件。
3. 合并：从根向下把文件拼起来，中间用空行隔开。离当前目录近的文件出现在后面，因此覆盖前面的指导。

空文件会被跳过；累计大小达到 project_doc_max_bytes（默认 32 KiB）后停止加入。遇到上限，可以调大上限，或把指令拆到嵌套目录里。

该写什么

官方最佳实践给出的内容清单：

• 仓库结构和重要目录
• 怎么运行项目
• 构建、测试、lint 命令
• 工程约定与 PR 要求
• 限制与“不要做”的规则
• “做完”意味着什么，以及怎么验证

CLI 里的 /init 可以在当前目录生成一份起步的 AGENTS.md。官方的态度是：它是个好起点，但要按你的团队真实的构建、测试、审查、发布方式改写。

官方示例：全局、仓库、子目录三层

全局（~/.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.

仓库根（团队共享的基础约定）：

# 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 先载入全局文件，再载入仓库根的 AGENTS.md，最后是支付目录的覆盖文件。Codex 走到当前目录就不再继续向下找，所以覆盖文件要尽量放在专门工作的目录旁边。

想临时覆盖全局规则而不删除原文件，可以用 ~/.codex/AGENTS.override.md；删掉它就恢复原来的共享指导。

怎么保持精简

下面四条出自官方最佳实践：

• 从基础开始：只有在发现重复犯错之后，才加新规则。
• 主文件保持简洁：文件变大时，把规划、代码审查、架构等任务专用内容放进单独的 markdown 文件，在主文件里引用。
• 同一个错误出现两次，让 Codex 做复盘，再据此更新 AGENTS.md：规则来自真实摩擦，才不会写成一堆不会被用到的“万一”。
• 别把所有东西塞进提示：每次都要重复的长期规则，放进 AGENTS.md；反复出现的完整流程，做成 Skill。

另外要分清三个位置（编者归纳）：提示放这一次任务特有的目标和完成标准，AGENTS.md 放长期不变的约定，Skill 放可复用的多步流程。任务提示怎么写见一条好任务怎么写；本站长任务一文也讲了“不要把所有知识塞进一个超长 AGENTS.md”，见Codex 长任务工作流。

文件名与大小上限怎么调

仓库里已经有别的文件名（比如 TEAM_GUIDE.md）时，可以加进备用名单；官方示例同时把上限调到了 64 KiB：

# ~/.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；不在名单里的文件名不会参与发现。

需要用不同的配置主目录时（比如给项目专用的自动化用户），可以设置 CODEX_HOME，官方示例是：

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

给代码审查加规则

如果你用 Codex 在 GitHub 上做代码审查，官方建议在离被审代码最近的 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。设置细节见官方 GitHub 集成页的 “Customize what Codex reviews”。审查通道怎么选、规则怎么用三个 PR 验证，见用 Codex 做代码审查。

怎么验证它真的载入了

• 在仓库根运行官方给的命令，Codex 应按优先级顺序复述全局与项目文件里的内容：

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

• 想确认嵌套覆盖是否生效，用 --cd 进入子目录再问：

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

• 想审计 Codex 到底载入了哪些文件，可以用 codex -c log_dir=./.codex-log 开启明文 TUI 日志，查看 ./.codex-log/codex-tui.log；如果启用了会话日志，也可以看最新的 session-*.jsonl。
• 指令看起来过期时，在目标目录重启 Codex：它每次运行（和每个 TUI 会话开始时）都会重建指令链，没有需要手动清理的缓存。

常见问题

• 什么都没载入：确认你在预期的仓库里，codex status 报告的工作区根是否正确；文件内容不能为空，Codex 会忽略空文件。
• 出现了不想要的指导：检查目录树更上层或 Codex 主目录里是否有 AGENTS.override.md，改名或删除它即可回到常规文件。
• 备用文件名没生效：核对 project_doc_fallback_filenames 有没有拼写错误，然后重启 Codex。
• 指令被截断：调大 project_doc_max_bytes，或把大文件拆到嵌套目录里，保证关键内容不被截掉。
• 配置主目录混乱：启动前运行 echo $CODEX_HOME；非默认值意味着 Codex 读取的主目录和你编辑的不是同一个。

一份起步清单

1. 在仓库根用 /init 生成起步文件，删掉不符合团队实际的内容。
2. 补上运行、构建、测试、lint 命令，以及“什么算做完”。
3. 把只对某个目录有效的规则放到该目录的 AGENTS.md（或 AGENTS.override.md）。
4. 用上面的命令验证载入顺序。
5. 之后每次发现 Codex 重复犯同一个错误，复盘并补一条规则；规则太多时拆文件。

更多常见误区见Codex 新手常见的 8 个错误。

官方来源

• Custom instructions with AGENTS.md：发现顺序、示例、备用文件名、验证与排错、Code Review Rules
• Best practices：该写什么、/init、保持精简与复盘
• Config advanced：Project instructions discovery：project_doc_max_bytes 等配置项
• Code review in GitHub：自定义审查规则的设置
• AGENTS.md 官方站点：格式的开放说明

核验日期：2026-10-23。