二十年来，文档一直是良好初衷的坟墓。你在第一个 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%。相比之下，由人类编写的文件带来了约四个百分点的稳健收益。教训不是“文档有用”，而是“正确的文档有用，而错误的文档会主动毒害环境”。
其中的机制在于指令预算。前沿模型能够以合理的连贯性遵循大约 150 到 200 条指令，而这种连贯性会随着指令数量的增加而均匀下降 —— “均匀”是一个残酷的词。模型不会在遵守前 200 条指令的同时礼貌地忽略第 201 条。随着你堆砌指令，它会开始同时忽视所有的指令。一个堆满各种命令、边缘情况和代码风格细节的臃肿 AGENTS.md 并不能给 Agent 提供更多助力。它稀释了那几条真正重要的指令，直到没有一条能可靠落地。
这颠覆了文档编写的整个心理学。对于人类读者，完整性是一种美德 —— 细节越多意味着问题越少。对于 Agent，完整性是一种负担。这项技能不再是写得详尽，而是编写最小的高价值约束集，并无情地删除模型可以自行发现的一切内容。告诉 Agent 你的测试文件以 .test.ts 结尾是在浪费预算 —— 它两秒钟就能看出来。而告诉它你的支付服务绝不能记录银行卡号（这是一条在代码中任何地方都没有体现的规则），则是无价之宝。
过时的文档现在是生产环境的隐患 在旧时代，过时的文档只是一种烦恼。但在 Agent 时代，它是具有运营后果的隐患，因为 Agent 无法分辨新鲜事实与陈旧事实之间的区别。它会满怀信心地套用文档中的架构，即便该架构早在两个季度前就被重构掉了。在 Agent 系统中，静态文档会产生“充满自信的错误输出”，而不是诚实的失败——这是最糟糕的错误模式，因为它看起来非常专业，从而能轻易通过评审。
这会将文档维护从一个纪律问题重构为一个基础设施问题。“记住更新文档”对人类来说始终是一个注定失败的指令，而在利害关系更高的今天，它的扩展性也并没有变得更好。做得好的团队正在像对待数据质量或测试覆盖率一样对待上下文：将其视为一个具有自身节奏的活系统。他们区分了声明式 上下文（人类编写并拥有的不变式）、衍生式 上下文（从代码生成的实事，如 API 签名，应在 CI 中重新生成）以及观测式 上下文（从系统实际行为中推断出的模式）。每种类型都有不同的保鲜机制。声明层简短且由人工维护。衍生层自动重建，因此永远不会与它所描述的代码脱节。
实际结论是：停止亲手编写任何工具可以同步的内容，并积极保护那一小部分由人工编写的核心内容免于腐烂。如果关于系统的一个事实可以生成，那么在每次提交时都生成它。如果它只能由人类知晓——例如设计决策、辛苦得出的约束、刻意偏离常规方案的做法——那就写一次，保持简短，并像对待 Bug 一样对待任何偏差。
如何编写 Agent 真正会使用的文档 基于以上内容，我们可以得出几项原则，它们与过去十年的文档建议几乎完全不同。
保持核心文件简短。 衡量这一点的实践者目标通常远低于 300 行，优秀的案例通常在 60 行以下。你添加的每一行都会消耗已有每一行的指令预算。如果你想做到面面俱到，那么你优化的目标读者就选错了。记录不可发现的内容，删除可发现的内容。 Agent 可以阅读你的文件树、package.json 和导入语句。但它无法阅读你的意图。要把预算花在不变式、领域词汇和你刻意排除的方案上——这些是代码中任何地方都不存在的上下文。不要让模型去做 Linter 的工作。 风格规则是人们往这些文件里塞的最常见也最浪费的东西。格式和 Lint 规则属于在每次提交时运行的确定性工具，而不是模型“大部分时间”遵循的概率性指令。偏好指针而非副本。 引用 file:line 位置，而不是粘贴代码片段。粘贴的代码在原件更改的那一刻就会过时；而指针始终保持权威。仅这一习惯就能消除一大类“充满自信的错误输出”。使用渐进式披露。 保持根文件精简，并链接到更深层次的主题文件（如 agent_docs/deployment.md、agent_docs/auth.md），Agent 只有在任务涉及该领域时才会调取这些文件。在 Monorepo 中，层级约定意味着 Agent 会读取离它正在编辑的代码最近的文件，因此每个包的上下文会覆盖根设置，而不会使根文件臃肿。不要自动生成高杠杆文件。 “抓取仓库并编写文档”的命令虽然方便，但对于最重要的那个文件来说却是适得其反的。自动生成会产生臃肿、可发现、低信号的内容，数据显示这会损害性能。亲手编写核心内容；这是你在代码库上花费的投资回报率最高的一小时。 文档复兴是重组，而非复旧 人们很容易将其描述为文档终于得到了它应有的尊重。但这个视角是错误的。README 变得更加重要，并不是因为我们集体良心发现。它变得更重要，是因为我们给它连接了一个极其诚实的消费者——它会阅读每一个字，字面上遵循指令，无法推断出文档之外的空白，并以破坏代码的形式展现出每一个疏漏和谎言的代价。
这场复兴并不是旧文档美德的回归。它是围绕新原则的重组：极简主义优于完整性，规定性优于描述性，指针优于副本，将“保鲜”视为基础设施而非纪律。内化了这一点的团队发现，花一小时打磨一个 60 行的 AGENTS.md，比在 Agent 的聊天窗口花一天时间逐一纠正错误能带来更多可运行的软件。代码库最高杠杆的接口不再是 IDE 或 API，而是你为阅读它的机器所写的文字。
就像你刚刚入职了一位最强大、最刻板且最不留情面的新员工一样去编写它——因为事实确实如此。
余下内容仅对会员开放。 会员可读完整内容 —— 每一个公开发布的观点背后，那些框架、决策与推理的全貌。
— 完整文章，包含未公开存档的部分 — 可落地的工作框架，附带权衡与决策依据 — 新文章抢先看，先于公开发布 登录以继续阅读→ 随时取消 · 一次订阅，畅读全部
