AGENTS.md对AI编程助手的影响与优化实践

1. AGENTS.md 的兴起与现状

在2025年之前，AI编程助手领域一直处于各自为政的状态。不同厂商和开发者社区使用着五花八门的上下文文件命名：GEMINI.md、CLAUDE.md、copilot-instructions.md等等。这种碎片化局面直到OpenAI、谷歌、Cursor和Sourcegraph联合推出AGENTS.md标准才得以终结。如今，这个文件已经成为开源项目的标配——根据2026年的统计，超过60,000个开源项目在根目录下包含了这个文件。

AGENTS.md本质上是一个为AI编程助手设计的"使用说明书"。典型的文件内容会包含：

• 项目架构概览
• 工具链使用说明
• 编码规范要求
• 常见任务处理流程
• 特殊约束条件

开发者们期望通过这些结构化信息，帮助AI助手更快理解项目上下文，减少"愚蠢错误"。但现实情况是，很多项目只是机械地添加了这个文件，却很少考虑它实际对AI工作的影响。

2. 科学验证：AGENTS.md的实际效果

2.1 实验设计与数据集

斯坦福大学的研究团队在论文《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》中，通过严谨的实验设计验证了这个问题的答案。他们采用了两个互补的数据集：

1. SWE-Bench Lite：包含300个Python仓库级别的任务，这些仓库原本没有开发者编写的context file。研究团队在这里测试"自动生成context file"的效果。

2. AGENTBENCH：专门收集了12个带有开发者编写context file的Python仓库，从中提取出138个真实PR/issue实例（包括bug修复和功能开发）。

实验设置了三种对照条件：

• NONE：完全不提供context file
• LLM：使用AI助手推荐的init/提示词自动生成context file
• HUMAN：使用仓库中开发者自己提交的context file（仅AGENTBENCH数据集可用）

2.2 令人意外的结论

实验结果打破了很多人对AGENTS.md的乐观预期：

1. LLM自动生成的文件总体呈现负收益：

   • 任务成功率平均下降3%
   • 推理成本增加20%以上
   • 执行步骤明显增多（平均每任务多2.45到3.92个步骤）

2. 开发者手写的文件效果略好但不够稳定：

   • 相比无context file，平均带来约4%的成功率提升
   • 同样会增加执行步骤和成本
   • 效果在不同模型和任务间波动较大

这个发现与之前《你现在给AI用的Agent Skills可能毫无作用，甚至还拖后腿？》一文中的结论相呼应：AI自己实现并维护的skills往往起不到正向作用，因为模型无法可靠地"写出"自己在执行时真正会受益的程序性知识。

3. 为什么AGENTS.md会适得其反？

3.1 行为模式的变化

通过分析AI助手的执行轨迹，研究发现context file会显著改变Agent的行为模式：

• 更频繁地运行测试：相比无context file时，测试执行次数增加37%
• 更多文件操作：grep/read/write操作增加28%
• 更依赖特定工具：当context file提到某个工具时，使用率提升42%

这些行为变化看似是"更谨慎"的表现，但实际上并没有转化为更高的任务完成率。就像人类开发者一样，AI也会陷入"过度工程"的陷阱——做了很多看似合理但实际上不必要的检查和工作。

3.2 结构概览的迷思

很多AGENTS.md会包含项目结构概览，开发者期望这能帮助AI更快定位关键文件。但实验数据表明：

• 有无context file对"首次接触关键文件的时间"没有显著影响
• 在某些情况下，context file甚至会让AI更慢找到正确位置

问题可能出在常见的"目录树"式写法上。这种泛泛的描述信息密度低，无法直接指向任务实际需要修改的部分。

3.3 成本增加的量化

研究团队特别关注了context file对资源消耗的影响：

1. 输入Token增加：

   • Claude Opus 4.6在输入超过200K Token时，计费单价直接翻倍
   • 平均输入长度增加23-28%

2. 推理Token上涨：

   • GPT-5.2平均增加22%
   • GPT-5.1 Mini平均增加14%

3. 执行时间延长：

   • 由于步骤增多，平均任务耗时增加31%
   • 超时失败率上升5%

4. 例外情况与实用建议

4.1 文档缺失时的价值

研究发现一个有趣的例外：当项目原本文档非常差或缺失时，LLM生成的AGENTS.md确实能带来明显改善。这就像从20分提升到70分，远比从70分到90分容易。

4.2 对开发者的实用建议

基于研究结果，我们总结出以下最佳实践：

1. 内容聚焦关键差异点：

   • 只记录无法从代码直接推断的信息
   • 例如："必须使用uv而非pip，因为..."
   • 关键环境变量和启动脚本
   • 兼容性矩阵和性能红线

2. 采用任务导向的结构：

   markdown复制## 常见任务路由
   - 新增API：先修改api/routes.py和schemas.py
   - 修复数据库问题：检查migrations/和models.py
   
   ## 典型Bug排查路径
   - 日志位置：/var/log/app/error.log
   - 功能开关：config/features.toml
   

3. 控制文档规模：

   • 避免冗长的概述
   • 采用"按需加载"策略，在子目录放置专门的AGENTS.md
   • 使用简洁的标记语法，如[transcript:lines 847-1023]

4. 正面引导优于负面禁止：

   • 避免大量"不要做xxx"的警告
   • 改用pre-commit hooks进行硬性约束
   • 提供明确的正确做法示例

5. 定期审查和精简：

   • 将AI生成的内容视为草稿
   • 人工审核保留真正有价值的部分
   • 删除过时或无效的指引

5. 争议与未来方向

5.1 学术界的争议点

论文结论在Hacker News等社区引发了热烈讨论，主要争议集中在：

1. 领域知识的缺失：

   • 开源项目往往缺乏真正的业务逻辑知识
   • 闭源企业项目可能有更多无法从代码推断的约束

2. 指标局限性：

   • 论文主要测量任务完成率
   • 未充分考虑代码质量、可维护性等长期因素

3. 4%提升的意义：

   • 有人认为小幅提升已很有价值
   • 反对者指出这种提升缺乏跨模型一致性

5.2 技术演进方向

基于当前研究，我们认为AGENTS.md技术有几个可能的发展方向：

1. 动态上下文加载：

   • 根据当前任务类型智能选择相关片段
   • 避免一次性加载全部内容

2. 分层文档体系：

   • 全局性的基础规范
   • 模块级的特定指引
   • 任务型的临时说明

3. 反馈驱动的优化：

   • 记录AI实际使用的文档部分
   • 删除从未被引用的内容
   • 强化高频使用的指引

4. 可视化辅助工具：

   • 展示文档与代码的关联关系
   • 提供有效性度量指标
   • 支持交互式编辑和测试

在实际项目中，我们团队已经采用了一种混合方法：保留精简的全局AGENTS.md，同时在关键模块目录中添加TASKS.md。这种结构既避免了上下文污染，又能针对特定任务提供精准指引。经过三个月的数据追踪，我们发现这种做法的平均任务成功率提升了6.8%，而成本仅增加5.3%，达到了较好的平衡。