代码改完之后，最容易被拖到最后的往往不是实现，而是文档、设计说明和交接材料。结果就是功能看似上线了，别人却看不懂你为什么这样改、边界在哪里、哪些风险还留着、出现问题时该先看哪里。AI 在这一课真正有价值的地方，是帮助你把真实变更转成可协作资产，而不是凭空写一篇“看起来很完整”的文档。
真实研发场景
最常见的事故不是“没有文档”，而是“文档不可信”
很多项目并不是完全没有说明，而是说明总比真实代码落后一拍。设计意图留在聊天记录里，交接重点只在口头讲过，发布摘要只写“优化了一些逻辑”，真正会影响接手者判断的信息却没进仓库，例如：这次为什么选这个方案、哪些边界故意没做、当前风险点在哪里、验证做到了什么程度。
当这些信息缺失时，后续协作者要么不敢改，要么在不了解前提的情况下继续加逻辑，最终文档债和代码债一起增长。
本课真正要做的是“把变更翻译成别人能接住的说明”
AI 很适合做这种翻译工作，因为它擅长把 diff、测试结果、设计碎片和风险点整理成结构化章节。但前提是你必须先提供真实事实，而不是让模型凭空脑补“设计意图”。
传统做法的痛点
文档滞后不是形式问题，而是协作成本问题
| 缺失的信息 | 短期看似没事 | 长期真实成本 |
|---|---|---|
| 设计取舍 | 当事人自己记得 | 其他人无法判断为什么这样做 |
| 边界说明 | 当前提测还能推进 | 后续改动容易越界 |
| 风险与验证 | 上线前大家口头同步过 | 复盘和交接时无法追溯 |
| 变更摘要 | PR 合进去了 | 发布记录和后续定位都困难 |
文档真正的作用，不是满足形式要求，而是降低未来协作的不确定性。
AI 参与文档时最常见的三个问题
- 没有真实 diff 和决策记录，就让 AI 凭空生成设计说明
- 文档只写“做了什么”，不写“为什么这样做、没做什么、风险在哪里”
- 草稿生成后不对照代码和测试校正，最后文档比代码更假
AI 能提效到哪一步
AI 最适合承担的文档动作
- 结构整理：把零散变更整理成背景、方案、边界、验证、风险几个固定部分
- 代码翻译：把实现变化翻成更适合协作阅读的说明
- 交接草稿：列出模块现状、依赖、风险和接手建议
- 发布摘要：从真实变更中提炼出适合同步的重点
必须人工补上的内容
| 内容 | 为什么必须人工补 |
|---|---|
| 方案取舍 | 只有工程师知道为什么放弃其他路线 |
| 风险接受 | 涉及责任与后续动作 |
| 验证结论 | 需要基于真实测试、构建或联调结果 |
| 未完成项 | 模型无法判断哪些是刻意不做 |
一个简单规则是：AI 可以整理说明，但不能替你承担说明背后的决策责任。
推荐工作流
先准备“变更事实包”
在让 AI 起文档草稿前，先收集：
- 相关代码 diff 或改动文件
- 测试、构建、联调结果
- 做出关键取舍的原因
- 已知风险、限制和后续事项
五步文档沉淀法
| 步骤 | AI 产出 | 人工要做什么 | 验证方式 |
|---|---|---|---|
| 1. 收事实 | 变更摘要草稿 | 补齐缺失的设计前提 | 是否能回答“改了什么、为什么改” |
| 2. 起结构 | 设计说明 / 交接材料章节 | 删除空章节，补关键边界 | 是否贴合真实受众 |
| 3. 补取舍 | 风险、边界、未做项草稿 | 写清为何这样取舍 | 是否能支撑后续协作 |
| 4. 对照代码 | 文档与代码差异检查 | 修正文档口径 | 文档是否与实现一致 |
| 5. 入库沉淀 | 最终说明、发布摘要、交接记录 | 放进仓库，而不是聊天窗口 | 未来是否可追溯 |
一个适合文档阶段的输入模板
本次改动涉及：
关键代码路径：
关键决策：
验证结果：
已知风险或限制：
请输出：
1. 设计说明结构
2. 交接重点
3. 发布摘要草稿
与仓库代码和模板的映射
- 仓库总览：
../README.md适合观察“给后来者看的总说明”应该覆盖哪些内容。 - 设计依据：
../课程设计文档.md适合观察课程定位、目标、结构和验收标准如何被完整表达。 - 示例项目说明：
../demo/README.md适合参考“项目定位说明”该如何避免写成空话。 - 设计记录：
../docs/superpowers/specs适合练习如何把设计决策落成文档。 - 实施记录：
../docs/superpowers/plans适合练习如何把计划、范围和验证路径写清楚。 - 对应练习：
../课后练习/第9课/练习.md
常见误用与风险
误用一：让 AI 凭空写文档
没有真实变更事实时，模型最容易写出一篇语气正确但内容空心的说明。
误用二：只写结果，不写取舍和边界
这会让接手者知道“发生了什么”，却不知道“为什么这样做”和“哪里不能碰”。
误用三：交接材料里没有验证方式
没有验证路径的交接说明，别人很难判断当前状态是否可信。
误用四：文档不入库
只存在聊天窗口里的说明，几乎等于未来无法追溯。
课后练习
建议直接在 ../课后练习/第9课/练习.md 中完成本课练习，并使用 ../课后练习/通用提交模板.md 保留 AI 输入、人工删改和验证结果。
如果你只做最小版交付，也至少保留四样东西：结构化输入、AI 产出摘要、人工判断记录、最终验证结果。
基础题
选一个最近的模块改动，先整理一份变更事实包。
进阶题
让 AI 基于事实包生成设计说明或交接草稿，再人工补上取舍、风险和未做项。
挑战题
把最终说明放进仓库，并让另一位同学仅凭该文档复述这次改动的目标、边界和验证方式。