<!-- title: Claude Code CI/CD与定时调度生产实战 -->

# Claude Code CI/CD集成与定时调度生产实战

## 概述

本教程面向希望在**团队级和生产线**中部署Claude Code的中高级开发者。你将学会：将Claude Code嵌入GitHub Actions实现自动化代码审查与PR修复；用`/loop`和CronCreate构建自主巡检Agent；通过`--continue`/`--resume`管理长时间会话；以及在生产环境中控制成本与权限。学完后，你能在真实CI/CD流水线中稳定运行Claude Code，并让它在无人工干预的情况下持续完成代码质量保障任务。

**适用人群**：已熟悉Claude Code基础操作，有CI/CD经验，希望将AI编码助手从"个人工具"升级为"团队基础设施"的开发者。

---

## 前置条件

| 条件 | 说明 |
|------|------|
| Claude Code ≥ v2.1.72 | `claude --version` 检查，定时任务需要此版本以上 |
| GitHub仓库 | 用于GitHub Actions集成 |
| Anthropic API Key | 存储为GitHub Secret或环境变量 |
| 基础CI/CD知识 | 了解YAML、GitHub Actions Workflow语法 |
| Claude Code基础操作 | 已完成至少一个交互式会话 |

---

## 第一章：Headless模式 — Claude Code的"无人驾驶"基础

### 1.1 什么是Headless模式

Headless模式是Claude Code脱离交互式终端、以纯命令行方式运行的模式。核心标志是`-p`（`--print`）参数：

```bash
# 最基本的headless调用
claude -p "解释当前项目的目录结构"

# 管道输入：将文件内容传给Claude
cat src/main.py | claude -p "Review this code for security issues"

# 将多个文件作为上下文
claude -p "检查以下文件的一致性" <(cat src/a.ts) <(cat src/b.ts)
```

Headless模式的核心特性：

- **无交互**：不启动REPL，不会等待用户输入
- **输出到stdout**：结果直接打印到标准输出，方便管道串联
- **退出码语义化**：成功返回0，失败返回非0，可直接用于CI条件判断
- **支持JSON输出**：`--output-format json` 返回结构化数据

### 1.2 关键CLI参数一览

```bash
# 限制Agent轮次，防止失控
claude -p "重构这个函数" --max-turns 5

# 限制可用工具，最小权限原则
claude -p "读取并分析日志" --allowedTools "Read,Glob,Grep"

# 指定模型（成本优化）
claude -p "简单格式化" --model claude-sonnet-4-6
claude -p "复杂架构分析" --model claude-opus-4-8

# JSON格式输出，便于脚本解析
claude -p "列出所有TODO注释" --output-format json

# 流式JSON，实时获取进度
claude -p "运行测试并修复失败" --output-format stream-json

# 指定系统提示
claude -p "审查PR" --system-prompt "你是一个安全审计专家，只关注安全问题"
```

### 1.3 会话管理：`--continue` 与 `--resume`

```bash
# 继续最近的会话（保留完整上下文）
claude --continue

# 继续最近的会话并追加新指令
claude --continue -p "现在请运行测试"

# 恢复特定会话（通过会话ID）
claude --resume <session-id>

# 恢复会话并追加指令
claude --resume <session-id> -p "请检查刚才的修改是否引入了新的lint错误"

# 查看所有历史会话
claude --resume  # 不带ID会列出所有会话供选择
```

**典型场景**：在CI中先让Claude分析代码，然后resume同一会话执行修复：

```bash
# Step 1: 分析阶段
SESSION_ID=$(claude -p "分析这个PR的变更，列出需要修复的问题" \
  --output-format json | jq -r '.session_id')

# Step 2: 修复阶段（复用上下文）
claude --resume $SESSION_ID -p "请逐一修复你刚才发现的问题"

# Step 3: 验证阶段
claude --resume $SESSION_ID -p "运行完整测试套件，确认所有修复都通过"
```

### 1.4 实战：本地批量文件处理脚本

