hello 大家好，这篇文章想跟大家聊聊 AGENTS.md 在 Code Agent 中的实用性 ，如果大家遇到任何问题，欢迎 联系我 或者直接微信添加 superZidan41
🔥🔥🔥 前方高能，干货满满，建议点赞➕关注➕收藏；
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 编码智能体在未来能够更加智能、高效，真正成为开发者的得力助手。
