11 · AGENTS.md 完整指南：给 Codex 写项目规则

AGENTS.md 的发现范围、层级覆盖、推荐内容、反模式和维护方法，让 Codex 每次任务前读懂项目规范。

AGENTS.md 是你可以写给 Codex 的「项目说明书」。它会在每次任务开始前被读进来，告诉 Codex：这个项目有什么规矩、哪些是雷区、你希望它怎么干活。

「发现范围」指的是这个文件放哪里才有效。通常放在项目根目录，它就能被自动发现；有时也支持放在其它约定位置。放对位置，规则才生效。

「层级覆盖」是说规则可以分几层。比如根目录一个总规则，子目录再放一个局部规则，越贴近具体目录的规则优先级越高。这样大项目里就能「总原则 + 分模块细则」配合使用。

flowchart TB
  A[Codex 接到任务] --> B[查找 AGENTS.md]
  B --> C{有几个层？}
  C -->|根目录| D[全局规则]
  C -->|子目录| E[局部规则]
  D --> F[按优先级合成]
  E --> F
  F --> G[作为初始上下文传给 Codex]
  G --> H[Codex 接手任务]
  style A fill:#5eead4,color:#050a0f
  style H fill:#5eead4,color:#050a0f
  style B fill:#0f1a24,color:#e6f1f5
  style D fill:#0f1a24,color:#e6f1f5
  style E fill:#0f1a24,color:#e6f1f5
  style F fill:#a78bfa,color:#050a0f
  style G fill:#0f1a24,color:#e6f1f5

「推荐内容」是这篇的重点。一个好的 AGENTS.md，通常包含这几类信息：项目的技术栈和整体结构、构建和测试怎么跑、代码风格约定、哪些目录或文件不要乱动、以及一些常见任务的推荐做法。核心是「让 Codex 少踩坑」。

「反模式」是很多人会犯的错。最常见的是把 AGENTS.md 写成一篇又臭又长的流水账，或者写了却从不更新，结果里面是过时的信息，反而误导它。规则要精、要准、要活着。

「维护」提醒我们，这不是一次性写完了事。项目在变，规则就得跟着变。把它当成项目的一部分，随代码一起演进。

AGENTS.md 的价值，在于把「每次都要口述一遍的规矩」沉淀成「自动生效的默认值」。等你写了几个项目之后会发现，一个好的 AGENTS.md，能显著减少它返工和闯祸的次数。

这一篇建议你重点学。因为无论你后面用哪个入口、做多复杂的任务，一个清晰的 AGENTS.md 都是稳定交付的地基。

一个自查清单：当你读完这一篇时，可以问自己三个问题——它解决的是什么具体问题？我当前的工作/学习里有没有这个场景？下一步我该学哪一篇？把这三个问题答清楚，你就知道自己有没有真正吃透。

五分钟练习：① 找一个一分钟能完成的代码任务 ② 用这一篇的方法描述给 Codex ③ 看它执行时有没有触发你刚学的那个机制 ④ 验证结果是否符合预期。这一轮做下来，你对这一篇的理解会深 3 倍。

与其他篇的关系：这一篇是本组的基础。如果你跳过了前面几篇，建议先回去看，否则这里有些概念可能看着突兀。如果都看过了，那你可以直接进入更后面的实战环节，把这里学到的东西用上。

复盘清单：每做完一个任务，可以花一分钟复盘——目标说清楚了吗？范围限定了吗？结果验证了吗？审查过 diff 了吗？下次哪里能更好？这 5 步能让你的 Codex 使用从「能用」进化到「好用」。