AGENTS.md 真的有用吗？

如果agent可以在代码中找到它，就从markdown中删除它。不要给agent一张它已经站在房间里的地图。

今天，我的注意到了一个需要讨论的有趣论点。这篇论文是

"评估AGENTS.md：仓库级上下文文件对编码agent有帮助吗？"

科技界每次推出一个新的"标准"时，都会兴奋不已，这个标准承诺将我们不稳定的LLM实习生转变为高级工程大师。我们都看过LinkedIn上的帖子。我们都读过"上下文工程"宣言。行业对AGENTS.md文件迷恋不已；那个神奇的仓库级"北极星"，据说可以指导你的AI agent通过遗留面条代码的迷宫。

但是等等。

如果我告诉你，你精心制作的ORCHESTRATOR.md实际上是你agent生产力的遗书呢？

来自苏黎世联邦理工学院安全、可靠和智能系统实验室（Kocetkov等人，2026）的一项爆炸性研究刚刚打破了整个"上下文工程"炒作机器。他们查看了数据。他们运行了基准测试。结果坦率地说，是对所有试图通过"提示工程"来摆脱糟糕架构的人的一个讽刺。

事实是：你可能在破坏你的agent。你在支付"有用性税"。而且你是微笑着做的。

1、"冗余循环"的肮脏秘密

让我们现实一点。大多数AGENTS.md文件是由——你猜对了——另一个AI生成的。你运行一个像/init这样的命令，模型扫描你的仓库，并吐出一个漂亮的、500行的markdown文件。它列出了你的技术栈（React、TypeScript、Vite）。它描述了你的文件夹结构（/src用于源代码，/tests用于测试）。它概述了你的命名约定。

这看起来负责任。感觉专业。苏黎世联邦理工学院团队发现，这些自动生成的文件实际上使任务成功率比根本没有上下文文件降低了大约3%。

想一想。你添加了"上下文"来帮助模型，它的表现更差了。

为什么？因为冗余循环。当你告诉模型"这是一个React项目"，但模型已经可以看到一个带有@types/react和十几个.jsx文件的package.json时，你不是在"强化"它的知识。你在稀释它的注意力。

上下文文件中的每个冗余token都与你要agent执行的实际任务竞争。这就像在给某人杂货店方向的同时，读给他们听他们自己汽车的车主手册。他们知道如何开车。就告诉他们该死的牛奶在哪里！

2、"过于顺从"问题：当合规性成为bug时

我们经常抱怨AI幻觉或不合规。但这一次，情况恰恰相反。

苏黎世联邦理工学院的研究强调了一个行为陷阱：AI agent过于顺从。

这不是通常的"模型忽略了我的提示"的抱怨。这是关于锚定效应。当agent读取AGENTS.md文件时，它将这些指令视为高优先级约束。如果你的上下文文件包含"最佳实践"或"架构概述"，而这些内容对于手头的bug修复来说并不严格必要，agent仍然会尝试将其每一步操作与这些规则协调起来。

这使得任务更难。它增加了不必要的推理步骤。这是过度思考的"核选项"。

在该研究使用GPT-4o在SWE-bench Lite上的测试中，"无上下文"基线解决了33.5%的任务。当他们添加开发者编写的上下文文件时？性能下降到29.6%。

我们是认真的吗？我们实际上是在花钱来使我们的工具变得不那么有效。

3、20%的"有用性税"

对于那些负担不起订阅费用——或者与企业级agentic工作流相关的大量API账单——的人来说，这一部分将会很痛苦。

研究表明，使用这些仓库级上下文文件使推理成本增加了20%以上。

• 提示词中有更多token？ 检查。
• "思维链"中有更多token，因为模型试图处理额外的规则？** 检查。
• 成功率更低？ 检查。

它作为一个原型工作；然后一切都崩溃了！你向CTO演示了"上下文感知Agent"，它在"Hello World"仓库上看起来很棒。但在生产环境的日常苦差事中，你只是在烧VC的钱来混淆你的LLM。

坦白说，我们生活在一个荒谬的时间线，我们花更多的时间通过markdown文件"管理"AI的个性，而不是修复首先让AI感到困惑的潜在技术债务。

4、AGENTS.md什么时候真正有效？

但是等等。总有一个但是。苏黎世联邦理工学院团队确实发现了一个上下文文件真正有帮助的场景。他们进行了一个"压力测试"，在该测试中他们剥离了所有其他文档（README、docs文件夹、注释）。

在那种真空中，AGENTS.md文件将性能提高了约2.7%。哦！所以上下文文件只有在你的仓库完全处于信息黑暗时代时才有用？

