当AGENTS.md成为负担：这项大规模研究戳破了AI编程助手的最大幻觉

老实说，我见过太多团队在项目根目录塞一个 AGENTS.md，然后理所当然地觉得 AI 编程助手就能“更懂”这个仓库。这种做法在过去两年几乎成了某种行业共识——新建仓库，先写 AGENTS.md，仿佛一份上下文文档就是 AI 理解代码的灵丹妙药。但最近一项大规模实证研究告诉我，这个直觉可能是错的，而且错得相当彻底。

这项研究来自 AI 编程领域近期最受关注的一篇论文，它对 AGENTS.md 这类仓库级上下文文件进行了系统性的效果检验。研究团队在 SWE-bench Lite（300 个真实 GitHub Issue 任务）和全新构建的 AGENTBENCH（138 个任务）两个基准上，测试了 Claude Code、Codex、Qwen Code 等主流编码 Agent 的组合表现，覆盖了 8 组不同的实验设置。结果相当颠覆：由 LLM 自动生成的 context file 在 8 组设置中有 5 组导致了成功率下降，平均降幅分别为 SWE-bench Lite 上 -0.5%、AGENTBENCH 上 -2%。与此同时，成本还上涨了超过 20%。

一份文档，两种命运：自动生成 vs 开发者手写

研究中最有意思的对比出现在两组实验之间。第一组是让 LLM 自动扫描整个代码库并生成 AGENTS.md，第二组是请实际开发者亲手编写同样的文档。结果显示，开发者手写的 context file 平均带来了 +4% 的成功率提升，而 LLM 自动生成的呢？不仅没有提升，反而拖了后腿。

这个差距让我重新思考了一个问题：AGENTS.md 本身可能不是坏东西，坏的是生成它的方式。LLM 在自动生成文档时，往往倾向于“多多益善”——把大量它认为相关的信息都塞进去，代码结构、调用关系、依赖版本、团队约定，一股脑堆在文件里。问题在于，编码 Agent 在接收这些信息时，冗余的上下文反而构成了噪音，干扰了它对真正关键信息的判断。简单说，就是信息越多，Agent 越容易迷失。

冗余假说：一个被实验验证的关键发现

研究团队进一步提出了一个“冗余假说”来做验证：他们把自动生成的 AGENTS.md 放到一个“干净”的环境中——即移除仓库中其他已有的文档（README、贡献指南等），只保留这个自动生成的 context file。结果呢？成功率反而上升了 +2.7%。

这个发现几乎完美地解释了前面的问题。自动生成的 AGENTS.md 本身并不是罪魁祸首，真正的罪魁祸首是它与其他文档之间的内容重复和冲突。当 Agent 同时看到 README、CONTRIBUTING.md、又有 AGENTS.md，三份文档讲的都是“项目结构”和“如何运行测试”，Agent 不知道该信哪一份，于是陷入了决策瘫痪。

我个人的判断是，这揭示了当前 AI 编程助手在长上下文理解上一个非常真实的瓶颈：它们并没有我们想象中那样善于从大量信息中提取精华。相反，越多的重复信息，越容易让模型在多个相似但不统一的描述之间产生混淆，最终输出的代码质量反而下降。

成本账：你的 Token 消耗可能在悄悄翻倍

研究还有一个非常实际的经济维度——成本。在测试中，接入 AGENTS.md 后，Agent 的 Token 消耗平均增加了 20% 以上，但任务完成率却没有提升甚至下降。这意味着团队不仅没有获得效率提升，反而在花更多的钱。

这个数据对那些在企业内部大规模部署 AI 编程助手的团队尤其值得关注。当前很多公司都在用 Claude Code、Codex 这类工具来做代码审查、自动化测试甚至功能开发，每增加一份 context file，背后的 API 费用就在累积。如果这份文档不能带来实质性的产出提升，那它就是在纯粹地增加成本。

研究团队还给出了一个非常务实的建议方向：与其花时间让 AI 生成通用性的 context file，不如把精力放在写入仓库专用的工具配置和领域知识上。也就是说，告诉 Agent“这个项目用的是什么构建工具链”“我们内部的 API 调用规范是什么”，这类高度定制化的、Agent 在公开文档里找不到的信息，才是真正值得注入上下文的。优先级应该是：专用工具配置 > 代码规范 > 项目概览。

我们应该怎么做

读到这儿，我想你应该和我一样，对 AGENTS.md 这件事有了新的认知。我的建议是，不要急着删除或新建 AGENTS.md，而是先审视一下你现在的文档体系是否足够精简。

首先，如果你的仓库已经有 README、贡献指南这类文档，不要期望 AGENTS.md 能带来额外的魔法效果——实验数据已经表明，在有其他文档的情况下，AGENTS.md 带来的更多是冗余而非价值。其次，如果你决定使用 AGENTS.md，尽量由了解项目的开发者手写，保持简洁，只记录 AI 在公开信息中找不到的内容，不要让它成为一份重复的“代码黄页”。

对于 AI 编程工具的开发者而言，这项研究的启示同样清晰：如何在上下文膨胀和任务质量之间找到平衡点，将成为下一阶段竞争的关键战场。那些懂得克制信息量、帮助用户做减法的产品，大概率会比堆砌功能的对手走得更远。

说到底，AI 编程助手不是读的书越多就越聪明的学生。它更像一个需要精准指令的执行者——给对指令，事半功倍；给错指令，不仅徒劳，还可能帮倒忙。