1. 引言：AI 编码时代的“新标配”

随着人工智能技术的飞速发展，AI 编码智能体（Coding Agents）正逐渐成为软件开发领域的新宠。这些智能体能够辅助甚至自动完成代码编写、错误修复、功能开发等任务，极大地提高了开发效率。在这一背景下，一种名为 AGENTS.md 的文件格式应运而生，并迅速在开发者社区中流行起来。它被设计为一个专门为 AI 智能体提供项目上下文和指令的“README”文件，旨在帮助 AI 更好地理解项目需求，从而更高效地工作 [^1]。

然而，这些看似能让 AI 变得更“聪明”的上下文文件，真的像我们想象的那样有效吗？它们是 AI 编码的未来，还是潜藏着不为人知的“陷阱”？最近，来自苏黎世联邦理工学院（ETH Zurich）的一项研究 [^2] 对此进行了深入探讨，其结果或许会颠覆我们的认知。

2. 论文速递：ETH Zurich 的硬核实验

这篇题为《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》的论文，对当前流行的 AI 编码智能体上下文文件进行了严谨的评估。研究团队构建了一个名为 AGENTBENCH 的基准测试，其中包含了来自 12 个开源项目的 138 个真实 GitHub 问题，旨在模拟 AI 智能体在实际开发环境中可能遇到的各种挑战。

研究人员测试了多个顶级大型语言模型（LLM），包括 Sonnet-4.5、GPT-5.2、GPT-5.1 Mini 和 Qwen3-30B，比较了它们在“没有上下文文件”、“使用 LLM 自动生成的上下文文件”和“使用人类编写的上下文文件”三种情况下的表现。

核心发现令人震惊：

• LLM 自动生成的上下文文件：不仅没有提高智能体的任务成功率，反而平均降低了 2%，同时还增加了超过 20% 的推理成本。
• 人类编写的上下文文件：虽然能带来微弱的性能提升（平均约 **4%**），但这种提升远不及预期，且同样伴随着成本的增加。

这项研究结果无疑给了我们一个当头棒喝：我们一直以来认为的“好心”，可能在某些情况下反而“办了坏事”。

3. 深度解析：为什么“好心办了坏事”？

为什么这些旨在提供帮助的上下文文件，反而会让 AI 智能体表现不佳呢？论文深入分析了智能体的行为模式，揭示了几个关键原因：

3.1 数据说话：成功率与成本的双重打击

下图展示了不同模型在有无上下文文件情况下的成功率对比。可以明显看出，在大多数情况下，LLM 生成的上下文文件（红色柱）导致了成功率的下降。而人类编写的上下文文件（绿色柱）虽然略有提升，但幅度不大。

此外，上下文文件还显著增加了 AI 编码智能体的工作复杂度和资源消耗。如下图所示，任务步骤和推理成本都出现了明显的增长。

3.2 行为分析：AI 变得“优柔寡断”了？

研究发现，当智能体被提供了上下文文件后，它们会表现出“过度探索”和“过度测试”的行为。这意味着智能体需要花费更多的时间去遍历文件、执行不必要的测试，而不是直接解决核心问题。它们似乎陷入了上下文文件所提供的“信息海洋”中，难以快速聚焦。

3.3 指令陷阱：AI 的“死板”与“误解”

AI 智能体倾向于严格遵守上下文文件中的指令，即使这些指令是冗余的、模糊的，甚至是错误的。当上下文文件包含了过多的背景信息、不必要的细节，或者引导智能体走向错误方向时，智能体仍然会“死板”地遵循这些指令，导致任务复杂化，甚至偏离目标。

论文指出，智能体在处理上下文文件时，会增加其在 PR 补丁中包含的文件进行第一次交互前的步骤数 [^2, Figure 4]。这表明上下文文件可能会导致智能体在实际编码前进行更多的“准备工作”，而这些工作并不总是高效的。

4. 实战建议：如何正确编写上下文文件？

既然上下文文件可能带来负面影响，那么我们应该如何正确地使用它们，才能真正帮助 AI 智能体呢？论文给出了以下实战建议：

4.1 “断舍离”原则：只保留最小化、最必要的项目要求

最有效的上下文文件应该是简洁明了的，只包含智能体完成任务所必需的最小化信息。避免提供冗长的背景故事、不相关的细节或自动生成的“废话”。

4.2 聚焦具体指令：提供清晰的工具使用指南

如果需要智能体使用特定的工具或遵循特定的流程，应在上下文文件中提供清晰、具体的指令和示例。例如，明确指出需要调用的 API、使用的库或遵循的代码规范。

4.3 人类编写的优势：精炼与聚焦

尽管人类编写的上下文文件带来的性能提升有限，但它们仍然优于 LLM 自动生成的。这表明人类在提炼关键信息、避免冗余和提供精确指令方面仍具有优势。因此，建议开发者亲自编写或审核关键的上下文文件。

下图总结了编写 AI 智能体上下文文件的“做”与“不做”：

5. 未来展望：AI 智能体的下一步

这项研究为 AI 编码智能体的发展提供了宝贵的见解。它提醒我们，技术的进步需要严谨的评估和不断的优化。未来，我们可能需要：

• 更智能的上下文处理机制：开发能够自动识别和过滤冗余信息、提取关键指令的 AI 智能体。
• 更灵活的指令遵循策略：让 AI 智能体能够根据任务的实际情况，灵活地解释和执行指令，而不是死板地遵守。
• 优化人机协作模式：探索更高效的人机协作方式，让人类开发者能够更好地引导和监督 AI 智能体的工作。

6. 结语：回归本质，简约而不简单

AI 编码智能体无疑是软件开发的未来趋势，但我们在拥抱新技术的同时，也应保持批判性思维。这篇论文告诉我们，有时候“少即是多”。对于 AGENTS.md 这类上下文文件，回归其本质——提供简洁、精确、必要的指令，或许才是真正提升 AI 智能体效率的关键。

让我们期待 AI 编码智能体在未来能够更加智能、高效，真正成为开发者的得力助手。

参考文献

[^1]: AGENTS.md - README for agents
[^2]: Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?

AI 文章精读 — Feb 27, 2026