使用 Claude Code 防止文档漂移：让文档与代码保持一致

什么是文档漂移（以及为什么它屡次发生）

文档漂移是文档所述内容与代码实际行为慢慢脱节的过程。它从小的差异开始，然后变成那种“我们上个月确实能运行”的困惑。

在真实团队里，漂移看起来是这样的：README 说可以用一个命令运行服务，但现在需要一个新的环境变量。API 文档显示某个端点有个字段，但字段已被重命名。运行手册告诉值班人员重启 worker-a，但该进程现在被拆成了两个服务。

即便是出于良好意图，漂移也会发生，因为软件变化的速度往往快于写文档的习惯。人们在压力下发布修复，复制旧示例，或认为别人会稍后更新文档。当你有太多看起来像“事实来源”的地方时（README 文件、API 参考、内部 wiki 页面、工单和经验知识），漂移也会加速增长。

成本是具体的：

• 入职受阻（新员工因安装问题损失数日）。
• 部署失败（步骤与当前配置不符）。
• 支持压力上升（用户按照过时说明操作）。
• 事故延长（运行手册把响应人员引向错误方向）。

润色文字不能解决事实错误。有效的方法是把文档当成可以验证的东西：将它们与当前代码、配置和真实输出比较，并指出那些文档承诺而代码不再支持的矛盾。

漂移常出现的位置：README、API 文档与运行手册

漂移通常出现在人们当作“速查”的文档中。它们只更新一次，而代码继续变化。先从这三类开始，因为它们包含可以检验的具体承诺。

README：用户最先感到痛点的地方

当日常命令发生变化时，README 就会漂移。新增一个 flag、移除一个 flag 或重命名环境变量，但安装部分仍显示旧的状态。新成员复制粘贴说明，遇到错误，就认为项目有问题。

最糟的是“几乎正确”的版本。缺一个环境变量可能浪费比完全过时的 README 更多的时间，因为人们会反复尝试微小变体，而不是怀疑文档本身。

API 文档：不一致的数据结构和误导示例

当请求或响应字段发生变化时，API 文档会漂移。即便是小的调整（重命名键、不同默认值、新的必需头）也会破坏客户端。常见情况是端点列表是正确的，但示例是错误的，而用户正好会复制这些示例。

典型信号：

• 示例负载包含服务器不再接受的字段。
• 响应样例显示旧的错误格式或状态码。
• 参数表把现在必需的字段标注为可选。
• 认证说明提及不再生效的头或 scope。
• 分页、排序或过滤规则与实际不符。

运行手册：安静的漂移导致严重的事故

当部署、回滚或运维步骤变化时，运行手册会漂移。一个过时的命令、错误的服务名或缺失的前置步骤都可能把常规修复变成停机。

它们也可能“准确但不完整”：步骤仍然可用，但跳过了新的迁移、缓存清理或功能开关。这时响应人员照着手册做，仍会感到意外。

如何使用 Claude Code：生成 diff 与矛盾报告

在处理文档漂移时，把文档当成代码来对待：提出一个小且可审查的补丁并解释原因。不要只让它“更新 README”，而是要求它针对具体文件生成差异。审阅者能看到清晰的前/后对比，并能快速发现意外改动。

一次好的漂移检查会产出两样东西：

1. 一个最小差异
2. 一份直接且具体的矛盾报告："文档说 X，仓库显示 Y。"

要求证据，而不是意见

当你给出提示时，强制要求仓库中的证据：文件路径和像路由、配置值或测试之类能证明当前行为的细节。

下面是一个让输出保持扎实的提示模式：

Check these docs for drift: README.md, docs/api.md, runbooks/deploy.md.
Compare them to the current repo.
Output:
1) Contradictions list (doc claim -> repo evidence with file path and line range)
2) Unified diffs for the smallest safe edits
Rules: do not rewrite sections that are still accurate.

如果 Claude 说“API 使用 /v2”，让它以路由器、OpenAPI 规范或集成测试为证据支持该说法。如果找不到证据，它应该明确说明。

在编辑前限定变更范围

漂移通常始于一处代码变更，却悄然影响多处文档。让 Claude 先限定影响范围：发生了什么变化、在哪改了、哪些文档可能被破坏、哪些用户行为会受影响。

示例：你把环境变量从 API_KEY 重命名为 SERVICE_TOKEN。一份有用的报告会找到旧名字出现的每个地方（README 的安装、API 示例、运行手册的密钥部分），然后生成紧凑的 diff，仅更新那些行以及会导致示例命令失败的部分。

在你提示之前先建立一个简单工作流

如果你把模型指向“所有文档”而不给规则，通常会得到被重写的段落但仍含错误事实的结果。一个简单的工作流能让改动小、可重复且易于审查。

从一个文档集开始：README、API 参考或人们确实使用的一份运行手册。从一个区域端到端修复可以教会你在扩展前信任哪些信号。

决定哪些算作事实来源

