11.6 文档与知识库自动化

让代码库自己写文档，让知识库自己保持更新。

读完你能做什么：搭建从代码到文档的自动管线，并避免"文档一写就过时"。

---

一、核心理念：文档从真相源生成

手写文档的根本问题是它会漂移 —— 代码改了，文档没跟上。

解法：让文档从真相源（代码、数据、schema）自动生成，而不是手写维护。

❌ 手写 API 文档 → 代码改了 → 文档过时 → 误导使用者
✅ 从代码/注解生成文档 → 代码改了 → 重新生成 → 始终一致

---

二、场景 1：从代码生成文档

2.1 API 文档

> 读 src/api/ 下所有的路由定义，生成一份 API 文档：
  - 每个 endpoint 的方法、路径、参数、响应
  - 从代码里的校验逻辑推断参数约束
  - 标注需要认证的 endpoint
  输出为 Markdown，按资源分组。

  重要：只写代码里真实存在的，不要补充代码里没有的 endpoint。

最后那句防幻觉 —— 文档生成也是幻觉高发区（见 04.3）。

2.2 架构文档

> 分析代码库的模块依赖，生成架构文档：
  1. 一张模块依赖图（mermaid）
  2. 每个核心模块的职责（从代码推断，标注证据文件）
  3. 关键数据流

  每个断言标注来源文件，你不确定的地方明确标出。

2.3 让文档带证据

每个关于"系统如何工作"的描述，附上对应的 `文件:行号`。
这样读者能验证，也方便未来更新时定位。

---

三、场景 2：文档与代码保持同步

3.1 检测漂移

> 对比 docs/api.md 和 src/api/ 的实际代码，找出不一致：
  - 文档写了但代码里没有的 endpoint
  - 代码里有但文档没写的
  - 参数/响应描述不符的
  列出所有漂移点。

3.2 自动更新

用定时任务或 hook 保持同步：

# CoWork 定时任务
> 每周检查 API 文档和代码的一致性，如果有漂移，生成一份更新后的文档并标出改动

或者用 hook，在 API 文件改动后提醒更新文档（见 06.5）。

---

四、场景 3：为遗留代码补文档

接手陌生项目时，让它边探索边产出文档（结合 11.1）：

> 探索这个未文档化的模块，产出：
  1. 它做什么（一句话）
  2. 公开接口清单（每个函数的作用、参数、返回）
  3. 它依赖什么、被谁依赖
  4. 已知的坑（从代码里的 workaround、TODO 推断）

  全部标注证据。不确定的功能，标"推测：需确认"，不要编。

---

五、场景 4：CoWork 里的文档自动化

CoWork 擅长把内容做成正式文档（见 09.3）。

5.1 从多来源汇总

> 挂载文件夹里有：技术方案.md、会议纪要若干、数据分析.xlsx。
  汇总成一份完整的项目文档（Word），结构清晰，
  数据部分用表格和图表。冲突的信息标出来让我决定。

5.2 研究优先，再生成

关键顺序：先扎实收集内容，再生成文档。

❌ "生成一份关于 X 的白皮书" → 内容是编的
✅ 先研究（搜索、读文件、分析）→ 有了真实内容 → 再调 docx 技能生成

---

六、场景 5：知识库维护

6.1 定期整理

# 定时任务
> 每月检查我们的知识库（挂载文件夹），找出：
  - 超过 6 个月没更新的文档
  - 互相矛盾的内容
  - 提到已废弃系统的文档
  生成一份"待整理清单"

6.2 建立索引

为大知识库建结构化索引，提升检索（见 03.3）：

> 为知识库里的所有文档生成一份索引（每篇一句话摘要 + 主题标签 + 更新日期），
  输出 docs-index.md。以后查找先看索引。

---

七、防止文档幻觉

文档自动化的最大风险是生成看似合理但不准确的内容。三条防线：

防线 1：只写真相源里有的

只描述代码/数据里真实存在的。禁止补充"通常会有"但实际没有的内容。

防线 2：带证据

每个技术断言附 `文件:行号` 或数据来源，方便验证和更新。

防线 3：标注不确定

你推断但不确定的内容，标"推测：需确认"。不要把推测写成事实。

---

八、一个完整的文档管线

【生成】（Claude Code）
> 从 src/api/ 生成 API 文档，带证据，只写真实存在的
  → docs/api.md

【同步】（Hook）
API 文件改动后 → 提醒更新对应文档

【定期检查】（定时任务）
每周对比文档与代码，报告漂移

【对外产出】（CoWork）
需要正式版本时 → 从 docs/*.md 生成带封面、目录的 Word/PDF

从代码到对外文档，全程自动，且始终与真相源一致。

---

常见错误

错误	后果	对策
手写文档维护	必然漂移	从真相源生成
不带证据	无法验证/更新	每条附来源
不防幻觉	文档看着对其实错	"只写真实存在的"
一次生成不维护	又过时了	定时检查漂移
内容没研究就生成	质量差	研究优先

---

延伸阅读

• 11.1 遗留代码库考古
• 09.3 Skills 与 Plugins 在 CoWork
• 04.3 幻觉的成因与锁死方案