```bash
#!/bin/bash
# batch-review.sh — 批量审查所有修改过的TypeScript文件
set -e

# 获取所有修改的文件
CHANGED_FILES=$(git diff --name-only origin/main...HEAD -- '*.ts' '*.tsx')

if [ -z "$CHANGED_FILES" ]; then
  echo "没有需要审查的TypeScript文件"
  exit 0
fi

echo "=== 开始审查以下文件 ==="
echo "$CHANGED_FILES"

# 逐文件审查
for file in $CHANGED_FILES; do
  echo "\n--- 审查: $file ---"
  claude -p "作为代码审查员，检查以下文件的：1) 类型安全 2) 错误处理 3) 性能问题。给出简洁的改进建议。" \
    --max-turns 2 \
    --allowedTools "Read,Glob,Grep" \
    < "$file"
done

echo "\n=== 批量审查完成 ==="
```

```mermaid
flowchart TD
    A[git diff 获取变更文件列表] --> B{有变更文件?}
    B -->|否| C[退出：无需审查]
    B -->|是| D[遍历每个文件]
    D --> E[claude -p 审查单个文件]
    E --> F[输出审查结果]
    F --> G{还有更多文件?}
    G -->|是| D
    G -->|否| H[汇总输出完成]
```

---

## 第二章：GitHub Actions集成 — 团队级自动化

### 2.1 官方 claude-code-action

Anthropic 提供了官方的 GitHub Action（`anthropics/claude-code-action`），支持在PR和Issue中通过`@claude`触发AI操作。

**基础配置**：

```yaml
# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    permissions:
      contents: write        # 允许创建commit
      pull-requests: write   # 允许PR评论
      issues: write          # 允许Issue评论

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0     # 完整历史，提供更好的上下文

      - name: Claude Code Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # 触发方式：PR中评论 @claude
          trigger_phrase: "@claude"
          # 允许的操作
          allowed_tools: "Read,Write,Edit,Bash,Glob,Grep"
          # 最大轮次限制
          max_turns: 10
```

### 2.2 自动PR审查（无需手动触发）

```yaml
# .github/workflows/auto-review.yml
name: Auto PR Review

on:
  pull_request:
    types: [opened, synchronize, ready_for_review]

jobs:
  auto-review:
    runs-on: ubuntu-latest
    if: "!github.event.pull_request.draft"
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed
        run: |
          FILES=$(git diff --name-only origin/main...HEAD)
          DIFF=$(git diff origin/main...HEAD)
          echo "files<<EOF" >> $GITHUB_OUTPUT
          echo "$FILES" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

      - name: Run Claude Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          REVIEW=$(claude -p "
          你是一名资深代码审查员。请审查这个PR的变更，关注以下方面：

          1. **安全漏洞**：SQL注入、XSS、硬编码密钥
          2. **逻辑错误**：边界条件、空指针、竞态条件
          3. **性能问题**：N+1查询、内存泄漏、不必要的重渲染
          4. **代码规范**：命名一致性、注释充分性

          变更的文件：
          ${{ steps.changed.outputs.files }}

          请用中文给出结构化的审查意见。
          " \
          --max-turns 3 \
          --allowedTools "Read,Glob,Grep,Bash" \
          --output-format json)

          # 提取审查内容并发布为PR评论
          echo "$REVIEW" | jq -r '.result' > review_comment.md
          
          # 使用gh CLI发布评论
          gh pr comment ${{ github.event.pull_request.number }} \
            --body-file review_comment.md
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

### 2.3 自动修复Lint错误

```yaml
# .github/workflows/auto-fix-lint.yml
name: Auto Fix Lint

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  auto-fix:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - name: Install dependencies
        run: npm ci

      - name: Run linter and capture errors
        id: lint
        run: |
          npx eslint . --format json > eslint_result.json 2>/dev/null || true
          ERROR_COUNT=$(jq '. | length' eslint_result.json)
          echo "error_count=$ERROR_COUNT" >> $GITHUB_OUTPUT

      - name: Auto-fix with Claude
        if: steps.lint.outputs.error_count > 0
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "
          以下是ESLint的检查结果（JSON格式）。
          请逐个修复所有可以自动修复的问题。
          修复后不要改变代码的业务逻辑。

          ESLint结果：
          $(cat eslint_result.json)
          " \
          --max-turns 15 \
          --allowedTools "Read,Write,Edit,Bash,Glob,Grep"

      - name: Verify fixes
        run: |
          npx eslint . --max-warnings 0 || {
            echo "仍有lint错误，请人工检查"
            exit 1
          }

      - name: Commit fixes
        run: |
          git config user.name "Claude Code [bot]"
          git config user.email "claude-code[bot]@users.noreply.github.com"
          git add -A
          git diff --cached --quiet || git commit -m "fix: auto-fix lint errors by Claude Code"
          git push
