一份覆盖6万开源项目的实证研究，首次系统检验AGENTS.md对AI编码代理的实际影响。结果颠覆常见认知：自动生成的文档普遍拉低任务完成率、推高推理开销，而人工编写的微弱收益也高度依赖项目成熟度与内容针对性。
智能速览
2026年统计显示超60,000个开源项目已采用AGENTS.md，但实测中LLM自动生成版本导致任务完成率下降3.2%～5.7%
人工编写的AGENTS.md仅在特定场景带来平均+4%的成功率提升，且效果不跨模型稳定复现
引入AGENTS.md后，GPT-5.2推理token平均增加22%，Qwen3-30B-Coder调用工具次数上升37%
实验发现文档未加速关键文件定位——有无AGENTS.md对触达PR修改文件的耗时无显著差异
文档价值呈倒U型分布：原始文档越差（如缺失安装/测试说明），LLM生成版收益越明显；规范完善的项目反而负向干扰
精华内容
当上下文文件成为标配，我们更需追问：它究竟在帮AI理解代码，还是在给AI加戏？这篇研究用两套互补数据集与四组主流模型组合，给出了可量化的答案。
负收益成常态
在AGENTBENCH基准测试中，所有LLM自动生成的AGENTS.md均导致任务完成率下降。Claude Code + Sonnet-4.5组合下降5.7%，Codex + GPT-5.2下降3.2%。对照组使用真实开发者手写文档时，仅在闭源风格强约束项目中观察到+4.1%的微弱提升，且该提升在GPT-5.1 Mini上不可复现，说明效果不具备模型普适性。
论文明确指出，负收益并非因模型‘不听话’，而是因文档触发了更多探索性行为——平均多执行2.8次测试、多调用1.6个工具，但这些动作并未转化为更高通过率，反而使12.4%的任务因超时失败。
更关键的是，这种负向影响随项目成熟度升高而加剧：在文档完整度＞80%的项目中，自动生成文档使错误归因率上升29%，即AI更频繁将失败归咎于环境配置而非逻辑缺陷。
成本显著攀升
上下文文件直接推高推理开销。GPT-5.2在加载AGENTS.md后平均推理token增加22%（从1,840→2,245），GPT-5.1 Mini增加14%（从1,520→1,733）。Qwen3-30B-Coder的工具调用频次上升37%，主要集中在重复执行lint检查与依赖验证。
这种成本增长并非无效劳动。trace分析显示，当文档中声明‘必须运行pre-commit hooks’，92%的agent会强制插入该步骤，即使当前任务仅需修改单行注释。类似地，文档提及‘所有PR需包含性能对比报告’时，agent会在单元测试通过后额外启动benchmark流程，平均延长执行链3.2步。
值得注意的是，token增幅与文档长度非线性相关：500字符以内文档引发的token增长可控（＜8%），但超过1,200字符后增幅陡增至31%，印证了上下文压缩机制在长文本下的失效风险。
定位效率未改善
针对‘仓库概览是否加速问题定位’这一核心假设，研究设计了精准指标：统计agent首次访问PR实际修改文件的步数。结果显示，有无AGENTS.md对中位步数无统计学差异（p=0.63），且在大型仓库（＞50k LOC）中，含文档组平均多走1.7步。
进一步分析发现，agent并未利用文档中的目录结构描述。当文档明确标注‘src/core/是业务逻辑主目录’，仅38%的agent首先进入该路径；而无文档组中，基于代码引用关系自动推导出该路径的比例为41%。
这说明现有AGENTS.md的‘overview’类内容未被有效消费。真正起作用的是隐含约束——例如文档注明‘config.py禁止硬编码API密钥’，使密钥泄露类错误下降63%，但这类内容仅占实测样本中优质文档的12%。
适用场景有边界
文档价值呈现强条件依赖性。在原始文档缺失率＞65%的项目中（如新启动的CLI工具），LLM生成的AGENTS.md将任务成功率从31%提升至68%，主要贡献在于补全基础操作链：87%的提升来自明确写出‘npm install && npm run dev’而非仅‘see README’。
但当项目已有规范README且文档完整度＞75%时，新增AGENTS.md使平均修复轮次增加2.3次，因agent过度关注文档中冗余的CI策略（如‘每次提交需触发3个不同云环境测试’），而忽略代码本身的逻辑矛盾。
研究建议采用‘按需加载’策略：在feature/目录下嵌套AGENTS.md，仅当任务涉及该模块时才注入。实测表明，该方式使无关工具调用减少54%，且在微服务架构项目中将成功率稳定维持在+3.8%水平。
AGENTS.md的价值不在‘有无’，而在‘为何而写’。它不是通用说明书，而是针对AI认知盲区的精准补丁。当文档聚焦不可推断的隐含约束、历史决策与失败模式时，才能释放真实效能。未来的关键或许不是堆砌上下文，而是建立人机协同的文档演进机制——让AI起草，由开发者校准，用真实错误驱动迭代。下一个值得追问的问题是：什么样的轻量级标记，能让AI一眼识别出‘这里必须人工确认’？
