04 · 为什么 AGENTS.md 能改变 Codex 行为

AGENTS.md 能改变 Codex 行为，是因为它把“每次都要重复交代的话”变成了任务开始前就会进入上下文的项目规则。

它本质上是接口

flowchart LR
    Repo["项目事实"] --> Agents["AGENTS.md"]
    Team["团队约束"] --> Agents
    Agents --> Codex["Codex 行为"]
    Codex --> Work["读文件 / 改代码 / 跑验证"]

README 主要解释项目给人看。AGENTS.md 主要约束 Agent 怎么干活。两者互补，不互相替代。

没有项目规则时，Codex 只能猜包管理器、目录职责、测试命令和禁止事项。有了 AGENTS.md，它能先知道项目真实约定，再开始做事。

发现顺序

Codex 启动时会构建 instruction chain。官方规则可以理解成三层：

1. Global scope：Codex home 下的 AGENTS.override.md 或 AGENTS.md。
2. Project scope：从项目根一路到当前目录，逐层读取 AGENTS.override.md、AGENTS.md 或配置里的 fallback 文件名。
3. Merge order：越靠近当前工作目录的规则越晚进入上下文，因此更能覆盖上层规则。

这意味着：

• 全局文件适合个人稳定习惯。
• 根目录文件适合全仓共同规则。
• 子目录文件适合模块规则。
• override 文件适合临时强覆盖，但不能滥用。

什么该写进去

适合写：

• 项目用途。
• 技术栈。
• 包管理器。
• 目录职责。
• 启动、测试、构建、lint 命令。
• 禁止事项。
• 受保护路径。
• 验收要求。

不适合写：

• 本次任务细节。
• 临时想法。
• 长篇背景。
• 密钥、账号、私有 token。
• 没稳定下来的个人偏好。
• 与现有规则冲突的模板。

如果你第二次对 Codex 纠正同一个问题，这就是写进规则的信号。

三层内容

第一层是事实：项目用什么技术栈、哪个包管理器、哪些目录做什么、哪些命令能验证。

第二层是约束：哪些文件不要碰，哪些操作不能默认做，哪些高风险逻辑必须先确认。

第三层是验收：改完要跑什么检查，无法验证时要怎么说明，最终交付应该包含哪些证据。

只有事实，没有约束，就是说明书。只有约束，没有事实，就是口号。没有验收，就无法判断完成。

新手第一次怎么写

不要追求完整。先写六块：

• 项目概况：一句话说明项目做什么。
• 目录职责：列关键目录，不要逐文件注释。
• 开发命令：只列启动、测试、构建、lint。
• 编码规则：写具体可执行的约定。
• 禁止事项：写不能碰的路径、命令和依赖。
• 验收要求：写不同改动类型怎么检查。

写法要具体。“代码要优雅”没有用，因为 Codex 无法验证。“修改 API handler 后运行某个测试命令”有用，因为它能执行。

怎么维护

AGENTS.md 不是一次写完的文档。它应该随着项目和团队实践迭代。

每次 Codex 犯错后，先判断是任务没写清，还是项目规则缺失。只有会反复出现的问题，才沉淀到 AGENTS.md。

团队项目里，AGENTS.md 应该像代码一样走 review。它改变的是所有 Agent 进入项目后的行为，不能随手改。

如果文件越来越长，先删除低价值说明，再把局部规则拆到更靠近对应目录的位置。

新手常见坑

• 把 README 复制进去：人类介绍太长，Agent 规则不够清楚。
• 写一堆抽象要求：无法验证，无法稳定执行。
• 把任务模板塞进去：每次任务不同，应该写 prompt。
• 把密钥、账号、私有 URL 写进去。
• 规则互相冲突：根目录说用 pnpm，子目录又让用 npm。
• 没有验收要求：Codex 只会说“完成了”。

怎么验收

让 Codex 只读总结当前加载到的规则。它应该能复述项目用途、命令、禁止事项和验收要求。

给一个小任务，看它是否先读相关文件、是否只改允许范围、是否按规则跑验证。

检查最终回复是否包含改动文件、验证结果、未验证项和剩余风险。

如果这些没有发生，优先改 AGENTS.md 的具体性，而不是继续堆更多提示词。

官方资料

• AGENTS.md
• Rules
• Project instructions discovery