```

### 2.4 安全配置清单

```yaml
# 生产环境必须的安全设置
env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}  # 永远不要硬编码
  
# 权限最小化
permissions:
  contents: read          # 默认只读，写权限按需开启
  pull-requests: read     # 按需提升

# 成本控制
# --max-turns: 限制每个任务的Agent轮次
# --allowedTools: 限制可用工具集
# --model: 复杂任务用Opus，简单任务用Sonnet
```

```mermaid
flowchart LR
    subgraph "触发方式"
        A1[PR opened/sync]
        A2["@claude 评论触发"]
        A3[定时调度 cron]
    end

    subgraph "Claude Code Action"
        B1[检出代码]
        B2[获取变更差异]
        B3[构造审查Prompt]
        B4[调用Claude API]
        B5[解析结果]
    end

    subgraph "输出动作"
        C1[PR评论]
        C2[自动Commit修复]
        C3[Label标记]
        C4[检查状态更新]
    end

    A1 --> B1
    A2 --> B1
    A3 --> B1
    B1 --> B2 --> B3 --> B4 --> B5
    B5 --> C1
    B5 --> C2
    B5 --> C3
    B5 --> C4
```

---

## 第三章：/loop与定时调度 — 自主运行Agent

### 3.1 /loop命令基础

`/loop`是Claude Code v2.1.72+引入的内置调度器，让Claude在会话内按计划重复执行任务。

```bash
# 在Claude Code交互式会话中
# 基本用法：每10分钟运行一次
/loop 10m 检查是否有新的GitHub Issue需要处理

# 指定具体间隔
/loop 5m 监控测试套件状态，如果失败请尝试修复
/loop 30m 检查依赖是否有安全更新
/loop 1h 运行代码质量检查并生成报告
```

### 3.2 CronCreate：精确的定时调度

在Claude Code会话中，Claude可以使用`CronCreate`工具创建更精确的定时任务：

**示例对话**：

```
用户：每天早上9点检查昨天的CI失败记录，分析失败原因并更新到Notion

Claude：（内部调用CronCreate工具）
✓ 已创建定时任务
  - 调度：57 8 * * *（每天早上8:57）
  - 内容：检查昨天GitHub Actions的失败记录，分析根因，更新到Notion
  - 持续性：durable（会话重启后仍有效）
  - 过期：7天后自动停止
```

**一次性提醒**：

```
用户：今天下午3点提醒我检查部署状态

Claude：（创建一次性定时任务）
✓ 已创建一次性提醒
  - 触发时间：今天 15:00
  - 内容：检查生产环境部署状态
  - 触发后自动删除
```

### 3.3 Durable vs Session-Only

| 特性 | Session-Only（默认） | Durable |
|------|---------------------|---------|
| 生命周期 | 随Claude会话结束而消失 | 写入`.claude/scheduled_tasks.json`，重启后恢复 |
| 适用场景 | 临时巡检、一次性任务 | 长期监控、每日例行任务 |
| 创建方式 | `durable: false`（默认） | `durable: true` |
| 过期机制 | 无（随会话结束） | 7天自动过期 |
| 配置路径 | 内存中 | `.claude/scheduled_tasks.json` |

**建议**：
- CI/CD监控、部署检查等短期任务 → Session-Only
- 日常代码质量检查、依赖安全扫描 → Durable

### 3.4 ScheduleWakeup：智能调度间隔

`ScheduleWakeup`是`/loop`动态模式的核心——它不是简单的固定间隔，而是根据任务性质智能选择唤醒时机：

```
Cache TTL = 5分钟

间隔选择指南：
├── < 5分钟 (60-270s)：缓存有效，适合主动轮询外部状态
│   例：监控CI运行状态（约8分钟完成）→ 设270s
│
├── 5分钟-1小时 (300-3600s)：接受缓存失效
│   例：等待代码审查反馈 → 设600s
│
└── 空闲状态 (1200-1800s)：默认心跳间隔
    例：无特定等待事项的后台巡检 → 设1500s

⚠️ 避免300s（最差选择：缓存已失效但未充分利用）
```

### 3.5 实战：自主代码质量巡检Agent

以下是一个完整的自主巡检方案，在Claude Code会话中启动：

```
请帮我建立一个自主巡检系统：

