<!-- title: Claude Code自动化文档生成全实战 -->

## 概述

本教程聚焦如何用 Claude Code 构建一套"代码改了、文档自动更新"的自动化文档管线。覆盖 JSDoc/TSDoc 内联注释、README 生成、API 文档、架构决策记录（ADR）、Docusaurus 站点搭建，以及通过 Hooks + GitHub Actions 实现文档与代码同步的完整工作流。适合已有 Claude Code 使用经验、希望在团队中消除"文档永远过时"痛点的一线开发者和 Tech Lead。

## 前置条件

| 条件 | 说明 |
|------|------|
| Claude Code ≥ 1.0.40 | 支持 Hooks 和 `--print` 模式 |
| Node.js ≥ 18 | 运行 Docusaurus 和脚本 |
| 一个真实项目 | 推荐 TypeScript/Python 项目，含 ≥10 个源文件 |
| 基础 Git 操作 | 能创建分支、提交、推送 |
| GitHub 仓库（可选） | 用于 GitHub Actions 自动化 |

---

## 第一章：文档债务的根源与解决思路

### 1.1 为什么文档总过时

传统开发流程中，代码和文档是两条独立的管线：开发者写代码 → 代码合并 → 有人想起该更新文档 → 手动改 → 改错或忘改。核心矛盾是 **代码变更与文档更新之间存在时间差和人为依赖**。

Claude Code 解决这个问题的思路是：**把文档生成变成代码变更的副作用（side effect），而非独立任务**。

```mermaid
flowchart LR
    subgraph 传统流程
        A1[代码变更] --> A2[手动更新文档]
        A2 --> A3[文档过时]
    end
    subgraph 自动化流程
        B1[代码变更] --> B2[Git Hook 触发]
        B2 --> B3[Claude Code 生成文档]
        B3 --> B4[文档始终同步]
    end
```

### 1.2 五层文档体系

一个健康的项目需要五种文档，Claude Code 能自动生成全部：

| 层级 | 文档类型 | 受众 | 生成方式 |
|------|----------|------|----------|
| L1 | 内联注释（JSDoc/TSDoc/docstring） | 开发者 | Claude Code 直接写入源文件 |
| L2 | README.md | 所有人 | 根据项目结构自动生成 |
| L3 | API 文档（OpenAPI/Markdown） | 前后端协作 | 从路由/接口定义提取 |
| L4 | 架构决策记录（ADR） | 架构师/Tech Lead | 从代码结构推断 |
| L5 | 文档站点（Docusaurus/MkDocs） | 团队/外部用户 | 汇总 L2-L4 生成静态站点 |

---

## 第二章：L1 — 内联注释自动生成

### 2.1 精准 Prompt 策略

内联注释是文档体系的基石。直接要求"给代码加注释"效果往往很差——Claude Code 会写出冗余的、逐行翻译式的注释。关键在于精准的 Prompt 设计。

**错误示范：**
```
给这个文件所有函数加注释
```

**正确示范：**
```
为 src/services/ 下所有 exported 函数添加 JSDoc 注释。
要求：
1. 只对 exported 函数添加，忽略 internal 函数
2. 包含 @param、@returns、@throws
3. 每个函数至少一个 @example
4. 描述用祈使句（"Validate user input" 而非 "Validates user input"）
5. 不要描述代码实现细节，描述"做什么"和"为什么"
```

### 2.2 实战操作

假设项目结构如下：

```
src/
├── services/
│   ├── user.service.ts
│   ├── auth.service.ts
│   └── payment.service.ts
├── utils/
│   ├── validator.ts
│   └── formatter.ts
└── index.ts
```

在 Claude Code 终端中执行：

```bash
claude
```

进入对话后输入：

```
读取 src/services/ 下所有 .ts 文件，为每个 exported function 添加 JSDoc。
规则：
- @param 需含类型和说明
- @returns 描述返回值结构
- 异步函数标注 @returns Promise<...>
- 不修改任何业务逻辑代码
- 保持现有 import 不变
```

### 2.3 TSDoc（TypeScript 项目进阶）

对于 TypeScript 项目，TSDoc 比 JSDoc 更精确，因为它可以利用类型信息：