是的。只有3%的时候。 如果agent可以通过扫描代码库找到信息，上下文文件就是噪音。AGENTS.md中唯一应该包含的是代码结构上无法编码的内容。

• 非显而易见的工具： 如果你使用uv而不是pip，或者使用bun而不是npm，告诉agent。它并不总是能猜到你的环境怪癖。
• 架构意图（"为什么"）： 代码显示了如何做某事。它很少显示为什么你选择了一个特定的、奇怪的模式而不是标准模式。
• "地雷"： "不要使用SerializerV1，它已被弃用但由于遗留原因仍在仓库中。" agent看到两个序列化器可能会掷硬币决定。告诉它哪一个是陷阱。
• 团队决策： "我们决定为这个特定的API使用snake_case，因为客户端很难缠。" agent永远不会从干净的代码库中"推断"出这一点。

5、为什么GPT-5.2不在乎你的markdown

研究的另一个关键点：使用更强的模型（如GPT-5.2或Sonnet-4.5）生成这些上下文文件并没有产生更好的结果。

这是自那以后首次真正突出这一特定上限的研究。更强的模型已经对常见库拥有巨大的"参数知识"。他们知道React如何工作。他们知道FastAPI如何处理依赖关系。

当你在AGENTS.md中提供标准库的详细"概述"时，你不是在帮助一个聪明的模型。你只是在混淆它的上下文窗口。不是大小，而是……嗯，你知道。是相关性。

6、"迷失在中间"的回声

这项研究建立在"迷失在中间"现象（Liu等人，2024）的基础上。我们知道随着上下文的增长，模型在该上下文中心精确定位相关信息的能力会下降。

通过用"仓库概述"和"目录列表"填充AGENTS.md，你实际上是将实际任务指令埋在一堆废话之下。

• 任务成功率： 下降。
• 延迟： 上升。
• 挫折感： 无限。

如果生活这么容易，那么每个人都会在每个提示词上附加一个1MB的文本文件，并称之为"AGI"。但事实并非如此。

7、基准测试与现实世界

苏黎世联邦理工学院的研究人员不仅仅局限于"标准化测试"。他们使用了AGENTBENCH，这是一个包含跨越12个仓库的138个现实世界任务的新数据集。

现在还有人相信模型提供商的那些"90%通过率"基准测试吗？它们是被净化的。它们被泄露到训练数据中。

在现实世界——混乱PR和冲突依赖的日常苦差事中，"无上下文"基线往往是王道。为什么？因为它迫使agent依赖基本事实：代码。

代码不会撒谎。Markdown文件会。Markdown文件会过时。Markdown文件反映的是我们希望代码库的样子，而不是它实际的样子。

8、上下文的"手术式"方法

创新总能以新的方式使事情变得复杂。但如果你正要将一个巨大的CLAUDE.md提交到主分支，停下来。

行业最佳实践的变化——"专家"们还没有告诉你的——正在从"全面文档"转向手术式干预。

而不是一个单一的"北极星"文件，我们应该着眼于"分片上下文"或"即时"上下文注入。但那是另一天的深度探讨。现在，规则很简单：少即是多。

9、裁决：修复代码，而不是提示词

这是我的观点。你应该做你觉得舒服的事情。但如果你想要我对这种数字病理学的看法：

你的AGENTS.md是你架构失败的清单。

每次你必须在上下文文件中写一条规则来阻止agent犯错时，这是你的代码库有"味道"或"摩擦"的信号。

• 如果agent一直把工具放在错误的文件夹中，修复文件夹结构。
• 如果agent一直使用错误的库版本，删除旧版本。
• 如果agent被你的"编排器模式"搞糊涂了，简化模式。

生活确实不公平，但这并不意味着我们需要接受炒作者本周销售的任何"最佳实践"。

领导者，请停止要求你的团队提供包含数千行手动指导的"AI就绪仓库"。你实际上是在花钱让自动化变慢。专注于干净、可发现的架构。 如果人类工程师需要一本50页的手册才能找到API_KEY配置，你的AI也需要。而且它会为你读的每一页收费。

致开发者： 把你的AGENTS.md当作一个无法在linter或tsconfig.json中编码的团队决策"缓存"。如果它在代码中，就从markdown中删除它。

我们生活在一个特殊的时间线，"文档"已成为我们硅基同事的性能退化药物。真正的故事不是你的上下文的大小。而是信噪比。

保持怀疑。保持精益。看在上帝的份上，不要再告诉你的AI/src代表"源代码"。它知道。

最终裁决：

今天删除80%的AGENTS.md。你的成功率和你的CFO都会感谢你。

原文链接: Delete 80% of AGENTS.md. It is making LLM 3% Stupider and 20% Costlier

汇智网翻译整理，转载请标明出处