1. 每30分钟检查一次：
   - git pull最新代码
   - 运行ESLint和TypeScript类型检查
   - 如果发现问题，尝试自动修复
   - 修复后运行测试验证

2. 如果连续3次巡检无新问题，将频率降低到每小时

3. 发现严重问题（安全漏洞、构建失败）时立即通知
```

Claude会创建类似以下的调度：

```json
{
  "tasks": [
    {
      "id": "patrol-quality",
      "cron": "*/30 * * * *",
      "prompt": "执行代码质量巡检：git pull，运行lint和类型检查，尝试自动修复问题，运行测试验证",
      "recurring": true,
      "durable": true
    },
    {
      "id": "patrol-security",
      "cron": "0 */4 * * *",
      "prompt": "运行npm audit检查安全漏洞，分析高危漏洞的影响范围，给出修复建议",
      "recurring": true,
      "durable": true
    }
  ]
}
```

```text
flowchart TD
    A[/loop 启动自主巡检] --> B[CronCreate 创建定时任务]
    B --> C[写入 .claude/scheduled_tasks.json]
    C --> D[等待触发时间]

    D --> E[触发执行]
    E --> F[git pull 获取最新代码]
    F --> G[运行 Lint + 类型检查]

    G --> H{发现问题?}
    H -->|否| I[记录：本次无问题]
    I --> J{连续3次无问题?}
    J -->|是| K[降低频率到每小时]
    J -->|否| D
    K --> D

    H -->|是| L[尝试自动修复]
    L --> M[运行测试验证]
    M --> N{测试通过?}
    N -->|是| O[Commit修复]
    N -->|否| P[通知人工介入]
    O --> D
    P --> D
```

---

## 第四章：成本控制与生产级实践

### 4.1 Token消耗模型

Claude Code在Headless模式下的成本由以下因素决定：

| 因素 | 影响 | 优化策略 |
|------|------|----------|
| 模型选择 | Opus最贵，Haiku最便宜 | 简单任务用Sonnet，复杂任务才用Opus |
| 上下文大小 | 仓库越大token越多 | `.claudeignore`排除无关目录 |
| Agent轮次 | 每轮消耗token | `--max-turns`严格限制 |
| 工具调用 | 每次调用有输入输出开销 | `--allowedTools`限制工具集 |
| 缓存命中 | 缓存命中降低50%+成本 | 保持CLAUDE.md稳定，减少上下文变更 |

### 4.2 成本优化的6个实用技巧

**技巧1：分层模型策略**

```bash
# 简单格式化/拼写检查 → Sonnet（快速且便宜）
claude -p "修复所有拼写错误" \
  --model claude-sonnet-4-6 \
  --max-turns 3

# 安全审计/架构分析 → Opus（深度思考）
claude -p "审查认证模块的安全架构" \
  --model claude-opus-4-8 \
  --max-turns 10 \
  --allowedTools "Read,Glob,Grep"
```

**技巧2：精简上下文**

```bash
# .claudeignore 文件 — 排除不必要的内容
node_modules/
dist/
build/
*.min.js
*.min.css
.lock
package-lock.json
*.svg
*.png
```

**技巧3：结构化输出减少冗余**

```bash
# 不好的做法：自由文本输出
claude -p "列出所有bug"

# 好的做法：要求结构化输出
claude -p "以JSON格式列出所有bug，格式：[{file, line, severity, description}]"

# 更好：使用--output-format json
claude -p "列出所有bug" --output-format json
```

**技巧4：会话复用**

```bash
# 不好的做法：每次都新建会话
claude -p "分析文件A"
claude -p "现在分析文件B"  # 丢失了A的上下文

# 好的做法：复用会话
claude -p "分析文件A"  # 返回session_id
claude --resume <id> -p "基于A的分析，现在分析B"
```

**技巧5：预算硬上限**

```bash
# 在CI脚本中设置token预算
claude -p "修复lint错误" \
  --max-turns 10 \
  --allowedTools "Read,Write,Edit"
```

**技巧6：使用`/compact`管理上下文窗口**

在长时间运行的会话中，上下文会不断增长。`/compact`命令会压缩历史对话：

```
用户：/compact