```
为 src/utils/validator.ts 中所有导出的类型守卫（type guard）函数添加 TSDoc 注释。
要求：
1. @param 使用 {TypeNode} 语法标注参数类型
2. @returns 使用布尔谓词描述（如 "true if input is a valid Email"）
3. 添加 @remarks 标注边界情况和限制
```

Claude Code 生成的结果示例：

```typescript
/**
 * Validates whether a string conforms to RFC 5322 email format.
 *
 * @param {string} input - The string to validate
 * @returns `true` if `input` matches the standard email pattern; otherwise `false`
 *
 * @remarks
 * This check uses a simplified regex and does not validate:
 * - Internationalized domain names (IDN)
 * - IP address literals in local part
 * - Comments in address
 *
 * @example
 * ```ts
 * isValidEmail("user@example.com"); // true
 * isValidEmail("not-an-email");     // false
 * ```
 */
export function isValidEmail(input: string): input is Email {
  return EMAIL_REGEX.test(input);
}
```

### 2.4 批量验证注释质量

生成注释后，运行一次质量检查：

```
扫描 src/ 目录下所有 .ts 文件，检查 exported 函数中：
1. 缺少 JSDoc/TSDoc 的函数（列出文件名:函数名）
2. @param 与函数签名参数不匹配的（列出差异）
3. @returns 缺失的异步函数
生成一份检查报告，不修改任何文件
```

---

## 第三章：L2 — README 自动生成与同步

### 3.1 结构化 README 生成

一个合格的 README 应包含以下模块，Claude Code 可以从代码库自动提取：

```markdown
# 项目名
> 一句话描述

## 快速开始
## 安装
## 配置
## 使用方法
## API 参考
## 开发指南
## 贡献指南
## License
```

在 Claude Code 中执行：

```
基于当前项目自动生成 README.md，要求：
1. 项目描述：从 package.json 的 name 和 description 提取
2. 快速开始：读取 package.json 的 scripts，提取 install/dev/build/test 命令
3. 配置：读取 .env.example 或 config/ 目录，列出所有配置项
4. 使用方法：从 src/index.ts 的导出接口生成用法示例
5. 开发指南：从 CONTRIBUTING.md 或现有工作流推断
6. 不要包含猜测性内容，只写能从代码确定的部分
7. 用中文撰写
```

### 3.2 README 同步策略

README 最大的问题是过时。解决方法是将 README 的关键段落标记为"自动生成区"：

```markdown
## 快速开始

<!-- AUTO-GENERATED:START:quickstart -->
安装依赖：
\`\`\`bash
npm install
\`\`\`

启动开发服务器：
\`\`\`bash
npm run dev
\`\`\`
<!-- AUTO-GENERATED:END:quickstart -->
```

然后在 CLAUDE.md 中配置持久指令：

```markdown
## 文档维护规则

当 package.json 的 scripts 发生变化时：
1. 更新 README.md 中 AUTO-GENERATED:START:quickstart 到 AUTO-GENERATED:END:quickstart 之间的内容
2. 只修改标记区域内的文本
3. 标记区域外的内容由开发者手动维护，不要修改
```

这样，Claude Code 在后续会话中看到 `package.json` 变更时，会自动更新 README 的对应区域。

---

## 第四章：L3 — API 文档自动生成

### 4.1 从 Express/Fastify 路由提取 API 文档

以 Express 项目为例，Claude Code 可以从路由定义直接生成 OpenAPI 3.0 规范：

```
扫描 src/routes/ 目录下所有路由文件，生成 OpenAPI 3.0 YAML 规范。
要求：
1. 从路由方法的 path 和 HTTP method 生成 endpoint 定义
2. 从 req.body 的 TypeScript interface 推断 request body schema
3. 从 res.json() 的返回值推断 response schema
4. 为每个 endpoint 生成 summary 和 description
5. 输出到 docs/openapi.yaml
```

### 4.2 从 API 文档生成客户端 SDK

生成的 OpenAPI 规范可以进一步让 Claude Code 生成客户端调用代码：

