AGENTS.md 真的有用吗？ETH Zurich 研究揭示 Context Engineering 的反直觉真相

论文：Are Repository-Level Context Files Helpful for Coding Agents?

来源：arXiv:2602.11988 | ETH Zurich & LogicStar.ai | 原文链接

发布日期：2026-02-12 | 更新日期：2026-06-23

📌 核心问题：Context Engineering 的「最佳实践」可能适得其反

在 AI Coding Agent 生态中，AGENTS.md（及其变体 CLAUDE.md、copilot-instructions.md 等）已经成为事实上的「标准配置」。几乎所有 Agent 框架都推荐开发者创建这类仓库级上下文文件，将项目架构、编码规范、工具链信息注入到每次 Agent 会话中。这被视为 Context Engineering 的基础实践。

但 ETH Zurich 的研究团队提出了一个尖锐的问题：这些被广泛推崇的 context files，真的能帮助 AI Coding Agent 更好地完成任务吗？还是说，它们只是在增加推理成本的同时，给 Agent 制造了不必要的噪音？

这个问题之所以重要，是因为它直接挑战了当前 AI Coding 领域的一个核心假设——「更多上下文 = 更好的表现」。如果这个假设不成立，那么整个 Context Engineering 的方向都需要重新审视。

🔬 关键数据：更少的上下文，更好的结果

研究团队在 SWE-bench 和一个名为 AGENTBENCH 的新数据集上，用 Sonnet-4.5、GPT-5.2、Qwen3-30B 等模型进行了大规模实验。结果令人震惊：

自动生成的 context files 平均降低任务成功率约 3%，同时推理成本增加超过 20%
  • 自动上下文税（Auto-Generated Tax）：LLM 自动生成的 context files 使成功率下降约 3%
  • 成本代价：推理成本增加 20%+，完成相同任务需要更多推理步骤
  • 人工撰写的优势有限：人工编写的 context files 仅带来约 4% 的边际提升
  • 更强的模型 ≠ 更好的上下文：使用 GPT-5.2 等更强模型生成的 context files 并没有产生更好的结果
更强的模型拥有足够的「参数化知识」来理解常见库和框架，额外的上下文反而变成了冗余噪音

🏗️ 技术架构与设计

  • 实验设计：双轨评估——SWE-bench（LLM 生成 context）+ AGENTBENCH（开发者手写 context），覆盖两种真实场景
  • 模型覆盖：Sonnet-4.5、GPT-5.2、Qwen3-30B 等主流 Coding Agent，确保结论的普适性
  • 评估维度：任务成功率、推理成本（token 消耗）、推理步骤数、工具使用频率
  • 发现机制：Agent 对 context files 中的指令有很强的遵从性——提到的工具使用频率提升 160 倍
  • 核心洞察：问题不在于 Agent 不读 context files，而在于它们「太听话」——不必要的指令反而成为负担

🔑 关键洞察

洞察一：Agent 自主发现能力被严重低估 研究发现，代码库概览和目录树——大多数 AGENTS.md 文件的核心内容——对 Agent 导航毫无帮助。Agent 本身就擅长自主发现文件结构，手动列出目录树只是在消耗推理 tokens，增加「认知负担」。

这直接颠覆了「给 Agent 一张地图它就能更快找到目的地」的直觉。实际上，Agent 更像是一个经验丰富的探险家——它不需要地图，需要的是「注意事项」和「特殊规则」。

洞察二：工具提及的乘数效应 研究数据显示，当某个工具在 context files 中被显式提及时，其使用频率提升高达 160 倍（从 0.01 次/实例提升到 1.6 次/实例）。这意味着 context files 的真正价值不在于「描述项目」，而在于「指定工具链」。

比如，告诉 Agent「使用 uv 而不是 pip，使用 bun 而不是 npm」比列出整个目录结构有用 100 倍。

洞察三：Context Engineering 需要从「全面文档」转向「精准手术」 不要写一本说明书，要写一份「手术指南」——只包含非显而易见的信息、非标准的工具链、项目的「为什么」而不是「是什么」。

🛠️ 实践指南：写好 Context Files 的新规则

✅ 应该包含的内容（Vital Few）

  • 技术栈与项目意图：解释「做什么」和「为什么」，帮助 Agent 理解项目目的和架构（如 monorepo 结构）
  • 非标准工具链：这是 AGENTS.md 真正的杀手级用例。指定如何构建、测试、验证变更（如「用 uv 不用 pip，用 bun 不用 npm」）
  • 特殊约束和规则：项目特定的、非显而易见的编码实践

❌ 应该排除的内容（Noise）

  • 详细目录树：跳过。Agent 可以自己找到需要的文件
  • 代码风格指南：不要浪费 tokens 告诉 Agent「用 camelCase」，用 linter 和 formatter 更便宜、更快、更可靠
  • 任务特定指令：避免只适用于少部分 issues 的规则
  • 未审核的自动生成内容：不要让 Agent 自己写 context file 而不经过人工审核

📐 结构设计原则

  • 保持精简：高性能 context files 的共识是 300 行以内，专业团队通常控制在 60 行以内
  • 渐进式披露：不要把所有内容放在根文件中，用主文件指向独立的任务特定文档
  • 用指针代替副本：不要嵌入会过时的代码片段，用 file:line 指针指向设计模式或接口

💡 引发思考

这篇论文对当前 Context Engineering 领域的影响是深远的。它揭示了一个根本性矛盾：我们以为在「帮助」Agent，实际上可能在「束缚」它。

对于 Harness Engineering 的实践者来说，这个研究提供了重要的指导——与其花大量时间编写详尽的 AGENTS.md，不如专注于两个关键点：（1）明确非标准工具链，（2）保持 context files 极度精简。Less is more，在 Context Engineering 中比在任何地方都更适用。

更深层的启示：AI Coding Agent 的能力边界在快速扩展。今天需要 context files 才能完成的任务，明天 Agent 可能自己就能搞定。Context Engineering 的最佳策略是「最小化干预」而非「最大化覆盖」。

📚 相关阅读

  • arXiv 原文：https://arxiv.org/abs/2602.11988
  • MarkTechPost 解读：https://www.marktechpost.com/2026/02/25/new-eth-zurich-study-proves-your-ai-coding-agents-are-failing-because-your-agents-md-files-are-too-detailed/
  • 关联论文：On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents (arXiv:2601.20404)
  • Sebastian Raschka 2026 论文列表：https://magazine.sebastianraschka.com/p/llm-research-papers-2026-part1

*逍遥云初 | 2026.06.30*