别让 AI 自动生成项目文档：成本涨两成，收益却没证据

越来越多项目在根目录放一份 AGENTS.md（或 CLAUDE.md、.cursorrules），专门写给 AI 看：这个项目怎么跑、什么不能碰、做完算完成。

这个文件已经从"个人习惯"变成了事实标准：OpenAI 在 2025 年 8 月提出这个格式，到 2025 年 12 月已有超过六万个开源项目在用，并由 Linux Foundation 旗下的 Agentic AI Foundation 接管治理。

但很多人的做法是：让 AI 自己生成一份。2026 年终于有了针对这件事的实证研究，结论比"不划算"更值得琢磨。

这项研究来自 ETH Zurich 的 SRI 实验室（论文《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》，2026 年预印本）。他们用四个主流编码智能体跑了两组真实任务（一组是常用的公开基准，一组是他们专门挑的 138 个小众仓库任务，避免模型背过答案），对比三种情况：没有说明文件、AI 生成的说明文件、开发者手写的说明文件。

结果分两层看：

成本是确定的：不管质量好坏，说明文件都会让智能体每任务多走 2.45 到 3.92 个步骤，推理成本上升 20% 以上。原因很实在——它很听话。文件里提到某个包管理器，它就真的去用；文件里说跑全量测试，它就真跑。指令变成了必须执行的工作，不管这次任务需不需要。

收益是不确定的：分组数据上，AI 生成的平均低约 3 个百分点，人工手写的平均高约 4 个百分点，但这些差异在统计上并不显著——论文原文的说法是"LLM 生成的文件对成功率有微弱负向影响，人工手写的文件有微弱正向收益"。换句话说，自动生成基本可以确定是拖后腿，手写能不能带来提升则证据不足，两者都远没有"加个文件就好了"那么神。

还有个细节很有意思：几乎所有自动生成的文件里都有"项目结构概览"这一段，但研究测下来，它并没有帮智能体更快定位到要改的文件——毕竟列目录这种事，它自己一步就能做完。

论文给出的建议也很直接：

省略自动生成的文件；人工手写的话，只写"最小必要要求"——也就是智能体自己推断不出来的东西：自定义工具、非常规的构建命令。

补充一个有意思的对照：同年另一项研究（Williams College）换了做法——不是一次性写完，而是先造一批问题样例，观察智能体在哪些指引上失败，再反复迭代修补这份文件。结果是任务解决率从 25.5%（无指引）→ 28.3%（静态指引）→ 33.0%（迭代调优后的指引）。也就是说：文档有用，但价值来自"迭代"，不来自"生成"。

把这些数字摆在一起，靠谱的判断有点扫兴：

说明文件不是效率神器。目前最严谨的研究没有观测到它对任务成功率有显著提升，但一定会让成本上升约 20%。如果你的期待是"加个文件，AI 就变聪明了"，那是期待错了。

但自动生成是明确负收益。这一点研究结论很干脆：直接省略。它生成的往往是冗长重复、以及 AI 自己本来就能从代码里读出来的内容——等于花钱买噪声。

手写的定位是"兜住下限"，不是"提升上限"。它真正的价值不在让 AI 变强，而在避免它猜错：用错包管理器、动到不该动的目录、不知道该跑哪条命令。这些错误的代价很高，而避免它们的成本很低。

想让它真的提升成功率，得靠迭代而不是写作。前面那项对照研究已经说明了：一次性写完的静态指引只有微弱收益，而用失败样例反复调优出来的指引能带来明显提升。文档是活的，不是一次性的。

（也要说明：厂商自己公布的评估里有更乐观的数字——比如某平台的内部评测显示常驻文档索引的通过率远高于无文档。这类数字来自厂商自评，样本和口径与学术研究不同，参考价值有，但别当成定论。）

把上面的结论收一下：这份文件不是效率神器，而是兜底工具。

可以写，但要写极少——只写 AI 自己推断不出来的东西（自定义工具、非常规命令、绝对不能碰的目录）；不要自动生成，因为它生成的往往是冗长重复、AI 本就能从代码读出的内容；写完也别供着，要拿失败样例反复迭代，而不是一次性写完。

至于"具体该写哪几块、don'ts 怎么写、多个 AI 工具怎么共存"——那是另一篇的事。

一份会被 AI 真正执行的文档，标准是：短到每次运行都能完整读一遍，且只含它猜不到的东西。

#智能体 #AGENTS.md #AI编程 #工程规范 #技术实践