```
读取 docs/openapi.yaml，为每个 endpoint 生成一个 TypeScript 客户端函数。
要求：
1. 使用 fetch API，不用 axios
2. 每个函数有完整的 TypeScript 类型
3. 错误处理封装为统一的 ApiError 类
4. 输出到 src/client/api.ts
```

### 4.3 实战案例：REST API 文档全流程

假设有一个用户管理 API：

```
src/routes/
├── auth.routes.ts    # POST /auth/login, POST /auth/register
├── user.routes.ts    # GET /users, GET /users/:id, PATCH /users/:id
└── admin.routes.ts   # GET /admin/stats, GET /admin/users
```

执行命令序列：

**Step 1：提取接口定义**

```
分析 src/routes/ 目录，列出所有 HTTP endpoint。
对每个 endpoint：
- HTTP 方法和路径
- 请求参数（query/path/body）
- 响应格式（从 res.json() 调用推断）
- 认证要求（从中间件推断）
以 Markdown 表格输出，不修改任何文件
```

**Step 2：生成 OpenAPI 规范**

```
根据上一步的分析结果，生成完整的 OpenAPI 3.0.3 YAML 规范。
包含：
- info（标题、版本、描述）
- servers（开发环境 URL）
- paths（所有 endpoint 的完整定义）
- components/schemas（复用的数据模型）
- securitySchemes（Bearer JWT）
输出到 docs/api/openapi.yaml
```

**Step 3：生成 Markdown API 文档**

```
读取 docs/api/openapi.yaml，为每个 endpoint 生成 Markdown 文档。
格式：
- 标题：HTTP 方法 + 路径
- 描述
- 请求参数表格
- 请求示例（curl 命令）
- 响应示例（JSON）
- 错误码说明
输出到 docs/api/endpoints/ 目录，每个 endpoint 一个文件
```

---

## 第五章：L4 — 架构决策记录（ADR）

### 5.1 什么是 ADR

ADR（Architecture Decision Record）是一种轻量级的文档格式，记录每个重要技术决策的上下文、选择和后果。格式通常为：

```markdown
# ADR-001: 选择 PostgreSQL 作为主数据库

## 状态
已接受

## 上下文
系统需要存储用户数据、订单数据和支付记录...

## 决策
使用 PostgreSQL 14.x 作为主数据库...

## 后果
- 正面：ACID 事务、JSON 支持、成熟生态
- 负面：需要 DBA 运维、水平扩展需要额外方案
```

### 5.2 用 Claude Code 自动生成 ADR

```
分析当前项目的技术栈和架构选择，为每个重要技术决策生成 ADR。
检查以下位置获取决策上下文：
1. package.json 的 dependencies
2. CLAUDE.md 中的项目说明
3. config/ 目录的配置文件
4. docker-compose.yml（如有）
5. infra/ 或 terraform/ 目录（如有）

为每个发现的技术决策生成 ADR，格式：
- ADR-XXX: 标题
- 状态：已接受/已废弃/已替代
- 上下文：为什么需要做这个决策
- 决策：选择了什么
- 后果：正面和负面影响

输出到 docs/adr/ 目录
```

### 5.3 持续更新 ADR

当项目引入新技术或替换组件时，在 CLAUDE.md 中配置：

```markdown
## ADR 维护规则

当以下文件发生变化时，检查是否需要新增或更新 ADR：
1. package.json 新增/移除 dependency
2. docker-compose.yml 新增/修改服务
3. infra/ 目录新增/修改配置

如果需要更新：
1. 创建新的 ADR（如果决策改变了）
2. 将旧 ADR 状态改为"已替代"，指向新 ADR
3. 不要删除旧 ADR
```

---

## 第六章：L5 — 文档站点自动构建

### 6.1 使用 Docusaurus 搭建文档站

```
在当前项目中初始化 Docusaurus 文档站点。
要求：
1. 安装到 docs-site/ 目录，不污染主项目
2. 配置中文语言支持
3. 从项目 README.md 生成首页
4. 从 docs/api/endpoints/ 生成 API 参考文档侧边栏
5. 从 docs/adr/ 生成架构决策侧边栏
6. 配置 navbar 包含：首页、API 文档、架构决策、GitHub 链接
```

### 6.2 自动同步脚本