Claude：已压缩上下文。关键信息已保留：
- 已审查12个文件，发现3个问题
- 修复了其中2个，1个需要人工确认
- 当前工作目录：src/auth/
```

### 4.3 监控与告警

```bash
#!/bin/bash
# monitor-costs.sh — 监控Claude Code使用成本
set -e

# 获取当前用量
USAGE=$(claude -p "输出当前会话的token使用统计" --output-format json 2>/dev/null)

INPUT_TOKENS=$(echo "$USAGE" | jq -r '.usage.input_tokens // 0')
OUTPUT_TOKENS=$(echo "$USAGE" | jq -r '.usage.output_tokens // 0')

# 简单的成本估算（基于Sonnet定价）
INPUT_COST=$(echo "scale=4; $INPUT_TOKENS * 3 / 1000000" | bc)
OUTPUT_COST=$(echo "scale=4; $OUTPUT_TOKENS * 15 / 1000000" | bc)
TOTAL_COST=$(echo "scale=4; $INPUT_COST + $OUTPUT_COST" | bc)

echo "=== Claude Code 成本报告 ==="
echo "输入Token: $INPUT_TOKENS → \$$INPUT_COST"
echo "输出Token: $OUTPUT_TOKENS → \$$OUTPUT_COST"
echo "总成本: \$$TOTAL_COST"

# 超预算告警
if (( $(echo "$TOTAL_COST > 5.00" | bc -l) )); then
  echo "⚠️ 成本超过\$5阈值！"
  # 可以集成Slack/DingTalk通知
fi
```

---

## 第五章：GitLab CI与多平台适配

### 5.1 GitLab CI配置

```yaml
# .gitlab-ci.yml
stages:
  - review
  - fix

claude-review:
  stage: review
  image: node:20
  only:
    - merge_requests
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY  # 在CI/CD Variables中配置
  before_script:
    - npm install -g @anthropic-ai/claude-code
  script:
    - |
      git fetch origin main
      DIFF=$(git diff origin/main...HEAD)
      CHANGED=$(git diff --name-only origin/main...HEAD)
      
      claude -p "
      作为代码审查员，审查以下Merge Request的变更。
      
      变更文件：$CHANGED
      
      审查要点：
      1. 安全问题（注入、认证绕过、敏感信息泄露）
      2. 代码质量（复杂度、重复、命名）
      3. 测试覆盖（是否有对应测试）
      
      请给出结构化审查报告。
      " \
      --max-turns 5 \
      --allowedTools "Read,Glob,Grep" \
      --output-format json > review_result.json
      
      # 使用GitLab API发布评论
      REVIEW_BODY=$(jq -r '.result' review_result.json)
      curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
           --data-urlencode "body=$REVIEW_BODY" \
           "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"

claude-auto-fix:
  stage: fix
  image: node:20
  only:
    - merge_requests
  when: manual  # 手动触发，防止自动修改
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  before_script:
    - npm install -g @anthropic-ai/claude-code
  script:
    - |
      claude -p "
      查看当前分支的lint错误和类型错误，逐一修复。
      修复后运行测试确认没有引入新问题。
      不要修改任何测试文件。
      " \
      --max-turns 20 \
      --allowedTools "Read,Write,Edit,Bash,Glob,Grep"
      
      git config user.name "Claude Code [CI]"
      git config user.email "claude-ci@example.com"
      git add -A
      git diff --cached --quiet || git commit -m "fix: auto-fix by Claude Code CI"
      git push origin HEAD:$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
```

### 5.2 多环境变量管理

```bash
#!/bin/bash
# env-setup.sh — 根据环境加载不同配置

ENV=${CI_ENVIRONMENT:-development}

case $ENV in
  production)
    export CLAUDE_MODEL="claude-opus-4-8"
    export CLAUDE_MAX_TURNS="15"
    export CLAUDE_ALLOWED_TOOLS="Read,Glob,Grep"  # 生产环境只读
    ;;
  staging)
    export CLAUDE_MODEL="claude-sonnet-4-6"
    export CLAUDE_MAX_TURNS="10"
    export CLAUDE_ALLOWED_TOOLS="Read,Write,Edit,Glob,Grep"
    ;;
  development)
    export CLAUDE_MODEL="claude-sonnet-4-6"
    export CLAUDE_MAX_TURNS="20"
    export CLAUDE_ALLOWED_TOOLS="Read,Write,Edit,Bash,Glob,Grep"
    ;;
