很多初学者会把 AGENTS.md 当成“写给 AI 的说明书”,写完却不知道它是否生效。本练习只解决一个具体问题:让 Codex 在不同目录中识别不同的测试命令,并用一个可观察的任务核对加载结果。下面使用虚构项目,不涉及真实代码、账号或付费设置。重点不是堆规则,而是确认规则的来源、优先级和实际影响。

一、先准备一个最小练习项目

准备条件很简单:一台能运行终端的电脑、已安装并能启动的 Codex,以及一个可写入的空目录。示例项目名为 `paper-lantern`,目录中暂时只有 `AGENTS.md` 和 `services/payments/`。项目里的命令都是虚构约定,不要把它们当成真实项目可执行命令。

在项目根目录创建 `AGENTS.md`,写入两条规则:项目级检查使用 `npm run lint`;修改 JavaScript 后运行 `npm test`。然后在 `services/payments/` 创建 `AGENTS.override.md`,写入一条更具体的规则:支付服务使用 `make test-payments`,不使用根目录的通用测试命令。这样就有了“根目录规则”和“子目录覆盖规则”两个可观察对象。

二、理解 Codex 怎样找文件

Codex 会先读取全局范围的指导文件,再从项目根目录逐层走到当前工作目录。每一层优先检查 `AGENTS.override.md`,然后检查 `AGENTS.md`;同一目录最多采用其中一个非空文件。多个目录的内容会按从外到内的顺序合并,离当前目录更近的规则出现在后面,因此更具体的指导可以覆盖较早的指导。

练习中,如果从项目根目录启动,Codex应看到项目根的 `AGENTS.md`。如果从 `services/payments/` 启动,它还应看到该目录的 `AGENTS.override.md`。根目录的规则不会自动消失,但支付目录的专用测试命令应成为当前任务的优先依据。空文件会被跳过,过长的合并内容还可能受到 `project_doc_max_bytes` 限制;初学时保持文件短小更容易排查。

三、用任务验证,而不是只问“看到了吗”

先在项目根目录启动 Codex,提交一个只读任务:“列出当前加载的指导来源,并说明如果修改 JavaScript,先后应做哪些检查。”预期结果是:它提到根目录的 `AGENTS.md`,并能复述 `npm test` 与 `npm run lint`。这里验证的是根目录规则是否进入当前任务上下文。

接着从 `services/payments/` 启动,或者使用等价的切换工作目录方式,再提交:“假设我要修改支付服务中的一个 JavaScript 文件,请给出测试命令,并说明它来自哪一层指导文件。”预期结果应包含 `make test-payments`,同时指出它来自支付目录的覆盖文件;若仍只回答 `npm test`,就说明当前目录、文件名或启动方式需要检查。

为了验证规则确实影响行为,可以再提交一个虚构任务:“只规划步骤,不改文件:修改支付服务中的 `fee.js` 后如何验证?”理想回答应把支付服务测试作为核心检查,并保留根目录 lint 规则,除非你的文件明确要求覆盖它。这个结果比单纯让 Codex复述文件内容更有价值,因为它检查了规则是否被应用到具体工作流。

四、至少做一次原文复核

不要只相信 Codex 的总结。打开项目中的 `AGENTS.md` 和 `services/payments/AGENTS.override.md`,逐条对照它的回答:第一,文件名和路径是否准确;第二,通用测试命令是否被支付目录规则替换;第三,是否把不存在的命令、目录或额外政策说成了项目规定。

还要复核一个容易忽略的边界:指导文件通常在 Codex 启动任务或会话时建立上下文。你修改文件后,重新启动一次命令或新会话,再重复验证。若回答仍然像旧内容,先检查是否启动在正确目录,以及 `CODEX_HOME` 是否指向了另一个 Codex 配置目录。不要用“它说已加载”代替文件原文核对。

五、故障排查与扩展写法

如果什么规则都没有出现,先确认文件非空、当前目录确实位于目标项目内,并检查项目根目录是否被正确识别。如果专用规则没有生效,检查 `AGENTS.override.md` 是否拼写正确,或者上层是否存在会影响判断的覆盖文件。

如果团队已有其他文件名,例如虚构的 `TEAM_GUIDE.md`,不能仅靠改名期待 Codex自动识别。只有在配置的 `project_doc_fallback_filenames` 中加入该名称后,它才会作为候选指导文件;配置变更后要重新启动。文件内容建议写可执行约定:适用范围、命令、例外和验证方式。格式偏好、过细的背景介绍和互相矛盾的规则会增加判断成本。

完成练习后,最终验收标准只有三项:根目录任务能识别通用规则;支付目录任务能识别更近的覆盖规则;你能从原文件逐条找到回答依据。达到这三项,才说明 AGENTS.md 不只是“写了”,而是进入了实际工作流程。

可复制的练习提示词

你正在检查一个完全虚构的项目 `paper-lantern`。请先列出你当前加载的指导文件,按从全局到当前目录的顺序说明来源。然后回答:如果要修改 `services/payments/fee.js`,应使用什么测试命令?该命令来自哪一层文件?不要假设不存在的文件、命令或政策。最后给出一个只读验证计划,不要修改任何文件。虚构文件内容如下:

项目根目录 `AGENTS.md`:
# Repository expectations
- 修改 JavaScript 后运行 `npm test`。
- 提交前运行 `npm run lint`。

`services/payments/AGENTS.override.md`:
# Payments service rules
- 支付服务使用 `make test-payments`,替代通用测试命令。
- 只规划步骤时,不要修改文件。

官方参考

核对日期 2026-11-14