创建 `scripts/sync-docs.sh`，在每次 CI 构建时运行：

```bash
#!/bin/bash
# 文档同步脚本 - 在 CI/CD 中运行

set -e

echo "=== 文档同步开始 ==="

# 1. 同步 README 到 Docusaurus 首页
cp README.md docs-site/docs/intro.md

# 2. 同步 API 文档
if [ -d "docs/api/endpoints" ]; then
  cp -r docs/api/endpoints/* docs-site/docs/api/
fi

# 3. 同步 ADR
if [ -d "docs/adr" ]; then
  cp -r docs/adr/* docs-site/docs/adr/
fi

# 4. 更新侧边栏配置
npx docusaurus write-heading-ids docs-site/docs

echo "=== 文档同步完成 ==="
```

### 6.3 使用 Claude Code 的 `--print` 模式实现全自动文档更新

将文档更新集成到开发工作流中，创建脚本 `scripts/update-docs.sh`：

```bash
#!/bin/bash
# 使用 Claude Code headless 模式自动更新文档

# 获取本次提交涉及的文件
CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD)

# 检查是否需要更新文档
NEEDS_API_DOC=false
NEEDS_README=false
NEEDS_ADR=false

for file in $CHANGED_FILES; do
  if [[ "$file" == src/routes/* ]]; then
    NEEDS_API_DOC=true
  fi
  if [[ "$file" == package.json ]] || [[ "$file" == README.md ]]; then
    NEEDS_README=true
  fi
  if [[ "$file" == package.json ]] || [[ "$file" == docker-compose.yml ]]; then
    NEEDS_ADR=true
  fi
done

# 按需更新文档
if [ "$NEEDS_API_DOC" = true ]; then
  echo "更新 API 文档..."
  claude --print "分析 src/routes/ 目录的最新变更，更新 docs/api/ 下的对应文档。只更新受影响的 endpoint 文档。"
fi

if [ "$NEEDS_README" = true ]; then
  echo "更新 README..."
  claude --print "更新 README.md 中 AUTO-GENERATED 标记区域的内容，反映 package.json 的最新 scripts 和 dependencies。"
fi

if [ "$NEEDS_ADR" = true ]; then
  echo "检查是否需要新增 ADR..."
  claude --print "比较 package.json 最近的变更，如果新增或移除了重要依赖，在 docs/adr/ 创建相应的 ADR。"
fi
```

---

## 第七章：Hooks 驱动的文档自动化

### 7.1 配置 Post-Commit Hook

在 `.claude/settings.json` 中配置 Hook，让代码提交自动触发文档更新：

```json
{
  "hooks": {
    "PostCommit": [
      {
        "matcher": "",
        "command": "bash .claude/hooks/post-commit-docs.sh",
        "description": "代码提交后自动更新受影响的文档"
      }
    ]
  }
}
```

创建 `.claude/hooks/post-commit-docs.sh`：

```bash
#!/bin/bash
# Post-commit 文档更新 Hook

CHANGED=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || echo "")

# 路由变更 → 更新 API 文档
if echo "$CHANGED" | grep -q "src/routes/"; then
  claude --print "更新 docs/api/ 中受影响 endpoint 的 Markdown 文档，反映 src/routes/ 中的最新变更。" >> .claude/logs/doc-update.log 2>&1 &
fi

# package.json 变更 → 更新 README
if echo "$CHANGED" | grep -q "package.json"; then
  claude --print "更新 README.md 中 AUTO-GENERATED 标记区域的内容。" >> .claude/logs/doc-update.log 2>&1 &
fi

# 新增配置 → 检查 ADR
if echo "$CHANGED" | grep -qE "(docker-compose|terraform|config/)"; then
  claude --print "检查 docs/adr/ 是否需要新增架构决策记录。" >> .claude/logs/doc-update.log 2>&1 &
fi

echo "[$(date)] Post-commit doc hook executed for: $CHANGED" >> .claude/logs/doc-update.log
```

### 7.2 Pre-Push Hook：文档完整性检查

在代码推送前，确保文档没有被遗漏：