esac

echo "环境: $ENV"
echo "模型: $CLAUDE_MODEL"
echo "最大轮次: $CLAUDE_MAX_TURNS"
echo "允许工具: $CLAUDE_ALLOWED_TOOLS"
```

```mermaid
flowchart TD
    subgraph "多环境策略"
        A[Production] --> A1["Opus模型<br/>只读权限<br/>严格限制轮次"]
        B[Staging] --> B1["Sonnet模型<br/>读写权限<br/>中等轮次限制"]
        C[Development] --> C1["Sonnet模型<br/>全部权限<br/>宽松轮次限制"]
    end

    subgraph "CI/CD Pipeline"
        D[PR Created] --> E{环境判断}
        E -->|生产分支| F[严格审查模式]
        E -->|开发分支| G[标准审查模式]
        F --> A1
        G --> C1

        A1 --> H[输出审查报告]
        B1 --> H
        C1 --> H

        H --> I{是否需要自动修复?}
        I -->|是| J[Claude自动修复]
        I -->|否| K[仅记录审查结果]
        J --> L[运行测试验证]
        L --> M[Commit & Push]
    end
```

---

## 第六章：完整实战项目 — 自动化代码质量守护系统

### 6.1 项目概述

构建一个完整的自动化系统，包含：
1. **PR自动审查**：每个PR自动获得AI审查评论
2. **定时质量巡检**：每小时检查代码质量
3. **依赖安全监控**：每天检查依赖漏洞
4. **智能修复**：低风险问题自动修复并提交

### 6.2 项目结构

```
.claude/
├── CLAUDE.md                      # 项目级指令
├── scheduled_tasks.json           # 定时任务持久化
└── settings.local.json            # 本地配置（含hooks）
.github/
└── workflows/
    ├── claude-review.yml          # PR自动审查
    ├── claude-security.yml        # 安全扫描
    └── claude-quality-patrol.yml  # 质量巡检
scripts/
├── claude-review.sh               # 审查脚本
├── claude-security-scan.sh        # 安全扫描脚本
└── claude-auto-fix.sh             # 自动修复脚本
```

### 6.3 核心配置文件

**CLAUDE.md（项目级AI指令）**：

```markdown
# 项目信息
这是一个Next.js 14 + TypeScript项目，使用Prisma ORM和PostgreSQL。

# 代码规范
- 使用函数式组件和hooks
- 所有API路由需要错误处理中间件
- 数据库操作使用事务
- 测试覆盖率目标：80%

# 审查重点
- 认证/授权逻辑变更需要特别审查
- 数据库迁移需要检查是否有数据丢失风险
- API接口变更需要确认向后兼容性

# 自动修复规则
- 只修复lint和类型错误
- 不修改业务逻辑
- 不修改测试断言
- 修复后必须运行测试验证
```

**settings.local.json（Hooks配置）**：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[安全检查] 确认不修改敏感文件: $TOOL_INPUT' >&2"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE 2>/dev/null || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '任务完成，运行最终检查...' && npm run lint && npm run type-check"
          }
        ]
      }
    ]
  }
}
```

**GitHub Actions完整Workflow**：

