Codex AGENTS.md 指南：写出可以验证的项目指令

AGENTS.md 和 AGENTS.override.md 会影响 Codex 收到的项目指令。继续追加规则之前，先确认实际生效的文件。本文由 Codex Pulse 独立编写，官方文档核对日期为 2026 年 9 月 20 日。

先检查指令来源

官方 AGENTS.md 指南 描述了全局指令，以及从项目根目录到启动工作目录的项目指令。在同一目录中，AGENTS.override.md 优先于 AGENTS.md。修改指令后，启动新会话再检查。指令文件表达工作要求，无法授予文件系统或网络权限。

从一个反复出现的问题开始

假设 agent 总是直接修改生成文件。先保存一个具体案例：任务、被修改的路径、正确的生成命令。然后写清楚应该改哪个源文件，以及怎样检查生成结果是否一致。“提高代码质量”没有提供可比较的验收结果。

下面是可放入仓库 AGENTS.md 的编辑模板。使用前，把方括号里的占位内容替换成真实路径和命令：

# 项目工作约定

## 修改之前

- 阅读 [项目说明路径]，检查当前 diff。
- 保留开始任务前已经存在的改动。

## 生成文件

- 修改 [源文件路径]，用 [命令] 重新生成 [产物路径]。
- 无法执行生成命令时，报告原因。

## 验证

- 为修改的行为运行 [针对性检查]。
- 报告完成之前，运行 [必需的构建命令]。
- 写出真实结果，以及无法执行的检查。

这是一份建议工作流，没有测量数据证明它一定提高成功率。代价是维护：代码里的路径和命令改变时，指令也要一起更新。

给不同信息选择合适的位置

第一版保持短小，让你能逐行检查。新增规则时，写清楚它要防止哪个错误；描述的行为已经不存在时，移除过期规则。不要把另一个项目的 package manager 或部署命令直接复制过来。

Codex 似乎忽略了 AGENTS.md，怎样排查

记录启动目录和客户端版本。检查文件名，以及是否存在 override。官方指南还说明了指令大小限制和发现设置；适用文件很长时，需要检查这些边界。

随后启动新会话，先发送一个只读请求：

修改之前，列出此处适用的项目指令文件。
找出关于生成文件的规则，注明来源路径。
解释将怎样验证本次任务。暂时不要修改文件。

把回答当作排查线索。亲自打开引用的文件，然后检查实际 diff。正确复述规则，无法证明执行过程遵守了规则。

用一个小任务检查规则效果

保存初始 commit，在没有无关改动的隔离副本中准备任务。指令修改前后使用相同的任务边界，记录三项结果：是否直接修改了生成文件、是否执行了生成命令、最终 diff 是否正确。

一次成功可以检查流程，但不足以证明稳定性。从同一起点重复任务，并保留失败结果。可复现 benchmark 指南 提供了记录方法。如果规则已被理解，任务依旧失败，使用质量检查表 区分上下文缺失、执行故障和输出错误。

下一个检查点

保留能针对已观察问题的最小规则，以及检查它的任务。命令发生变化，或相同错误再次出现时，重新验证。涉及 PR 的具体要求，可以继续阅读代码审查工作流。