Codex AGENTS.md 实战：写项目指令并验证是否生效

文章用一个小实验讲清 Codex 的 AGENTS.md 指令文件怎么放、怎么分层、怎么验证是否被加载。作者在 macOS 上用 Codex CLI 0.146.0 建了一个临时 Git 项目，用「项目标记 + 交付日」这种可核对的事实，测试根目录与嵌套目录的指令覆盖关系。

先写项目真正需要的规则

• AGENTS.md 放在能标识项目身份的文件旁边，比如 README.md 或 package.json；不确定根目录时用 git rev-parse --show-toplevel 确认。
• 指令要写在本项目里能跑通的命令，别把 JavaScript 的测试规则照搬到 Python 项目。
• 作者用的练习文件包含四条：项目标记 CEDAR_ROOT、默认交付日周五、改完 shipping.py 后跑 python3 -m unittest -v、除非业务规则变化否则不改测试。
• 好指令回答具体问题：代码在哪、怎么验证改动、什么必须保持兼容、什么时候该问项目负责人；「写出优秀代码」这类话没有信息量。

指令按层级放置

• 从全局偏好、仓库根目录到当前目录形成一条指令链；同一目录下 AGENTS.override.md 优先于 AGENTS.md，每一层只选中一个文件。
• 这解释了两个常见困惑：旁边的 override 会让对 AGENTS.md 的修改看起来无效；兄弟目录里的文件不会自动进入根到当前目录的指令链。
• 这些文件是交给 agent 的指令，仓库还可能共享给协作者，所以不要写密钥。

用可核对的事实验证根目录

• 在项目根目录开一次全新运行，问一个答案只能来自指令文件的问题，而不是把答案写进提问里。
• 作者的提问是让 agent 只依据已提供的项目指令报告项目标记、团队标记和交付日，回答为 CEDAR_ROOT、None supplied、Friday。
• 这比问「你读了吗」再接受一个「是」更可靠，但仍不能证明 agent 每个任务都会遵守；真实改动后要看 diff 和测试结果，口头说会跑测试不等于测试通过。

嵌套规则只在确有差异时添加

• 练习项目结构为 cedar/ 下放 AGENTS.md，support/ 下同时有 AGENTS.md 和 AGENTS.override.md，other/ 下另有 AGENTS.md。
• support 的基础文件写周二，override 写周一并使用标记 SUPPORT_OVERRIDE，兄弟目录 other 写周四。
• 在 support 目录新开一次运行问同样的问题，结果包含 CEDAR_ROOT、SUPPORT_OVERRIDE 和 Monday，不含 support 基础文件的标记，也不含兄弟目录的标记。
• 这说明根目录规则会继承下来，本地文件只补充更窄的规则，不必在子目录重复所有根规则；交互复现时先退出旧会话，再 cd support 后启动 codex，因为指令链在运行开始时组装。

保持文件可维护，排查失效原因

• 测试命令、目录结构或发布要求变化时复查文件，删掉不再描述项目的规则；判断标准是队友能否看出这条指令有没有被遵守。
• 不要在多个嵌套文件里重复同一条规则，副本会漂移；共享约定放根文件，本地文件只写例外。
• 指令文件不等于操作系统权限，「不要编辑此文件夹之外」只是建议，真正的写入边界要靠权限配置。
• 排查顺序：用 pwd 确认起始目录、确认文件名是 AGENTS.md、检查同层是否有 override、用独特标记新开运行验证、检查全局或父级指令是否冲突、缩短过长的指令链（合并大小受 project_doc_max_bytes 限制）。
• 换用其他文件名时要配置并验证 fallback；一次性任务说明用聊天消息，可复用的命名流程做成 skill，需要外部工具时用 MCP 连接。

今天就能做

• 在项目根目录建一个只含 3 到 5 条可核对规则的 AGENTS.md，用独特标记做一次新会话验证。
• 把「改完某文件跑哪条测试命令」写进根文件，并在真实改动后亲自看 diff 和测试输出。
• 清理嵌套文件里与根文件重复的规则，只保留真正的例外。