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

给这个文件所有函数加注释

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

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

claude

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

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

/**
 * 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("[email protected]"); // true
 * isValidEmail("not-an-email");     // false
 * ```
 */
export function isValidEmail(input: string): input is Email {
  return EMAIL_REGEX.test(input);
}

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

# 项目名
> 一句话描述

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

基于当前项目自动生成 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. 用中文撰写

## 快速开始

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

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

## 文档维护规则

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

扫描 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

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

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

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

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

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

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

## 状态
已接受

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

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

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

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

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

输出到 docs/adr/ 目录

## ADR 维护规则

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

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

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

#!/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 "=== 文档同步完成 ==="

#!/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": {
    "PostCommit": [
      {
        "matcher": "",
        "command": "bash .claude/hooks/post-commit-docs.sh",
        "description": "代码提交后自动更新受影响的文档"
      }
    ]
  }
}

#!/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

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

#!/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

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

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

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

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

第一步：内联注释
- 为 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/

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

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

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

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

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

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

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

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

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

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

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

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

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