用简单语言写下该文档集的事实来源。

• 对于 README：CLI 帮助输出和一个可运行的示例应用。
• 对于 API 文档：路由定义加上集成测试。
• 对于运行手册：部署配置和触发该流程的告警。

一旦把这些来源命名，提示会更清晰："将 README 与当前 CLI 输出和配置默认值比较，然后生成补丁。"

选择审阅者能快速验证的输出格式

在首次检查前达成一致的输出格式。混合格式会让人难以看清改动和原因。

一个简单规则集：

• 每次文档改动都要求一个 diff，外加一句话的理由。
• 仅当工具无法安全建议措辞时才允许短的矛盾列表。
• 尽量把 diff 限制在每次只改一个文档文件。
• 将失效示例（命令、请求、代码片段）作为比一般措辞更高的优先级。

一个实用习惯：在每个文档的 PR 中添加一条小备注，例如“事实来源已校验：routes + tests”，让审阅者知道比对了什么。这会把文档更新从“看起来可以”变为“已与真实来源核验”。

按步骤：在每次变更时保持文档与代码一致

把每次代码变更当成一次小型文档调查。目标是早期发现矛盾并产出审阅者可以信任的最小补丁。

先选定要检查的确切文件和一个明确的漂移问题。例如：“我们是否更改了任何环境变量、CLI 标志、HTTP 路由或错误码，而文档仍在提到？”具体的问题能防止模型去改写整段内容。

接着，让 Claude Code 先从代码中提取硬事实。要求它只列出具体项：用户运行的命令、端点与方法、请求与响应字段、配置键、必需环境变量，以及脚本或配置中引用的操作步骤。如果在代码中找不到某项，它应说明“未找到”，而不要猜测。

然后要求一个简单的对照表：文档声明、代码显示的内容，以及状态（匹配、不匹配、缺失、不明确）。这能让讨论保持基于事实。

之后，要求一个包含最小改动的统一 diff。告诉它只修改为解决不匹配所需的行，保留文档现有风格，并避免添加没有代码支持的承诺。

最后给出一个简短的审阅者总结：改了什么、为什么改、以及需要二次确认的点（如重命名的环境变量或新增的必需头）。

API 文档：验证端点与示例的实用方法

当代码悄然改变时，API 文档会漂移：路由被重命名、字段变为必需、或错误格式发生变化。结果是客户端集成失败和无用的调试时间。

使用 Claude Code 检查文档漂移的任务是从仓库证明 API 的行为，然后指出文档中的不一致。让它从路由和处理器中提取清单（路径、方法、请求和响应模型），并与 API 参考中宣称的内容进行对比。

关注人们实际复制粘贴的内容：curl 命令、头、示例负载、状态码和字段名。在一次提示中让它检查：

• 认证要求（头、令牌类型、公开端点）
• 分页参数和默认值
• 错误状态码与 JSON 格式
• 版本行为（v1 与 v2）
• 示例是否匹配当前的验证规则

当发现不匹配时，只接受能引用代码证据（精确的路由定义、处理器行为或模式）的 diff。这能保持补丁小且易审查。

示例：代码现在在 POST /widgets 返回 201 并新增了必需字段 name，而文档仍显示 200 并省略了 name。好的输出会同时指出这两个矛盾，并只更新该端点的状态码和示例 JSON，保持其余内容不动。

运行手册：减少因陈旧流程导致的中断

运行手册在最昂贵的方式下失败：它们看起来完整，但步骤与系统当前行为不符。一次小改动（重命名环境变量或新的部署命令）就能把一次事故延长，因为响应人员跟着不可能成功的步骤走。

把运行手册当作代码：要求针对当前仓库生成 diff，并必须有矛盾呼叫。将它与系统当前使用的脚本、配置默认值和工具进行比较。

关注那些在事故中最容易造成来回折腾的失效点：

• 列出的命令是否与当前脚本和标志一致？
• “默认”配置值是否与应用当前发布的一致？
• 所需的环境变量和密钥是否在代码和部署配置中被引用？
• 部署与回滚步骤是否与当前发布工具和命名一致？
• “已知良好”的值（端口、区域、超时）是否仍然正确？

还要添加快速的预检和预期输出，这样响应人员可以判断自己是否走在正确路径上。简单写“验证它能工作”不够；给出你期待的精确信号（状态行、版本字符串或健康检查响应）。

如果你在平台上构建并部署应用（例如 Koder.ai），这点尤其重要，因为快照与回滚只有在运行手册指定了正确操作且反映当前恢复路径时才有用。

导致漂移恶化的常见错误

让文档成为“漂亮的散文”而不是与代码匹配的一组声明，是制造文档漂移的最快办法。

默默破坏一致性的错误做法

一个常见失误是先要求重写。当你跳过矛盾检查时，可能会得到语言更顺的文本，但仍然描述错误的行为。始终先问：文档宣称了什么、代码做了什么、两者哪里不一致。