```json
{
  "hooks": {
    "PrePush": [
      {
        "matcher": "",
        "command": "bash .claude/hooks/pre-push-doc-check.sh",
        "description": "推送前检查文档完整性"
      }
    ]
  }
}
```

`pre-push-doc-check.sh` 脚本：

```bash
#!/bin/bash
# Pre-push 文档完整性检查

ERRORS=()

# 检查：所有 exported 函数有 JSDoc
MISSING_JSDOC=$(claude --print "扫描 src/ 目录，列出所有缺少 JSDoc 注释的 exported 函数。只输出文件名:函数名列表，每行一个。如果没有缺失，输出 NONE。")

if [ "$MISSING_JSDOC" != "NONE" ]; then
  ERRORS+=("以下 exported 函数缺少 JSDoc:\n$MISSING_JSDOC")
fi

# 检查：API 路由有对应文档
MISSING_API_DOC=$(claude --print "比较 src/routes/ 中的 endpoint 列表和 docs/api/endpoints/ 中的文档文件。列出没有对应文档的 endpoint。如果没有缺失，输出 NONE。")

if [ "$MISSING_API_DOC" != "NONE" ]; then
  ERRORS+=("以下 API endpoint 缺少文档:\n$MISSING_API_DOC")
fi

# 如果有错误，阻止推送
if [ ${#ERRORS[@]} -gt 0 ]; then
  echo "❌ 文档完整性检查失败："
  for err in "${ERRORS[@]}"; do
    echo -e "$err"
  done
  echo ""
  echo "运行 'claude' 修复文档缺失问题后再推送。"
  exit 1
fi

echo "✅ 文档完整性检查通过"
exit 0
```

---

## 第八章：GitHub Actions 全自动文档管线

### 8.1 完整 CI/CD 配置

创建 `.github/workflows/docs.yml`：

```yaml
name: Documentation Pipeline

on:
  pull_request:
    paths:
      - 'src/**'
      - 'package.json'
      - 'docs/**'
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'package.json'

jobs:
  check-docs:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            检查本次 PR 涉及的代码变更，确认：
            1. 新增的 exported 函数是否有 JSDoc 注释
            2. 修改的 API endpoint 是否有对应的文档更新
            3. README.md 中的 AUTO-GENERATED 区域是否已更新
            如果发现问题，在 PR 中添加 review comment 指出具体位置。

  update-docs:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            根据 main 分支的最新变更，自动更新以下文档：
            1. 受影响文件的 JSDoc 注释
            2. docs/api/ 中的 API 文档
            3. README.md 的 AUTO-GENERATED 区域
            4. 如有架构变更，创建新 ADR
            所有变更直接提交到 docs/auto-update 分支。

      - name: Create PR for doc updates
        run: |
          if git diff --quiet; then
            echo "No doc changes needed"
            exit 0
          fi
          git checkout -b docs/auto-update-$(date +%Y%m%d-%H%M%S)
          git add docs/ README.md
          git commit -m "docs: auto-update documentation [skip ci]"
          git push origin HEAD
          gh pr create \
            --title "docs: automated documentation update" \
            --body "Auto-generated documentation updates based on recent code changes." \
            --label documentation
```

### 8.2 工作流程总览

```mermaid
flowchart TB
    subgraph 开发者
        A[编写代码] --> B[git commit]
        B --> C[git push]
    end

    subgraph Hook 层
        B --> D[Post-Commit Hook]
        D --> E{路由变更?}
        E -->|是| F[更新 API 文档]
        E -->|否| G{pkg 变更?}
        G -->|是| H[更新 README]
        G -->|否| I[跳过]
    end

    subgraph CI/CD 层
        C --> J[GitHub Actions 触发]
        J --> K{PR or Push?}
        K -->|PR| L[文档完整性检查]
        L --> M[PR Comment 反馈]
        K -->|Push to main| N[自动更新文档]
        N --> O[创建 Docs PR]
        O --> P[人工审核 → 合并]
    end

    subgraph 文档站点
        P --> Q[触发 Docusaurus 构建]
        Q --> R[部署文档站点]
    end

    style A fill:#4CAF50,color:white
    style R fill:#2196F3,color:white
```

---

## 第九章：实战案例——为真实项目构建文档自动化