```yaml
# .github/workflows/claude-review.yml
name: Claude Quality Gate

on:
  pull_request:
    types: [opened, synchronize, reopened]

concurrency:
  group: claude-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    name: AI Code Review
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      checks: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Install Dependencies
        run: npm ci

      - name: Get PR Context
        id: context
        run: |
          # 获取变更统计
          STATS=$(git diff --stat origin/main...HEAD)
          echo "stats<<EOF" >> $GITHUB_OUTPUT
          echo "$STATS" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
          
          # 获取变更文件列表
          FILES=$(git diff --name-only origin/main...HEAD)
          echo "files<<EOF" >> $GITHUB_OUTPUT
          echo "$FILES" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
          
          # 获取完整diff（限制大小）
          DIFF=$(git diff origin/main...HEAD | head -5000)
          echo "diff<<EOF" >> $GITHUB_OUTPUT
          echo "$DIFF" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

      - name: Security Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "
          你是一名安全审计专家。审查以下PR变更中的安全风险。

          变更统计：
          ${{ steps.context.outputs.stats }}

          完整Diff：
          ${{ steps.context.outputs.diff }}

          请重点检查：
          1. SQL注入、XSS、CSRF
          2. 硬编码密钥/密码
          3. 不安全的依赖引入
          4. 权限提升风险

          以JSON格式输出：{severity: 'high'|'medium'|'low', findings: [{file, line, type, description}]}
          如果没有安全问题，输出：{severity: 'none', findings: []}
          " \
          --max-turns 3 \
          --allowedTools "Read,Glob,Grep" \
          --output-format json > security_review.json 2>/dev/null

      - name: Code Quality Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "
          你是一名资深代码审查员。审查以下PR的代码质量。

          变更文件：
          ${{ steps.context.outputs.files }}

          审查标准：
          1. 可维护性（复杂度、命名、注释）
          2. 错误处理（边界条件、异常捕获）
          3. 性能（算法效率、内存使用）
          4. 测试覆盖（是否有对应测试）

          对每个问题给出：严重度、文件位置、具体建议。
          使用中文输出。
          " \
          --max-turns 5 \
          --allowedTools "Read,Glob,Grep" \
          --output-format json > quality_review.json 2>/dev/null

      - name: Publish Review Comment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # 合并两个审查结果
          python3 -c "
          import json, sys
          
          with open('security_review.json') as f:
              sec = json.load(f)
          with open('quality_review.json') as f:
              qual = json.load(f)
          
          comment = '## 🤖 Claude Code 审查报告\n\n'
          
          # 安全部分
          sec_severity = sec.get('severity', 'none')
          if sec_severity == 'none':
              comment += '### 🔒 安全审查\n✅ 未发现安全问题\n\n'
          else:
              emoji = '🔴' if sec_severity == 'high' else '🟡' if sec_severity == 'medium' else '🟢'
              comment += f'### 🔒 安全审查 {emoji}\n'
              for f in sec.get('findings', []):
                  comment += f'- **{f[\"type\"]}** ({f[\"file\"]}:{f.get(\"line\",\"?\")}) — {f[\"description\"]}\n'
              comment += '\n'
          
          # 质量部分
          comment += '### 📋 代码质量审查\n'
          qual_text = qual.get('result', '审查完成')
          comment += qual_text
          
          with open('final_comment.md', 'w') as f:
              f.write(comment)
          "
          
          gh pr comment ${{ github.event.pull_request.number }} \
            --body-file final_comment.md

      - name: Upload Review Artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: claude-review-results
          path: |
            security_review.json
            quality_review.json
          retention-days: 7
```

### 6.4 运行效果

当开发者提交PR后，系统自动执行：

1. **检出代码** → 获取完整变更上下文
2. **安全审查** → Claude用Opus模型扫描安全风险
3. **质量审查** → Claude用Sonnet模型评估代码质量
4. **合并报告** → 自动生成结构化审查报告
5. **发布评论** → 在PR中发布审查结果

预期PR评论效果：

```markdown
## 🤖 Claude Code 审查报告

### 🔒 安全审查 🟢
- **硬编码API URL** (src/config.ts:12) — 建议使用环境变量
- **未验证用户输入** (src/api/routes.ts:45) — userId参数缺少类型校验

### 📋 代码质量审查
✅ 整体代码质量良好，以下为改进建议：

- **错误处理**：src/api/routes.ts:78 的catch块过于宽泛，建议细化异常类型
- **性能**：src/components/UserList.tsx 使用了内联函数，可能导致不必要的重渲染
- **命名**：src/utils/h.ts 建议使用更具描述性的文件名
```

```mermaid
flowchart TD
    subgraph "触发阶段"
        A[开发者提交PR] --> B[GitHub Actions 触发]
    end

    subgraph "分析阶段"
        B --> C[检出代码 + 获取diff]
        C --> D1["安全审查<br/>Opus模型<br/>max-turns: 3"]
        C --> D2["质量审查<br/>Sonnet模型<br/>max-turns: 5"]
        D1 --> E[security_review.json]
        D2 --> F[quality_review.json]
    end

    subgraph "输出阶段"
        E --> G[Python脚本合并结果]
        F --> G
        G --> H[生成final_comment.md]
        H --> I[gh pr comment 发布]
        I --> J[PR页面显示审查报告]
    end

    subgraph "后续动作"
        J --> K{发现高危问题?}
        K -->|是| L[添加 🔴 安全标签]
        K -->|否| M[通过审查 ✅]
        L --> N[通知安全团队]
    end
```

