Codex AGENTS.md 指南：写出可以验证的项目指令
用具体示例编写 AGENTS.md，检查指令加载范围，并通过小任务排查 Codex 忽略规则的问题。
最近更新: 2026-10-29
作者 Stometa · 核验依据与日期见正文中的来源和运行记录。
2026 年 10 月 25 日，我们用 Codex CLI 0.163.0、同一句 prompt 和两份互相冲突的 AGENTS.md 跑了两次。两次的答案都跟着启动目录走（fixture 根目录得到 ROOT，其下的 service/ 子目录得到 CHILD），工具调用为 0 次。本文由 Codex Pulse 独立编写，官方文档于 2026 年 10 月 29 日重新核对；下面的运行发生在 10 月 25 日，只覆盖指令加载。
先检查指令来源
官方 AGENTS.md 指南 写明：Codex 从项目根目录（通常是 Git 根目录）出发，向下走到当前工作目录。每个目录先查 AGENTS.override.md，再查 AGENTS.md。离工作目录越近的文件，在合并后的 prompt 里越靠后，优先级越高。合并后的总大小受 project_doc_max_bytes 限制（默认 32 KiB），指令链每次运行都会重新构建，所以新会话会读到修改。指令文件表达工作要求，无法授予文件系统或网络权限。
官方给出的检查方式，是让 Codex 说出当前生效的指令文件。这是在问模型。下一节看 Codex 实际收到了什么。
10 月 25 日的观察：同一句 prompt，两个目录
我们在一个本地 Git checkout 下的固定 fixture 里放了两份文件。上层文件要求被问到诊断标记时回答 ROOT；其 service/ 子目录里的文件要求回答 CHILD。每个启动目录各开一个新的 gpt-6-sol 会话，通过 codex exec 运行，read-only sandbox，approval policy 为 never，reasoning effort 为 medium，prompt 如下：
Without using tools or reading files, answer with only the diagnostic marker already supplied in your instructions.
| 启动目录 | 用户级文件之后注入的项目文件 | 最终答案 | 工具调用 |
|---|---|---|---|
| fixture 根 | checkout 根 AGENTS.md、fixture 根 AGENTS.md | ROOT | 0 |
service/ | 同样两份，外加 service/AGENTS.md | CHILD | 0 |
会话记录显示了 Codex 收到的内容。每个 rollout 的第一条 user 消息以 # AGENTS.md instructions for <启动目录> 开头：先是用户级文件，然后是 --- project-doc --- 分隔符，再从 checkout 根目录开始依次排列项目文件。用户级文件和 checkout 根文件里都没有诊断标记。只有 service/ 这次运行的注入内容里包含 CHILD 指令。
prompt 禁止使用工具，记录里也没有工具调用条目，所以两次答案里的标记来自注入文本，模型没有打开任何文件。
这两次运行覆盖的范围很窄：父文件与子文件之间的标记选择，一个模型，一个 CLI 版本，每个目录一次。它们没有覆盖编辑过程中 Codex 是否遵守规则、AGENTS.override.md、32 KiB 上限，也没有覆盖结果重复出现的频率。
在哪里查看 Codex 收到的内容
在我们的运行里，会话记录是 $CODEX_HOME/sessions/YYYY/MM/DD/ 下的 rollout-*.jsonl。打开你那次会话对应的文件，读第一条 user 消息：注入的文件按 Codex 合并的顺序列在那里。官方指南还说明了 TUI 的明文日志（codex -c log_dir=./.codex-log）。
修改任何措辞之前，先把这份列表和你预期的文件对照。文件不在列表里，就先查放置位置、文件名和工作目录；改写规则帮不上忙。
从一个反复出现的问题开始
假设 agent 总是直接修改生成文件。先保存一个具体案例：任务、被修改的路径、正确的生成命令。然后写清楚应该改哪个源文件，以及怎样检查生成结果是否一致。“提高代码质量”没有提供可比较的验收结果。
下面是可放入仓库 AGENTS.md 的编辑模板。使用前，把方括号里的占位内容替换成真实路径和命令：
# 项目工作约定
## 修改之前
- 阅读 [项目说明路径]，检查当前 diff。
- 保留开始任务前已经存在的改动。
## 生成文件
- 修改 [源文件路径]，用 [命令] 重新生成 [产物路径]。
- 无法执行生成命令时，报告原因。
## 验证
- 为修改的行为运行 [针对性检查]。
- 报告完成之前，运行 [必需的构建命令]。
- 写出真实结果，以及无法执行的检查。
这是一份建议工作流，没有测量数据证明它一定提高成功率。代价是维护：代码里的路径和命令改变时，指令也要一起更新。
给不同信息选择合适的位置
| 信息 | 建议位置 | 怎样验证 |
|---|---|---|
| 稳定的仓库约定 | 根目录 AGENTS.md | 选择该仓库的代表性任务 |
| 单个服务的规则 | 对应范围的指令文件 | 从服务目录启动，核对适用指令 |
| 仅针对今天的要求 | 本次任务 prompt | 对照该任务的验收条件 |
| 较长的背景材料 | 链接到项目文档 | 按当前改动读取需要的证据 |
第一版保持短小，让你能逐行检查。新增规则时，写清楚它要防止哪个错误；描述的行为已经不存在时，移除过期规则。不要把另一个项目的 package manager 或部署命令直接复制过来。
Codex 似乎忽略了 AGENTS.md，怎样排查
记录启动目录和客户端版本。检查文件名，以及是否存在 override。然后打开会话记录，确认这个文件有没有被注入；10 月 25 日的运行展示了该看哪里。官方指南还说明了指令大小限制和发现设置；适用文件很长时，需要检查这些边界。
随后启动新会话，先发送一个只读请求：
修改之前，列出此处适用的项目指令文件。
找出关于生成文件的规则，注明来源路径。
解释将怎样验证本次任务。暂时不要修改文件。
把回答当作排查线索，并对照你问的是什么来读。在同一天、同一 CLI 版本的一次早期探索运行里，prompt 指向一个任务文件，要求给出标记，以及提供该标记的指令文件路径。agent 用 shell 命令查找后回答 CHILD，引用了 service/ 里的文件和它的上一级文件。它没有列出 checkout 根目录的 AGENTS.md，因为那份文件没有提供标记，所以这个答案符合当时的提问，也看不出自述不完整。想要完整清单，就问“适用的文件”；然后亲自打开引用的文件，再检查实际 diff。正确复述规则，无法证明执行过程遵守了规则。
两次运行没有回答的问题
一次成功可以检查流程，但不足以证明稳定性。在你自己的仓库里，从同一起点重复运行并保留失败结果，用 k/n 计数，每次运行旁边保存会话记录。可复现 benchmark 指南 提供了记录方法。如果规则已被注入、也被理解，任务依旧失败，使用质量检查表 区分上下文缺失、执行故障和输出错误。
下一个检查点
保留能针对已观察问题的最小规则，以及检查它的任务。命令发生变化，或相同错误再次出现时，重新验证。这里仍未测试：同一目录下的 AGENTS.override.md、超过 32 KiB 的文件，以及标记能否在很长的编辑任务中保持。涉及 PR 的具体要求，可以继续阅读代码审查工作流。