### 9.1 项目背景

假设有一个 Express + TypeScript 的电商后端项目：

```
ecommerce-api/
├── src/
│   ├── routes/
│   │   ├── product.routes.ts
│   │   ├── order.routes.ts
│   │   └── auth.routes.ts
│   ├── services/
│   │   ├── product.service.ts
│   │   ├── order.service.ts
│   │   └── stripe.service.ts
│   ├── models/
│   │   ├── Product.ts
│   │   ├── Order.ts
│   │   └── User.ts
│   ├── middleware/
│   │   ├── auth.ts
│   │   └── validator.ts
│   └── index.ts
├── package.json
├── tsconfig.json
└── CLAUDE.md
```

### 9.2 一次性全量文档生成

在 Claude Code 中执行一个综合 Prompt：

```
对当前项目执行完整的文档生成，按以下顺序：

第一步：内联注释
- 为 src/services/ 和 src/middleware/ 中所有 exported 函数添加 JSDoc
- 包含 @param, @returns, @throws, @example
- 不修改业务逻辑

第二步：API 文档
- 分析 src/routes/ 的所有路由定义
- 生成 OpenAPI 3.0 规范到 docs/api/openapi.yaml
- 为每个 endpoint 生成独立的 Markdown 文档到 docs/api/endpoints/

第三步：架构文档
- 生成 docs/architecture.md，描述：
  - 系统架构图（用 Mermaid）
  - 数据流（Request → Middleware → Service → Model → Response）
  - 认证流程
  - 错误处理策略

第四步：README
- 生成完整的 README.md
- 包含安装、配置、开发、部署、API 概览等章节

第五步：ADR
- 为当前使用的技术栈决策各生成一条 ADR
- 输出到 docs/adr/

每步完成后汇报新增和修改了哪些文件。
```

### 9.3 预期结果

执行完成后，项目结构变为：

```
ecommerce-api/
├── src/                          # 源码（已添加 JSDoc）
├── docs/
│   ├── api/
│   │   ├── openapi.yaml          # OpenAPI 3.0 规范
│   │   └── endpoints/
│   │       ├── product-api.md
│   │       ├── order-api.md
│   │       └── auth-api.md
│   ├── adr/
│   │   ├── 001-express-framework.md
│   │   ├── 002-stripe-payment.md
│   │   └── 003-jwt-authentication.md
│   └── architecture.md           # 含 Mermaid 架构图
├── README.md                     # 完整 README
├── CLAUDE.md                     # 包含文档维护规则
└── .claude/
    ├── settings.json             # 包含 Hooks 配置
    └── hooks/
        ├── post-commit-docs.sh
        └── pre-push-doc-check.sh
```

### 9.4 验证文档质量

运行以下 Prompt 进行自检：

```
执行文档质量审计：
1. 检查所有 exported 函数的 JSDoc 完整性（@param 是否匹配、@returns 是否存在）
2. 验证 OpenAPI 规范是否与实际路由一致（URL、方法、参数）
3. 检查 README 的安装命令是否与 package.json 一致
4. 验证 ADR 是否覆盖了所有主要技术决策
5. 检查架构图是否与实际代码结构匹配

输出一份审计报告，按严重程度排序：
- 🔴 错误（文档与代码不一致）
- 🟡 警告（文档缺失但不影响使用）
- 🟢 建议（可改进的文档质量点）
```

---

## 第十章：进阶技巧与常见问题

### 10.1 文档碎片化治理

当项目文档分散在多个目录时，用 Claude Code 生成一份文档索引：

```
扫描 docs/ 目录下所有 .md 文件，生成一份文档导航索引 docs/SUMMARY.md。
格式为树状目录，每个文档条目包含：
- 文件路径（相对于 docs/）
- 一句话摘要（从文件第一段提取）
- 最后更新日期（从 git log 获取）
```

### 10.2 多语言文档

对于需要中英双语的项目：

```
读取所有 docs/ 下的中文文档，为每个文档生成英文版本。
规则：
1. 保存为 docs/en/ 同名文件
2. 代码示例和技术术语不翻译
3. Docusaurus 配置 i18n 支持中英切换
```

