04 · 为什么 AGENTS.md 能改变 Codex 行为
面向新手解释 AGENTS.md 为什么能让 Codex 更稳定：它是项目和 Agent 的协作接口，不是普通 README。
AGENTS.md 能改变 Codex 行为，不是因为它有什么神秘格式，而是因为它把“每次都要重复交代的话”变成了项目启动时就会进入上下文的规则。
同一个任务，没有项目规则时，Codex 只能猜包管理器、目录职责、测试命令和禁止事项。有了 AGENTS.md，它能先知道项目真实约定，再开始做事。
先理解：AGENTS.md 是接口
写代码的人都知道接口的价值：它定义两边怎么协作。
AGENTS.md 也是接口，只是连接的是项目和 AI Agent。项目一侧有源码、配置、测试、目录边界；Agent 一侧有读文件、改文件、跑命令、调用工具的能力。AGENTS.md 把两边对齐。
README 主要解释项目给人看。AGENTS.md 主要约束 Agent 怎么干活。两者互补，不互相替代。
怎么判断一条规则该不该写进去
最实用的判断是：下个月还有效的，写进 AGENTS.md；只对这次任务有效的，写进 prompt。
适合写进去的内容包括项目用途、技术栈、包管理器、目录职责、启动命令、测试命令、禁止事项、验收要求。
不适合写进去的内容包括本次任务细节、临时想法、长篇背景、密钥、账号、还没有稳定下来的偏好。
如果你第二次对 Codex 纠正同一个问题，这就是写进规则的信号。
一份合格 AGENTS.md 的三层
第一层是事实。项目用什么技术栈、哪个包管理器、哪些目录做什么、哪些命令能验证。
第二层是约束。哪些文件不要碰，哪些操作不能默认做，哪些高风险逻辑必须先确认。
第三层是验收。改完要跑什么检查，无法验证时要怎么说明，最终交付应该包含哪些证据。
只有事实，没有约束，就是说明书。只有约束，没有事实，就是口号。没有验收，就无法判断完成。
新手第一次怎么写
不要追求完整。先写六块就够。
项目概况：一句话说明这个项目做什么。
目录职责：列关键目录，不要逐文件注释。
开发命令：只列启动、测试、构建、lint 等常用命令。
编码规则：写具体可执行的约定，例如复用现有组件、不要新增库、错误处理格式。
禁止事项：写不能碰的路径、不能做的命令、不能新增的依赖。
验收要求：写改 UI、改逻辑、改类型、改文档分别要怎么检查。
写法要具体
“代码要优雅”没有用，因为 Codex 无法验证。
“修改 API handler 后运行某个测试命令”有用，因为它能执行。
“默认不要安装新依赖”有用，因为它能遵守。
“改 UI 后检查 375px 和 1440px”有用，因为它给出了验收面。
规则越具体，越容易执行；规则越抽象，越容易变成装饰。
怎么维护它
AGENTS.md 不是一次写完的文档。它应该随着项目和团队实践迭代。
每次 Codex 犯错后，先判断是任务没写清，还是项目规则缺失。只有会反复出现的问题，才沉淀到 AGENTS.md。
团队项目里，AGENTS.md 应该像代码一样走 review。它改变的是所有 Agent 进入项目后的行为，不能随手改。
如果文件越来越长，先删除低价值说明，再把局部规则拆到更靠近对应目录的位置。
新手常见坑
- 把 README 复制进去：人类介绍太长，Agent 规则不够清楚。
- 写一堆抽象要求：无法验证，无法稳定执行。
- 把任务模板塞进去：每次任务不同，应该写 prompt。
- 把密钥、账号、私有 URL 写进去。
- 规则互相冲突：根目录说用 pnpm，子目录又让用 npm。
- 没有验收要求：Codex 只会说“完成了”。
怎么验收
让 Codex 只读总结当前加载到的规则。它应该能复述项目用途、命令、禁止事项和验收要求。
给一个小任务，看它是否先读相关文件、是否只改允许范围、是否按规则跑验证。
检查最终回复是否包含改动文件、验证结果、未验证项和剩余风险。
如果这些没有发生，优先改 AGENTS.md 的具体性，而不是继续骂模型不听话。