第 16 期 | 日常文档全自动生成流水线
🎯 学习目标
学完本期你将掌握：
- 如何让 Claude Code 自动基于源码生成 API 文档
- Print Mode 批量生成周报、迭代日志和 CHANGELOG
- Git 驱动的自动化文档更新流程
- 文档即代码 (Docs-as-Code) 的实践方法
📖 核心概念讲解
16.1 文档的痛点：写了不更新，更新了不写
开发者的文档困境:
README 写了 → 三个月没更新 → 新人照着做全错
API 文档写了 → 加了 5 个接口没同步 → 客户报 Bug
周报要写 → 每周五花 30 分钟 → 复制粘贴上周的
解决方案: 让代码自己写文档，让 Git 自己写周报
16.2 文档自动化的三种模式
模式 1: 源码 → 文档
读取代码注释和类型定义
→ 自动生成 API Reference
适合: API 文档、SDK 文档、组件文档
模式 2: Git → 文档
读取 git log / PR / Issues
→ 自动生成 CHANGELOG、周报
适合: 迭代日志、团队周报、发版说明
模式 3: 混合模式
源码 + Git + 配置文件
→ 生成完整的项目文档站
适合: README、Onboarding Guide
💻 模拟 Claude TUI 交互
场景 1：自动生成 API 文档
> 读取 src/routes/ 下所有路由文件，
自动生成一份完整的 API 文档
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ 🔍 Tool: Glob → src/routes/**/*.ts │
│ 找到 12 个路由文件 │
│ │
│ 🔍 Tool: Read → (逐个读取) │
│ │
│ ⚙️ Tool: Write → docs/api-reference.md │
│ │
│ ✅ API 文档已生成！共发现 34 个端点: │
│ │
│ ### 用户模块 (8 个端点) │
│ | 方法 | 路径 | 说明 | │
│ |--------|---------------|-------------| │
│ | GET | /api/users | 用户列表 | │
│ | POST | /api/users | 创建用户 | │
│ | GET | /api/users/:id | 用户详情 | │
│ | PUT | /api/users/:id | 更新用户 | │
│ | DELETE | /api/users/:id | 删除用户 | │
│ | ... | │
│ │
│ 每个端点都包含: │
│ - 请求参数 (从 TypeScript 类型推断) │
│ - 响应格式 (从 return 语句推断) │
│ - 认证要求 (从中间件推断) │
│ - 示例 curl 命令 │
│ │
╰──────────────────────────────────────────────────────╯
场景 2：Git 驱动的自动周报
> 根据本周的 git log 生成周报
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ ⚙️ Tool: Bash │
│ $ git log --since="7 days ago" --oneline │
│ --format="%h %s (%an)" │
│ │
│ 📋 本周开发周报 (2024.03.18 - 2024.03.22): │
│ │
│ ## ✅ 已完成 │
│ - **用户模块**: 完成注册流程优化 (#234) │
│ - **支付系统**: 接入 Stripe 支付 (#241) │
│ - **性能优化**: 首页加载时间降低 40% │
│ │
│ ## 📊 数据概览 │
│ - 本周提交: 47 次 │
│ - 涉及文件: 82 个 │
│ - 新增代码: 2,340 行 / 删除: 890 行 │
│ - PR 合并: 8 个 │
│ │
│ ## 🔜 下周计划 │
│ (基于 open issues 推断): │
│ - #245: 订单导出功能 │
│ - #248: 移动端适配 │
│ │
╰──────────────────────────────────────────────────────╯
💻 代码演示
# ✅ 从源码生成 API 文档
claude -p "读取 src/routes/ 下所有文件，
生成 Markdown 格式的 API 文档到 docs/api.md"
# ✅ 自动生成 CHANGELOG
claude -p "基于 git log --since='last month'
生成 CHANGELOG.md，按功能分类"
# ✅ 周报生成
claude -p "根据本周 git log 和 closed issues，
用中文写一份项目周报"
# ✅ README 自动更新
claude "基于当前项目实际的文件结构和 package.json，
更新 README.md 中的安装说明和项目结构图"
# ✅ 组件文档
claude "扫描 src/components/ 下所有 React 组件，
为每个组件生成 Props 文档和用法示例"
Git Hook 自动化文档更新
# 在 .git/hooks/pre-commit 中加入自动文档更新
#!/bin/bash
# 如果路由文件有变动，自动更新 API 文档
if git diff --cached --name-only | grep "src/routes/"; then
claude -p "src/routes/ 有变动，
请更新 docs/api.md" --allowedTools Read,Write
fi
🔧 涉及的 Tools
| 工具 | 文档生成阶段 | 作用 |
|---|---|---|
Glob |
发现 | 扫描源文件目录 |
Read |
解析 | 读取代码和注释 |
Bash |
Git 查询 | 获取 commit/PR/issue 数据 |
Write |
输出 | 生成 Markdown 文档 |
Edit |
更新 | 增量更新已有文档 |
📝 本期要点回顾
- 源码即文档：让 Claude 从代码中自动提取文档
- Git 即周报：从 commit log 自动生成报告
- 用 Print Mode (
claude -p) 适合批量文档生成任务 - 用 Git Hooks 可以实现文档的自动同步更新
- 文档生成是 PM 和开发者都能受益的高 ROI 场景