AGENTS.md 可能在伤害你的编码 Agent：一项实证研究给出的反直觉结论

很多团队已经把 AGENTS.md 当成 AI 协作的标准配置：跑一次 /init，提交到仓库，默认质量就会更好。

这篇文章真正有价值的地方，在于它没有停留在经验判断，而是把问题变成了可以实测的假设：给 Agent 一个 context file，到底会让它更正确，还是只会让它更忙？

结论并不讨喜。在不少场景里，AGENTS.md 可能让结果更差、成本更高。

文章引用的核心工作来自 ETH Zurich（2026 年 2 月）。研究团队构建了 AGENTBENCH，并结合 SWE-bench Lite 做对照。

实验条件很清楚：

1. 无 context file。
2. LLM 自动生成 context file。
3. 人类编写 context file。

覆盖的代理包括 Claude Code、Codex、Qwen Code。核心评价问题不是“跑得快不快”，而是“任务是否做对”。

这个评价口径非常关键，因为它和很多工程团队的真实目标一致：先追求正确，再谈速度。

文中给出的结论可以浓缩成三点：

1. 自动生成 context file 在 8 组设置里有 5 组让表现变差，AGENTBENCH 平均下降约 2%。
2. 推理成本上升明显，整体增加约 20% 到 23%。
3. 人工编写版本平均提升约 4%，但稳定性不够，跨模型与基准并不一致。

还有两个很容易被忽略的观察：

1. 加不加 context file，对“定位目标文件的速度”帮助很有限。
2. 给了 context file 后，模型往往消耗更多 reasoning tokens，说明它在为额外上下文付出注意力成本。

这意味着很多团队直觉中的“上下文越全越好”，在当前代理工作流里未必成立。

文章还对比了另一项结论相反的研究（Lulla et al.）：其数据显示 AGENTS.md 能减少运行时与输出 token。

表面看像冲突，实则是评价维度不同：

1. 一类研究测效率：导航更快、token 更省。
2. 另一类研究测正确性：任务是否真正解决。

因此更准确的表述是：

• Context file 可能让 Agent 更快走到一个答案。
• 但它不保证这个答案更正确。

对工程团队来说，这个区别决定了优化优先级。如果你在做高风险改动，正确率应该压过“看起来很快”。

原文把原因拆得比较清楚，工程上也很有解释力。

自动生成文件常常复述仓库里本来就能发现的信息（目录、技术栈、常规命令）。

这类内容不是“增量知识”，只是“重复输入”，会占用上下文预算。

长文档会稀释重点。模型注意力不是线性的，越长越容易把关键约束埋掉。

你最想让它遵守的那条规则，可能刚好在最不容易被稳定关注的位置。

只要文档里提到某个工具或流程，Agent 往往会过度依赖它。文档一旦过期，错误会被稳定放大。

这类问题在“旧规范仍在仓库里，但现实已变化”的团队里尤其常见。

文章引用 Addy Osmani 的一条过滤规则，我建议直接当团队评审标准：

如果 Agent 能通过读代码自行发现，就不要写进 AGENTS.md。

换句话说，文档应优先保留“代码里看不出来，但踩了会爆炸”的信息：

1. 必须使用的非默认命令（例如特定参数）。
2. 不能改动的高风险模块。
3. 已知历史坑与临时约束。
4. 迁移中的目录或兼容性边界。

这类内容短，但价值密度高。

文中还提到两个方向：

1. 任务级动态上下文生成（按任务装载，不做仓库级静态大文件）。
2. 评测驱动的指令优化闭环（跑任务、评估、反馈、迭代）。

这背后的共识是：

1. 给人看的“项目说明”不等于给模型看的“执行上下文”。
2. 上下文应该跟着任务变，而不是一次提交后长期冻结。

如果你正在维护 AGENTS.md，可以先做一个低成本改造：

1. 把文档压缩到一页以内，只保留不可自发现的信息。
2. 每条规则都要能回答“它避免了什么具体错误”。
3. 规则失效后及时删除，避免历史包袱继续锚定模型。
4. 在 CI 或周度回顾里把它当“活文档”维护，而不是初始化产物。

这篇文章最值得带走的一句话是：

AGENTS.md 应该更像故障清单，而不是仓库百科。

当它从“全面介绍”转向“高风险约束”，你通常会得到两个结果：

1. 更低的上下文噪声。
2. 更稳定的实际产出质量。