作为 AI Coding 的 “标配文件”，AGENTS.md 已被超过 60000 个开源项目纳入根目录。它由 OpenAI、谷歌等厂商联合制定标准，旨在为 Coding Agent 提供仓库概览、工具链指令、编码规范等上下文，甚至不少 Agent 支持用/init命令自动生成。但一篇名为《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》的论文，却抛出了颠覆性结论：LLM 自动生成的 AGENTS.md 会让任务成功率下降 3%、成本上涨 20%+；即使是开发者手写的版本，也仅带来 4% 左右的微弱正收益，且稳定性不足。
AGENTS.md 究竟是 AI Coding 的 “神助攻”，还是徒增负担的 “鸡肋文件”？答案并非非黑即白 —— 问题不在于文件本身，而在于 “怎么写” 和 “怎么用”。
一、实验揭秘：AGENTS.md 的真实效果到底如何？
论文通过两套数据集（SWE-Bench Lite、AGENTBENCH）和三种对照设置（无文件、LLM 自动生成、开发者手写），对 Claude Code、GPT-5.2、Qwen3-30B 等主流模型进行了测试，结果颇具争议：
1. 核心结论：自动生成 “负收益”，手写 “微收益但贵”
-
LLM 自动生成：平均让任务成功率下降 3%，推理成本上涨 20%-23%。比如 Claude Opus 4.6 输入 Token 超过 200K 时计费单价翻倍，而自动生成的文件会让 Token 消耗激增，还会让 Agent 平均多执行 2.45-3.92 个步骤；
-
开发者手写：在 AGENTBENCH 数据集上平均提升 4% 的成功率，但同样推高成本，且收益不具备跨模型一致性 —— 在部分模型上甚至毫无效果；
-
例外情况：当项目原本文档极差或缺失时，LLM 生成的 AGENTS.md 反而能补全依赖安装、测试启动等关键信息，实现从 20 分到 70 分的提升；但对于文档成熟的项目，反而会添乱
2. 为什么会这样？Agent “听话但不聪明”
实验追踪发现，AGENTS.md 并没有让 Agent 更精准，只是让它更 “折腾”，核心问题集中在三点：
-
行为异化：Agent 会严格遵守文件中的流程要求，频繁跑测试、广泛翻阅仓库文件、过度使用指定工具（如 uv、repo_tool），但这些额外操作并未转化为更高命中率，反而容易跑偏；
-
关键文件定位变慢：文件中常见的 “仓库目录概览” 信息密度低，无法直接指向 “任务常改文件”，导致 Agent 触达核心文件的时间反而比无文件时更长；
-
推理负担加重：额外的流程规范、检查点要求让 Agent 的推理 Token 激增 ——GPT-5.2 的推理 Token 平均增加 22%，GPT-5.1 Mini 增加 14%，任务超时风险上升。
3. 模型与提示词：无法挽救的本质缺陷
论文还测试了 “更强模型是否能改善效果”“不同提示词是否影响结果”，结论是：
-
用 GPT-5.2 这类强模型生成 AGENTS.md，在一个数据集上可能涨分，在另一个上反而跌分，无稳定收益；
-
切换 Codex 或 Claude Code 的生成提示词，也没有一致的输赢，本质是 AI 的概率预测特性导致自动生成缺乏可靠方法。
二、争议焦点：4% 的收益到底值不值？
论文结论在 HN 等社区引发激烈讨论，核心争议集中在四个维度，不同视角的碰撞让 AGENTS.md 的价值更清晰：
1. 争议一：开源项目缺乏 “核心价值”，闭源项目才需要
-
支持者观点：AGENTS.md 的最大价值是传递 “代码无法推断的领域知识”（如业务背景、历史决策、隐含约束），但开源项目很少包含这类信息，闭源大项目才是真正刚需场景，论文 benchmark 无法体现；
-
反对者观点：即使是闭源项目，手写领域知识的成本高，且 Agent 未必能有效吸收，4% 的收益不足以覆盖维护成本。
2. 争议二：指标单一，忽略 “隐性价值”
-
支持者观点：论文仅测试 “任务完成率（exec (test)=PASS）”，但 AGENTS.md 的真实价值是减少蠢错、降低后续重构成本、保证团队规范统一，这些隐性收益未被量化；
-
反对者观点：论文已测成本与步骤，发现 Agent 的 “谨慎行为” 并未转化为更高质量的代码，反而徒增消耗，隐性价值缺乏数据支撑。
3. 争议三：仓库越大越需要？论文给出反例
-
支持者直觉：大型仓库文件繁多，Agent 需要 AGENTS.md 指引入口，但论文发现 “目录概览” 写法无效，无法加速关键文件定位；
-
折中观点：不是仓库大不需要，而是写法不对 —— 泛泛的目录树没用，精准的 “任务路由” 才有用。
4. 争议四：4% 的收益微不足道？
-
支持者观点：一个简单的 md 文件就能带来 4% 的成功率提升，对于大规模项目已是显著增益；
-
反对者观点：4% 的提升不跨模型，且伴随 20%+ 的成本上涨，投入产出比极低，不如优化其他环节。
三、正确用法：让 AGENTS.md 从 “负收益” 变 “高效助攻”
论文和社区实践都证明，AGENTS.md 的价值不在于 “有没有”，而在于 “写什么” 和 “怎么写”。想要发挥作用，需遵循 “少而精、针对性、按需加载” 三大原则：
1. 核心原则：只写 “代码推不出来” 的关键信息
AGENTS.md 的黄金法则是：放弃 “大而全的百科全书”，聚焦那些 Agent 从代码中无法推断、却容易反复踩坑的内容，例如：
-
工具链约束：“仅支持 uv 包管理，不支持 pip，原因是项目依赖的 xx 库仅 uv 能正确解析”；
-
环境配置：“必须通过
./scripts/start-env.sh启动集成环境，需设置 ENV=prod、API_KEY=xxx”； -
关键规则：“兼容性需覆盖 Python 3.10+，性能红线为单接口响应≤200ms，禁止直接操作数据库”。
2. 结构优化：少写 “目录导览”，多写 “任务路由”
无效的 AGENTS.md 列满目录树，有效的 AGENTS.md 直接指向 “做什么、找哪里”，推荐结构：
-
常见任务→入口文件：“新增 API→先修改
api/routes.py定义路由 +schemas.py定义数据结构”“修复支付 bug→优先查看services/payment/目录，日志路径为logs/payment-error.log”； -
常见问题→排查路径：“出现‘依赖冲突’→先执行
uv sync --frozen，无效则删除__pypackages__目录重试”“测试失败→先检查 feature flag 是否开启（路径：config/feature_flags.yaml）”。
3. 部署技巧：嵌套使用 + 按需加载，避免 Token 浪费
-
嵌套部署：大型 monorepo 可在根目录放 “全局规则”（安全、合规要求），子项目目录放 “局部指令”（专属工具链、业务规则），Agent 会优先读取当前目录的文件，避免全局上下文污染。例如 OpenAI 主仓库已用 88 个嵌套 AGENTS.md 实现细粒度控制；
-
精简写法：避免冗长描述，用 “[transcript:lines 847-1023]” 这类标记替代大段代码引用，防止上下文压缩时关键信息丢失；
-
正面引导：少写 “不要做什么”，多写 “应该做什么”，必要时用 Pre-commit Hooks 硬性约束，比文档提示更有效。
4. 生成策略：LLM 当草稿，人类来把关
自动生成并非完全不可用，正确流程是：
-
用低成本模型（如 Qwen3-30B）自动生成初稿，补全依赖、测试等基础信息；
-
人工审阅删减，保留关键约束和任务路由，删除泛泛的目录描述和重复信息；
-
AI 犯错后，针对性添加补丁指令，而非一次性写满所有规则。
四、总结：AGENTS.md 的价值，在于 “精准赋能” 而非 “全面覆盖”
AGENTS.md 不是 AI Coding 的 “万能钥匙”，但也绝非 “无用文件”。它的核心问题是被滥用 —— 很多项目把它当成 “仓库说明书”，写满 Agent 不需要的信息，反而拖慢效率。
真正有效的 AGENTS.md，是 “针对性的提示卡”：只包含代码推不出来的关键信息，用任务路由替代目录导览，用嵌套部署控制上下文范围。对于文档缺失的项目，它能快速补全基础操作；对于成熟项目，它能减少重复踩坑；对于大型仓库，它能精准指引方向。
60000 + 项目的选择并非盲目，只是大多数人没用对。放弃 “大而全” 的执念，聚焦 “少而精” 的关键，AGENTS.md 就能从 “负收益文件” 变成 AI Coding 的 “高效助攻”。