另一个错误是让模型猜测。如果某个行为在代码、测试或配置中不可见，就把它标记为未知。“大概”是 README 承诺被发明出来、运行手册变成虚构的根源。

这些问题在日常更新中经常出现：

• 更新某一节但忘了同步示例、错误信息和边缘情况
• 在一个地方（README）重命名概念却没更新 API 文档、配置键或运行手册
• 修正端点描述但忘了更新请求/响应示例
• 更改行为却没更新默认值或限制说明
• 合并文档修改时没有在 diff 摘要中写短的“为什么改了”说明

一个小示例

一个处理器把过期令牌的返回码从 401 改为 403，同时头名从 X-Token 改为 Authorization。如果你只重写了认证部分，可能会漏掉 API 文档中仍然显示旧头的示例，或者运行手册仍在指示值班观察 401 的激增。

当你生成 diff 时，添加一句决策说明，例如："认证失败现在返回 403，以区分无效凭证与缺失凭证。"这可以防止下一个人把文档又“修回”旧行为。

合并文档更新前的快速清单

把每次文档更新当成小审计。目标是在别人下周跟着文档做事时减少惊讶。

捕捉大多数漂移问题的五项检查

在你点击合并前，扫描 README、API 文档与运行手册的具体断言并逐一验证：

• 标出每个包含命令、端点、配置键、环境变量、端口或示例负载的断言。
• 对每个断言记录能证明它的精确文件（源码、配置、模式、迁移、测试或 CLI 帮助输出）。如果找不到证据，就标注为未知而不是猜测。
• 仅在有证据时要求最小 diff。如果断言未知，改动应变为问题或 TODO，而非自信声明。
• 对示例进行合理性检查：输入是否仍与代码接受的参数匹配（参数名、必需字段、头、默认值）？长示例是漂移的温床。
• 对于运行手册，确认步骤覆盖可能的失败、可安全回滚的途径，以及如何验证已恢复。

一个快速的停止规则

如果在同一文档中发现两个或更多未知断言，就暂停合并。要么补充证据（文件路径和函数名），要么把文档收缩为只保留确定的内容。

示例场景：一处功能变更引发三处文档漂移

小团队更新了认证：客户端不再发送 X-API-Key，而是发送短期令牌 Authorization: Bearer <token>。代码发布、测试通过，团队继续前进。

两天后，新开发者按 README 操作。README 仍然说明“在环境变量中设置 X-API-Key”，并给出带旧头的 curl 示例。他们无法在本地运行，便以为服务挂了。

同时，API 文档也过时了。它描述旧头并仍然显示字段名 user_id，但 API 现在返回 userId。文字没有问题，但与代码矛盾，读者就会复制错误的内容。

随后发生一次事故。值班人员按照运行手册上“轮换 API 密钥并重启 worker”的步骤操作。但问题在于配置变更导致的令牌验证失败，手册把他们带入了错误方向，浪费了 20 分钟。

这时 Claude Code 的价值在于它生成 diff 和矛盾报告，而不是完整重写。你可以让它比较认证中间件和路由处理器与 README 片段、API 示例和运行手册步骤，然后提出最小补丁：

- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>

- { "user_id": "..." }
+ { "userId": "..." }

重要的是它能标注不匹配的地方、指向确切位置，并且只改那些仓库证明已过时的内容。

下一步：把漂移检查变成常规工作

当检查变成枯燥且可重复的例行任务时，文档才能保持准确。根据变更的风险选择节奏。快速迭代的代码可以在每个 PR 上运行漂移检查；稳定服务则可用每周一次的扫查加上预发布检查。

把文档漂移当作测试失败来对待，而不是写作任务。使用 Claude Code 生成一个小 diff 和一份简短的矛盾清单，然后修复使文档回到真实状态的最小改动。

一个轻量化且易坚持的例程：

• 每个 PR：对该变更可能影响的文件运行漂移检查（README、API 文档、运行手册）。
• 将 diff 摘要保存在 PR 描述或审阅笔记中，让审阅者看到改了什么和为什么改。
• 优先选择容易回滚的小改动，而非大规模重写。
• 发布前：重新检查用户会复制粘贴的内容（curl 示例、环境变量、部署步骤）。
• 每周：抽查一两份较旧的运行手册，确认它们与当前命令和仪表盘一致。

把那些 diff 摘要保存好，方便日后查阅。一条简短的说明如“文档更新以匹配新 /v2 端点，移除已弃用头，更新示例响应”能在几个月后说明为何改动发生。

把“快照与回滚”的思想应用到文档上。如果某条说明不确定，先在一个地方修改并快速验证，然后将已确认的版本复制到其他位置。

如果你在快速开发阶段，可以在 Koder.ai (koder.ai) 中生成应用及其初始文档，然后导出源码并在常规工作流中继续以可审查的方式修改。目标不是追求完美的文字，而是让人们实际做的事情（命令、端点、步骤）与代码行为保持一致。