---

## 第七章：常见问题与故障排查

### 7.1 常见错误与解决方案

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| `API key not found` | 未设置环境变量 | 确认`ANTHROPIC_API_KEY`已配置为Secret |
| `Session not found` | 会话ID过期 | 使用`claude --continue`代替过期ID |
| `Max turns exceeded` | Agent轮次耗尽 | 增大`--max-turns`或简化任务 |
| `Rate limit exceeded` | API调用频率过高 | 添加重试逻辑，降低调度频率 |
| `Context window exceeded` | 仓库太大 | 优化`.claudeignore`，使用`/compact` |
| `Permission denied` | 工具被禁止 | 检查`--allowedTools`和`permissions`配置 |

### 7.2 调试技巧

```bash
# 查看详细日志
claude -p "测试" --verbose 2>claude-debug.log

# JSON输出模式查看完整元数据
claude -p "测试" --output-format json | jq '.'

# 检查会话历史
ls ~/.claude/projects/*/sessions/

# 查看定时任务状态
cat .claude/scheduled_tasks.json | jq '.'
```

### 7.3 CI/CD中的重试策略

```bash
#!/bin/bash
# retry-claude.sh — 带重试的Claude调用
MAX_RETRIES=3
RETRY_DELAY=30

for i in $(seq 1 $MAX_RETRIES); do
  echo "尝试 $i/$MAX_RETRIES..."
  
  if claude -p "$1" \
    --max-turns "${MAX_TURNS:-10}" \
    --output-format json > result.json 2>/dev/null; then
    echo "成功！"
    exit 0
  fi
  
  if [ $i -lt $MAX_RETRIES ]; then
    echo "失败，${RETRY_DELAY}秒后重试..."
    sleep $RETRY_DELAY
    RETRY_DELAY=$((RETRY_DELAY * 2))  # 指数退避
  fi
done

echo "所有重试均失败"
exit 1
```

---

## 延伸阅读

- [Anthropic官方：Claude Code GitHub Actions文档](https://code.claude.com/docs/en/github-actions) — 官方Action的完整配置参考
- [Anthropic官方：Headless模式文档](https://code.claude.com/docs/en/headless) — Agent SDK和`-p`模式的权威指南
- [Anthropic官方：定时任务文档](https://code.claude.com/docs/en/scheduled-tasks) — `/loop`和CronCreate的详细说明
- [Anthropic官方：Hooks参考](https://code.claude.com/docs/en/hooks) — 所有Hook事件类型的完整规范
- [Trail of Bits：Claude Code安全配置](https://deepwiki.com/trailofbits/claude-code-config/4.2-pretooluse-hook-examples) — 安全团队推荐的PreToolUse Hook示例

## 参考来源

1. [Run Claude Code programmatically — Anthropic官方文档](https://code.claude.com/docs/en/headless) — Headless模式、Agent SDK、CLI参数完整参考
2. [Claude Code GitHub Actions — Anthropic官方文档](https://code.claude.com/docs/en/github-actions) — 官方GitHub Action集成指南与YAML配置
3. [Run prompts on a schedule — Anthropic官方文档](https://code.claude.com/docs/en/scheduled-tasks) — /loop命令与CronCreate定时调度机制
4. [Claude Code Batch Processing Guide — SmartScope](https://smartscope.blog/en/generative-ai/claude/claude-code-batch-processing/) — /batch命令与headless模式批量处理实战
5. [Claude Code Hooks Reference — Anthropic官方文档](https://code.claude.com/docs/en/hooks) — Hooks事件类型、配置schema、JSON输入输出格式

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | DevOps训练营、AI工程化训练营、团队效能提升工作坊 |
| **学员基础要求** | 熟悉Git、CI/CD基础、至少使用过Claude Code交互模式 |
| **预计教学时长** | 6-8小时（含实操） |
| **推荐教学节奏** | 第一章（1h）→ 第二章（2h）→ 第三章（1.5h）→ 第四至六章（2.5h） |
| **实操环境需求** | GitHub仓库、Anthropic API Key、Node.js 20+ |
| **课后作业建议** | 为自己的项目配置GitHub Actions自动审查 + 一个/loop定时巡检任务 |

> [!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)