### 10.3 文档生成性能优化

大型项目文档生成可能耗时较长，优化策略：

| 策略 | 实现方式 | 适用场景 |
|------|----------|----------|
| 增量更新 | 只处理 git diff 涉及的文件 | 日常开发 |
| 并行生成 | 多个 Claude Code 实例分别处理不同模块 | 全量生成 |
| 缓存利用 | 将已生成文档作为上下文避免重复分析 | 反复更新 |
| 分层处理 | 先生成 L1 内联注释，再基于注释生成上层文档 | 从零开始 |

增量更新的 Prompt 模板：

```
本次代码变更涉及以下文件：
$(git diff --name-only HEAD~1 HEAD)

只更新受这些文件影响的文档：
1. 检查这些文件中的 exported 函数，更新 JSDoc
2. 如果涉及路由变更，只更新对应 endpoint 的 API 文档
3. 如果涉及新依赖，考虑是否需要新增 ADR
不要处理与本次变更无关的文档
```

### 10.4 常见问题与解决方案

**Q1：Claude Code 生成的 JSDoc 参数类型与实际不一致**

```
解决方案：在 Prompt 中强调"从函数签名提取参数类型，不要推断"。
如果使用 TypeScript，让 Claude Code 直接读取类型定义而非猜测。
```

**Q2：文档生成时修改了不该改的代码**

```
解决方案：在 CLAUDE.md 中明确标记不可修改的文件：
## 禁止修改的文件
- src/**/*.test.ts
- src/config/production.ts
- .env

同时使用 AUTO-GENERATED 标记控制 README 的修改范围。
```

**Q3：OpenAPI 规范生成的 Schema 不够精确**

```
解决方案：让 Claude Code 先读取 TypeScript Model 定义，
再生成 Schema。Prompt 示例：
"先读取 src/models/ 下所有 Model 文件的 TypeScript interface 定义，
然后基于这些类型生成 OpenAPI Schema，确保字段类型和必填项完全一致。"
```

**Q4：Hooks 中 Claude Code 执行超时**

```
解决方案：将耗时操作改为异步执行（后台运行）。
在 hook 脚本中使用 & 将 claude --print 放到后台，
并写入日志文件供事后检查：
claude --print "更新文档..." >> .claude/logs/doc-update.log 2>&1 &
```

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适用训练营类型** | AI编程实战营、DevOps工程训练营、全栈开发进阶营 |
| **预计教学时长** | 3-4 小时（含实操练习） |
| **难度等级** | 中级（需要 Claude Code 基础使用经验） |
| **学员前置要求** | 会用 Claude Code 完成基本编码任务、了解 Git 工作流 |
| **推荐课程结构** | 第一章（讲解15分钟）→ 第二至五章（实操90分钟）→ 第六至八章（实操60分钟）→ 第九章综合练习（45分钟）→ 第十章答疑（30分钟） |
| **硬件要求** | 每人一台已安装 Claude Code 的电脑，能访问 GitHub |
| **助教配比** | 建议 1:8，文档自动化涉及多个工具链配合 |

---

## 参考来源

1. [How to Auto-Generate Documentation with Claude Code](https://claudecode-lab.com/en/blog/claude-code-documentation-generation/) — Claude Code 文档生成的完整方法与 Prompt 模板
2. [Documentation Generation with Claude Code | Developer Toolkit](https://developertoolkit.ai/en/claude-code/lessons/documentation/) — 涵盖 JSDoc/TSDoc 生成技巧和文档维护策略
3. [How to Write Documentation with Claude Code | Beam](https://getbeam.dev/blog/claude-code-documentation.html) — 从 README 到 API 文档的实战教程
4. [Automated Documentation with Claude Code: Building Self-Updating Docs Using Docusaurus](https://medium.com/@dan.avila7/automated-documentation-with-claude-code-building-self-updating-docs-using-docusaurus-agent-2c85d3ec0e19) — Docusaurus 集成的端到端方案
5. [Documentation-Driven Development Workflow with Claude Code](https://dev.to/quochuydev/how-i-built-a-documentation-driven-development-workflow-with-claude-code-1cbb) — 文档驱动开发工作流实践

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)