案例背景
某开源 SDK 刚发布了 v3.0，包含 30 个公开 API。社区反馈"文档太旧"，需要：
- 为 30 个 API 各生成一份参考文档（签名、参数、返回值、示例）
- 写一篇 5000 字的"从 v2 升级到 v3"迁移指南
- 更新 README 的快速开始部分
传统做法：
- 1 个 API 文档 ≈ 40 分钟（读代码 + 写 + 校对）
- 30 个 = 20 小时
- 迁移指南 1 天
- README 半天
- 合计 约 5 个工作日
我们用 AI 压缩到 4 小时。
工具链
- Claude Code：终端 AI，配合 Filesystem MCP 直接读源码、写文档
- Cursor：润色与可视化校对
- GitHub MCP：读 v2 与 v3 的 diff，提取 Breaking Changes
工作流程
Phase 1：源码扫描与结构化（30 分钟）
Prompt：
用 Filesystem MCP 扫描 src/public/ 目录，
列出所有 export 的 API，输出表格：
| API 名 | 文件 | 行号 | 类型（函数/类/常量） | 签名 |
Claude Code 自动：
list_directory src/public/→ 12 个文件- 对每个文件
read_file→ 解析 export - 输出 30 行表格
| API | 文件 | 类型 | 签名 |
|---|---|---|---|
createClient | client.ts | 函数 | (config: ClientConfig) => Client |
Client.query | client.ts | 方法 | (sql: string, params?: any[]) => Promise<ResultSet> |
| ... | ... | ... | ... |
人工环节：花 5 分钟扫一遍，确认无遗漏。
Phase 2：单 API 文档生成（2 小时）
这是工作量最大的部分，用 链式调用 拆成 3 步。
Step 1：提取 API 元信息
Prompt：
读取 src/public/{file}，针对 API {api_name}：
1. 完整签名（含泛型与默认值）
2. 参数列表：名、类型、是否必填、默认值
3. 返回值类型与结构
4. 抛出的异常类型
输出 JSON。
Step 2：生成示例代码
Prompt：
基于以下 API 元信息，生成 3 个示例：
1. 最简调用
2. 常见场景（带参数）
3. 高级用法（错误处理 + 组合其他 API）
要求：示例必须可运行，类型正确，注释说明每步。
API 元信息：{step1_output}
Step 3：组合成文档
Prompt：
把 API 元信息与示例组合成 Markdown 文档，结构：
## {api_name}
### 签名
{signature}
### 参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
（表格）
### 返回值
{return}
### 示例
{examples}
### 注意事项
（基于源码中的注释与边界条件推断）
### 相关 API
（同模块其他 API 链接）
批量执行
import json
from pathlib import Path
apis = json.loads(Path("api_list.json").read_text())
for api in apis:
# 三步链
meta = call_llm(step1_prompt(api))
examples = call_llm(step2_prompt(meta))
doc = call_llm(step3_prompt(meta, examples))
Path(f"docs/api/{api['name']}.md").write_text(doc)
30 个 API，每个约 3 分钟（受 API 速率限制），总计 90 分钟。
人工环节：随机抽 5 个文档校对，确认：
- 签名正确（AI 偶尔漏泛型）
- 示例可运行（实际跑一遍）
- 无幻觉参数（AI 偶尔编不存在的字段）
Phase 3：迁移指南（1 小时）
这一步最难，因为需要对比 v2 与 v3 的差异。
Step 1：提取 Breaking Changes
Prompt：
用 GitHub MCP 读取 v2.0...v3.0 之间的所有 commit，
筛选标题含 "BREAKING" 或 "breaking" 的提交，
每个输出：
- commit hash
- 变更描述
- 影响的 API
AI 输出 8 个 Breaking Changes。
Step 2：分类与影响评估
Prompt：
把以下 8 个 Breaking Changes 分类：
- 删除的 API
- 改名的 API
- 参数变更
- 行为变更
每类给出迁移策略（旧写法 → 新写法）。
Breaking Changes：{step1_output}
AI 输出：
| 类型 | 旧 | 新 | 迁移 |
|---|---|---|---|
| 删除 | client.execute() | - | 改用 client.query() |
| 改名 | ResultSet.rows | ResultSet.records | 全局替换 |
| 参数 | query(sql, cb) | query(sql, params) | 回调改 Promise |
Step 3：写迁移指南正文
Prompt：
基于分类结果，写 5000 字迁移指南：
1. 概览（v3 主要变化）
2. 快速检查清单（用户能 3 分钟扫完）
3. 逐项详解（每项：旧 → 新 + 代码对比 + 注意点）
4. 自动迁移脚本思路（给伪代码）
5. 常见迁移问题 FAQ
人工环节：
- 在"自动迁移脚本"部分实际写一个 codemod（AI 给的是伪代码）
- FAQ 补充 2 个社区实际问过的问题
- 校对所有"旧 → 新"代码对比的准确性
Phase 4：README 更新（30 分钟）
Prompt：
读 README.md（v2 版），读 src/public/index.ts（v3 入口），
更新 README 的"快速开始"部分：
1. 安装命令（确认 v3 包名）
2. 最小可运行示例（< 20 行）
3. 链接到 docs/api/ 下的完整文档
4. 链接到迁移指南
保持原有其他部分不变。
人工环节：跑一遍 README 里的示例，确认可运行。
关键 Prompt 复盘
Prompt 1：源码扫描
用 Filesystem MCP 扫描 {dir}，列出所有 export，
输出表格：API 名 | 文件 | 行号 | 类型 | 签名
为什么有效：让 AI 先建全局视图，再逐个深入，避免遗漏。
Prompt 2：示例生成
基于 API 元信息生成 3 个示例：最简、常见、高级。
要求可运行、类型正确、有注释。
为什么有效：明确"可运行"约束，AI 会更保守、更准确。
Prompt 3：迁移指南分类
把 Breaking Changes 分类：删除/改名/参数/行为。
每类给迁移策略（旧 → 新）。
为什么有效：结构化分类让混乱的变更变可读，AI 比人更擅长这种归纳。
踩过的坑
坑 1：AI 把私有方法当公开 API
AI 扫描时把 _internalHelper 也列入了 API 清单
原因：它没区分 export 与未 export
解决：Prompt 明确"只列 export 的，下划线开头的私有不列"。
坑 2：示例代码编造参数
AI 示例：client.query("SELECT * FROM users", { timeout: 5000 })
真相：v3 的 query 第二参数是 params 数组，没有 timeout 选项
解决：示例生成前先把 API 完整签名喂给 AI，并要求"只能用签名中的参数"。
坑 3：迁移指南遗漏行为变更
AI 只抓了 commit 标题含 BREAKING 的，
但有些行为变更没标 BREAKING（开发者疏忽）
解决：补充 Prompt "对比 v2 与 v3 的测试用例，找出断言变化的"，测试比 commit message 更可信。
坑 4：文档语气不一致
30 个 API 文档由链式调用生成，
语气各异（有的正式有的随意）
解决：在 Step 3 的 system prompt 中固定文档模板与语气，并在末尾加一步统一润色。
坑 5：成本超预期
30 API × 3 步 × 平均 3000 token = 27 万 token
实际还多，因为每步都把源码塞进去
解决：用 Prompt 缓存 把"system + 源码"前缀缓存，成本降 70%。
效率对比
| 环节 | 传统 | AI 辅助 | 提速 |
|---|---|---|---|
| 源码扫描 | 半天 | 30 分钟 | 8x |
| API 文档（30 个） | 20 小时 | 2 小时 | 10x |
| 迁移指南 | 1 天 | 1 小时 | 8x |
| README | 半天 | 30 分钟 | 8x |
| 校对润色 | 已含 | 30 分钟 | - |
| 合计 | 约 5 天 | 4 小时 | 10x |
哪些环节 AI 真省时间
- ✅ 重复结构生成：30 个 API 文档结构一致，AI 批量出
- ✅ 代码理解：读源码提取签名，AI 比人快
- ✅ diff 归纳：从 200 个 commit 里筛 8 个 Breaking，AI 一遍过
哪些环节还得靠人
- ⚠️ 示例可运行性：AI 偶尔编参数，必须实际跑
- ⚠️ 迁移脚本：AI 给伪代码，可执行的 codemod 需人写
- ⚠️ FAQ：AI 不知道社区实际问什么，需补充真实问题
- ⚠️ 语气统一：批量生成容易风格漂移，需末尾统一润色
质量保障清单
发布前必查：
- 每个 API 签名与源码一致（类型、默认值）
- 每个示例实际运行通过
- 迁移指南的"旧 → 新"代码对比准确
- README 示例可运行
- 所有内部链接有效
- 无幻觉参数或方法
小结
这个案例最大的启示：技术写作的瓶颈不是"写"，而是"读代码 + 结构化"。AI 把读代码、提取信息、结构化这三件最耗时的事自动化了，人只需把关"准确性"和"可运行性"。
下次写文档前，别急着打开编辑器，先用 Filesystem MCP 让 AI 帮你扫一遍代码，你会立刻知道有多少 API、每个的签名是什么——这一步省下的时间，够你把所有示例都跑一遍了。