文档复兴：你的 README 是 Agent 的核心上下文界面

二十年来，文档一直是良好初衷的坟墓。你在第一个 Sprint 期间编写 README，那时架构整洁，你的热情高涨。但没人读它。到了第三个 Sprint，它就开始在构建命令上误导人，到了第六个 Sprint，它描述的是一个早已被删除的服务。文档是每个人都同意缴纳但实际上没人在缴的税 —— 一种没有反馈循环的道德准则。写了烂文档，什么也不会发生。不写文档，同样什么也不会发生，因为高级工程师把架构都记在脑子里。

然后我们将编程 Agent 指向我们的代码仓库，反馈循环一夜之间降临。README 现在是你拥有的杠杆率最高的文件 —— 这并不是因为有人做了关于文档规范的励志演讲，而是因为该文件的质量现在直观地决定了你的 Agent 是交付正确的代码，还是会信誓旦旦地对一个已不存在的架构产生幻觉。

这就是文档的复兴，而它与我们过去编写的文档几乎毫无关系。

从描述性到指令性

旧的 README 是描述性的。它为人类叙述系统，人类在入职期间会粗略阅读一次，凭直觉填补空白，然后就再也不打开它。人类是宽容的读者。他们会推断。当文档与代码冲突时，他们会察觉并默默地信任代码。他们会询问隔壁桌的同事。一份陈旧的 README 只会让新员工困惑一个下午，而不会导致生产事故。

Agent 的 README 是指令性的。它不是供人类解读的叙事 —— 它是模型在接触任何一行代码之前加载的执行上下文。当你告诉 Agent “我们使用仓库模式进行数据访问，绝不直接从控制器调用 ORM” 时，这句话不只是背景介绍。它是模型在编写下一个文件时必须遵循或违反的约束。这种文件的标准化形式 —— AGENTS.md（2025 年中期在 agents.md 得到正式定义，由 OpenAI、Google、Anthropic、Cursor、Sourcegraph 和 JetBrains 共同推广，旨在取代碎片化的 .cursorrules、.clinerules 和各类工具配置文件）—— 最好被理解为一份写给会逐字逐句执行的读者的 README。

这种“字面主义”就是游戏的全部。当文档出错时，人类读者的表现会优雅降级。Agent 则不然。它会根据文件中的内容自信地操作，这意味着陈旧的指令不会导致明显的失败 —— 它会产生看似合理、结构良好但错误的代码。糟糕文档的成本从“轻微的人类困惑”变成了“看似正确但错误的输出”，这种转变让 README 从“可有可无的附属品”变成了基础设施。

数据显示：文档质量即任务质量

“更好的文档会有所帮助”这种直觉由来已久。新奇之处在于，这种影响现在是可衡量的、巨大的且直接的。

Anthropic 的内部基准测试报告称，一个格式良好的上下文文件可以将“错误模式重写”（即 Agent 以你的代码库明确拒绝的风格实现某些功能的情况）减少 40 到 60%。在对比研究中，使用压缩且索引良好的文档界面的 Agent，与被迫通过搜索仓库来发现相同事实的 Agent 相比，任务成功率在测算任务中从 79% 跃升至 100%。一旦为特定领域建立了清晰的文档模式，Agent 能以 90% 的正确率完成任务，且第一次生成的代码往往比没有该上下文的人类写出的更简洁。

请将这些数字理解为一个核心观点：文档质量不再是代码质量的代名词。它是代码质量的输入。同一个 Agent，同样的模型权重，完成同样的任务，其成败在很大程度上取决于你在一个 Markdown 文件里写了什么。这赋予了一个大多数团队都视为马后炮的文件惊人的杠杆作用 —— 这也是为什么 README 悄然成为了仓库中最有价值的产物。

这些数字背后有一个结构性原因。没有上下文进行推理的 Agent 会在“探索”上耗尽预算：搜索约定、通过阅读三个文件来推断第四个文件、猜测层与层之间的边界。每一个步骤都是猜错的机会，也是在进入实际任务之前耗尽上下文窗口的机会。好的文档压缩了探索阶段。它预先将不变性交给模型，这样推理预算就能花在解决问题上，而不是花在对你的决策进行逆向工程上。

反直觉的部分：过多的文档会让 Agent 变得更糟

这是复兴与显而易见的结论分道扬镳的地方。如果文档质量决定了成功，那么懒惰的结论就是“写更多文档”。而数据显示，事实恰恰相反。

研究人员测试了 LLM 生成的上下文文件 —— 即通过运行 /init 风格的命令抓取仓库并自动生成的文档 —— 结果在八个测试设置中，有五个的任务成功率反而下降了。使用自动生成文件的 Agent 在每个任务中需要额外 2.45 到 3.92 个步骤，且运行成本增加了 20 到 23%。相比之下，由人类编写的文件带来了约四个百分点的稳健收益。教训不是“文档有用”，而是“正确的文档有用，而错误的文档会主动毒害环境”。

加载中…