一份好的 AGENTS.md，就是模型升级
你花钱升级的 Claude，在你写的 AGENTS.md 面前，可能还不如免费的。
最近在折腾 AI 编码助手，Claude Code、Cursor、Codex CLI 都试了一圈。
发现一个反直觉的事：模型之间的差距，远没有 AGENTS.md 之间的差距大。
写得好的 AGENTS.md，效果相当于从 Haiku 升级到 Opus。写得差的，比没有还烂。
这不是瞎说。Augment Code 团队从自家 monorepo 里抽出几十份 AGENTS.md，做了系统性评测。结论是：同一个文件，对一个任务提升 25%，对另一个任务降低 30%。
核心认知：AGENTS.md 不是文档，是 Prompt
这是最关键的一句话。
AGENTS.md 不是写给人看的 README，它是写给 AI 模型看的系统提示词。你不是在写文档，你是在给模型做"上下文工程"。
意味着什么？写得好，模型变聪明。写得差，模型变笨。跟你说什么"模型不行"没关系，是你喂给它的上下文不行。
什么样的 AGENTS.md 有效
总结了 6 种经过验证的模式。
1. 渐进式展开，别堆砌
100-150 行的核心文件 + 几个引用文件 = 最佳组合。
核心文件写概览和关键规则，细节扔进引用文件，让模型按需加载。
超过 150 行之后，效果开始反转。模型会陷入"过度探索"——读了太多上下文，反而被干扰。
说白了，AGENTS.md 不是越全越好。它是"技能树"，不是"百科全书"。
2. 流程化描述，别写散文
把部署、测试、发版这种流程，写成编号步骤。
一个真实案例：六步部署流程，缺配置文件的比例从 40% 降到 10%，正确性提升 25%。
模型需要的是"第一步做什么，第二步做什么"，不是"我们应该怎么做"。
3. 决策表解决歧义
当你的代码库有两种写法时，别让模型猜。直接给决策表。
比如 React Query vs Zustand：
- 只有服务端数据？→ React Query
- 多处修改同一状态？→ Zustand
- 需要乐观更新 + 本地状态混合？→ Zustand
这个模式直接把最佳实践遵循度拉高了 25%。模型不用猜了，按表选就行。
4. 放真实代码片段，别放伪代码
3-10 行的真实生产代码，比任何说明都有用。
比如放一个 Redux Toolkit 的 createSlice 模板、一个 typed useAppSelector hook。模型直接照着写，代码复用率提升 20%。
代码是最好的文档，对人如此，对模型更是如此。
5. 领域规则要具体可执行
"用 Decimal 而不是 float 做财务计算"——这种规则直接有效。
"注意性能"——这种规则等于没说。
规则的颗粒度决定了模型的执行力。
6. 每个"不要"配一个"要"
只说"不要"的 AGENTS.md 是毒药。
试过写 30 条"不要"规则，覆盖数据库迁移、API 版本、部署安全、认证边界。结果模型变得过度保守，什么都怕碰，产出直接腰斩。
正确做法："不要直接实例化 HTTP 客户端"后面紧跟"使用 lib/http 中的共享 apiClient"。
告诉模型该做什么，而不是不该做什么。
最常见的坑：上下文腐烂
这是踩坑最多的地方。
架构描述太多
AGENTS.md 里写了完整的架构全景、消息队列、API 网关路由、共享中间件。任务只是一个两行配置修改。
结果：模型读了 12 个文档，加载了 80K token 的无关上下文，最后改了个半成品。
教训：架构描述要简洁，聚焦边界，写"是什么"而不是"为什么"。
警告太多
30+ 条"不要"规则，覆盖各种边界场景。任务只是一个简单的 CRUD 接口。
结果：模型逐条检查每个警告是否相关，探索了一堆不需要碰的代码。PR 耗时翻倍，完成度降低 20%。
教训：核心警告留在主文件，大部分扔进引用文件。每个"不要"配一个"要"。
旧文档挡新路
AGENTS.md 记录了 REST + 轮询模式。任务是用 WebSocket 做实时协作。模型乖乖跟着文档写了轮询方案——技术上能跑，架构上全错。
教训：引入新模式时，AGENTS.md 要同步更新，否则它会变成路障。
关于文档发现率
还发现一个有意思的数据：
- AGENTS.md → 100% 自动发现
- 引用文件 → 90%+ 按需加载
- 目录级 README → 80%+ 工作在该目录时读取
- 嵌套 README → 只有 40% 被发现
- 孤立文档（_docs/ 文件夹）→ 不到 10%
AGENTS.md 是唯一可靠被发现的文档位置。 重要的内容要么放在这里，要么从这里引用。
一个真实案例：某个服务在 _docs/ 里放了 30K 字的协议设计、限流规则、安全文档。几十个会话下来，模型几乎没打开过。
实操建议
该写什么
- 项目概览：这是什么项目，核心模块有哪些（5 行以内）
- 开发流程：怎么跑测试、怎么发版、怎么部署（编号步骤）
- 决策表：常见歧义场景的选择依据
- 关键规则：可执行的领域约束（不超过 10 条）
- 代码示例：2-3 个真实代码片段
不该写什么
- 完整的架构拓扑图（模型会过度探索）
- 30 条以上的警告（模型会过度保守）
- 与当前代码库无关的通用建议
- 需要追溯原因的"为什么"（模型只需要知道"是什么"）
结构建议
/AGENTS.md ← 根目录：项目概览 + 核心规则（100-150行）
├── /src/AGENTS.md ← 源码模块：开发规范
├── /api/AGENTS.md ← API 模块：接口约定
├── /docs/reference/ ← 引用文件：按需加载
写在最后
AGENTS.md 的本质，是你和 AI 模型之间的一份"合作协议"。
你写得清楚，模型就执行得准确。你写得模糊，模型就开始猜。你写得太多，模型就被淹没。
一份好的 AGENTS.md，不需要你升级模型，就已经是模型升级了。
相关话题： #AI编程 #ClaudeCode #Cursor #AGENTS.md #提示词工程
