<!-- title: Claude Code自动化三大武器实战全解 -->

# Claude Code自动化三大武器实战全解

## 概述

本教程面向已掌握Claude Code基础操作的开发者，深入讲解三大自动化武器：**Headless模式（-p）**、**Hooks系统**、**批量任务编排**。学完后你将能构建完整的自动化工作流——从CI/CD代码审查到批量重构、从安全防护到通知推送，让Claude Code从"对话助手"进化为"自动化引擎"。

**适用人群**：有Claude Code使用经验的开发者、DevOps工程师、需要大规模代码改造的技术负责人。

**学习目标**：
- 掌握 `-p` 模式的所有参数与输出格式
- 独立配置Hooks的6种事件类型和Matcher模式
- 构建多步骤、可编排的批量自动化流水线

## 前置条件

| 条件 | 说明 |
|------|------|
| Claude Code CLI | 已安装并完成认证（`claude` 命令可用） |
| 终端基础 | 熟悉 Bash/Zsh 管道、重定向、退出码 |
| API Key | `ANTHROPIC_API_KEY` 环境变量已配置 |
| 项目目录 | 一个有实际代码的 Git 仓库用于练习 |

---

## 第一部分：Headless模式——让Claude Code变成命令行工具

### 1.1 核心概念

Headless模式是Claude Code的非交互执行模式。当你使用 `-p`（或 `--print`）标志时，Claude Code不再启动交互式REPL，而是接受一条Prompt，执行后直接输出结果到stdout。

```mermaid
flowchart LR
    A["用户输入<br/>claude -p 'prompt'"] --> B["Headless模式<br/>非交互执行"]
    B --> C{"输出格式"}
    C -->|"--output-format text"| D["纯文本到stdout"]
    C -->|"--output-format json"| E["JSON结构体"]
    C -->|"--output-format stream-json"| F["NDJSON事件流"]
    D --> G["管道到其他命令"]
    E --> H["程序化解析"]
    F --> I["实时流式处理"]
```

### 1.2 基础用法

**最简形式**——一行命令获得回答：

```bash
claude -p "解释这个函数的作用：$(cat src/utils/parse.ts)"
```

**管道输入**——把文件内容"喂"给Claude：

```bash
cat error.log | claude -p "分析这些错误日志，找出根本原因"
```

**输出重定向**——结果写入文件：

```bash
claude -p "为 src/api/ 下所有接口生成TypeScript类型定义" > types.generated.ts
```

### 1.3 关键参数全览

| 参数 | 作用 | 示例 |
|------|------|------|
| `-p` / `--print` | 启用非交互模式 | `claude -p "prompt"` |
| `--output-format` | 输出格式：`text`/`json`/`stream-json` | `--output-format json` |
| `--max-turns` | 限制Agent最大执行轮数 | `--max-turns 5` |
| `--allowedTools` | 限制可用工具列表 | `--allowedTools "Read,Glob,Grep"` |
| `--model` | 指定使用的模型 | `--model claude-sonnet-4-6` |
| `--system-prompt` | 自定义系统提示 | `--system-prompt "你是一个代码审查专家"` |
| `--input-format` | 输入格式：`text`/`stream-json` | `--input-format stream-json` |
| `--resume` | 恢复之前的会话 | `--resume <session-id>` |
| `--append-system-prompt` | 追加系统提示（不覆盖默认） | `--append-system-prompt "项目使用React 19"` |

### 1.4 三种输出格式详解

**格式一：text（默认）**

纯文本输出，适合人类阅读和简单管道：

```bash
claude -p "列出package.json中过时的依赖" --output-format text
# 输出：直接的文字回答
```

**格式二：json**

返回结构化JSON，包含完整会话信息：

```bash
claude -p "这段代码有什么问题？" --output-format json
```

输出结构（简化）：

```json
{
  "result": "代码中存在以下问题...",
  "session_id": "abc-123-def",
  "cost_usd": 0.034,
  "duration_ms": 4500,
  "num_turns": 3,
  "is_error": false
}
```

**格式三：stream-json**

实时NDJSON（Newline Delimited JSON）事件流——这是自动化的核心：

```bash
claude -p "重构auth模块" --output-format stream-json --verbose
```

每行是一个JSON事件，关键事件类型包括：

```
{"type":"system","subtype":"init","session_id":"...","tools":[...]}
{"type":"assistant","subtype":"text","content":"我来分析auth模块..."}
{"type":"tool_use","name":"Read","input":{"file_path":"src/auth/index.ts"}}
{"type":"tool_result","name":"Read","output":"文件内容..."}
{"type":"result","result":"重构完成...","cost_usd":0.12,"duration_ms":12000}
```

### 1.5 多轮对话：stdin流式输入

通过 `--input-format stream-json` 可以实现多轮对话式自动化：

```bash
cat <<'EOF' | claude -p --input-format stream-json --output-format stream-json
{"type":"user","content":"分析src/api目录下的代码结构"}
{"type":"user","content":"为每个接口生成对应的单元测试"}
{"type":"user","content":"运行测试并报告结果"}
EOF
```

每条JSON消息代表一个用户轮次，Claude会按顺序处理所有轮次。

### 1.6 安全限制——工具白名单

在自动化场景中，限制Claude的工具权限是关键安全措施：

```bash
# 只读审查——不允许修改任何文件
claude -p "审查这个PR的安全问题" \
  --allowedTools "Read,Glob,Grep,Bash" \
  --max-turns 10

# 纯分析模式——只能读取和搜索
claude -p "生成项目架构文档" \
  --allowedTools "Read,Glob,Grep"
```

**可用工具名列表**：`Read`、`Write`、`Edit`、`Bash`、`Glob`、`Grep`、`Task`、`WebSearch`、`TodoWrite`、`NotebookEdit` 等。

---

## 第二部分：Hooks系统——为Agent行为装上"触发器"

### 2.1 Hooks架构总览

Hooks是Claude Code的事件驱动机制，允许你在特定时机注入自定义逻辑——无论是安全防护、自动格式化、还是通知推送。

```mermaid
flowchart TB
    subgraph "Hook事件生命周期"
        A["SessionStart"] --> B["UserPromptSubmit"]
        B --> C["PreToolUse"]
        C --> D["工具执行"]
        D --> E["PostToolUse"]
        E --> F["继续Agent循环"]
        F --> C
        F --> G["Stop"]
        G --> H["Notification"]
    end

    subgraph "Hook处理器类型"
        I["command<br/>Shell命令"]
        J["http<br/>HTTP请求"]
        K["prompt<br/>LLM判断"]
    end

    C -.-> I
    C -.-> J
    C -.-> K
    E -.-> I
    E -.-> J
```

### 2.2 六大Hook事件类型

| 事件 | 触发时机 | 典型用途 |
|------|----------|----------|
| `PreToolUse` | 工具执行**之前** | 拦截危险操作、输入校验、权限控制 |
| `PostToolUse` | 工具执行**之后** | 自动格式化、日志审计、触发通知 |
| `Notification` | Agent发出通知时 | 发送到Slack/Discord、桌面通知 |
| `Stop` | Agent会话结束时 | 执行清理、生成报告、记录指标 |
| `SubagentStop` | 子Agent结束时 | 聚合子Agent结果、资源清理 |
| `SessionStart` | 会话启动时 | 注入上下文、环境检测、加载配置 |

### 2.3 配置位置与优先级

Hooks可以在三个层级配置，优先级从低到高：

```
~/.claude/settings.json          # 全局配置（所有项目）
├── .claude/settings.json        # 项目级配置（团队共享）
└── .claude/settings.local.json  # 本地配置（个人偏好，不提交到Git）
```

### 2.4 配置Schema详解

完整的Hooks配置结构：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "your-script.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "send-slack-notification.sh"
          }
        ]
      }
    ]
  }
}
```

**关键字段说明**：

- `matcher`：正则表达式，匹配工具名。`PreToolUse` 和 `PostToolUse` 专用，省略则匹配所有工具
- `hooks[].type`：处理器类型，支持 `command`、`http`、`prompt`
- `hooks[].command`：要执行的Shell命令

### 2.5 Hook输入输出协议

**输入**——Hook通过stdin接收JSON数据：

```json
{
  "session_id": "sess_abc123",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "删除node_modules"
  }
}
```

**输出**——通过stdout返回JSON，退出码决定行为：

| 退出码 | 含义 | 效果 |
|--------|------|------|
| `0` | 通过 | 继续执行（可返回额外信息） |
| `2` | 阻止 | 阻止工具执行，向Agent显示原因 |

**阻止执行的示例脚本**：

```bash
#!/bin/bash
# block-dangerous-commands.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -qE 'rm\s+-rf\s+/|drop\s+table|DROP\s+TABLE'; then
  echo '{"decision":"block","reason":"禁止执行危险操作：'$COMMAND'"}'
  exit 2
fi

exit 0
```

### 2.6 六大实战Hook配置

**配置一：自动代码格式化（PostToolUse）**

每次文件写入后自动格式化：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(cat | jq -r .tool_input.file_path); ext=${FILE##*.}; case $ext in ts|tsx|js|jsx) npx prettier --write \"$FILE\" ;; py) black \"$FILE\" ;; go) gofmt -w \"$FILE\" ;; esac'"
          }
        ]
      }
    ]
  }
}
```

**配置二：保护敏感文件（PreToolUse）**

阻止修改.env等敏感文件：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); FILE=$(echo $INPUT | jq -r .tool_input.file_path); if echo \"$FILE\" | grep -qE \"\\.env|credentials|secret|\\.pem\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"禁止修改敏感文件: $FILE\\\"}\"; exit 2; fi; exit 0'"
          }
        ]
      }
    ]
  }
}
```

**配置三：Slack通知（Notification）**

Agent任务完成时发送通知：

```json
{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'MSG=$(cat | jq -r .message); curl -s -X POST \"$SLACK_WEBHOOK_URL\" -H \"Content-Type: application/json\" -d \"{\\\"text\\\":\\\"🤖 Claude Code: $MSG\\\"}\"'"
          }
        ]
      }
    ]
  }
}
```

**配置四：Bash命令安全审计（PreToolUse）**

记录并审查所有Shell命令执行：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); CMD=$(echo $INPUT | jq -r .tool_input.command); echo \"[$(date -Iseconds)] CMD: $CMD\" >> ~/.claude/bash-audit.log; if echo \"$CMD\" | grep -qE \"curl.*\\|.*sh|wget.*\\|.*bash\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"禁止管道到Shell执行\\\"}\"; exit 2; fi; exit 0'"
          }
        ]
      }
    ]
  }
}
```

**配置五：测试自动运行（PostToolUse）**

源码修改后自动运行相关测试：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(cat | jq -r .tool_input.file_path); if [[ \"$FILE\" == src/**/*.ts ]] && [[ \"$FILE\" != *.test.ts ]]; then TEST_FILE=\"${FILE%.ts}.test.ts\"; if [ -f \"$TEST_FILE\" ]; then npx vitest run \"$TEST_FILE\" 2>&1 | tail -5; fi; fi; exit 0'"
          }
        ]
      }
    ]
  }
}
```

**配置六：会话启动环境检测（SessionStart）**

每次会话开始时注入项目上下文：

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"项目: $(basename $(pwd)) | 分支: $(git branch --show-current 2>/dev/null || echo N/A) | 最后提交: $(git log -1 --oneline 2>/dev/null || echo N/A)\"'"
          }
        ]
      }
    ]
  }
}
```

### 2.7 Matcher模式匹配技巧

`matcher` 字段使用正则表达式匹配工具名：

```
Bash             # 精确匹配Bash工具
Write|Edit       # 匹配Write或Edit
.*               # 匹配所有工具
Read|Glob|Grep   # 匹配所有只读工具
```

**常见工具名列表**：

| 工具名 | 类别 |
|--------|------|
| `Read` | 文件读取 |
| `Write` | 文件创建 |
| `Edit` | 文件编辑 |
| `Bash` | Shell命令 |
| `Glob` | 文件搜索 |
| `Grep` | 内容搜索 |
| `Task` | 子Agent |
| `TodoWrite` | 任务管理 |
| `WebSearch` | 网络搜索 |

### 2.8 Hooks调试技巧

**验证Hook是否加载**：

在Claude Code交互模式中使用 `/hooks` 命令查看当前已加载的所有Hooks。

**调试Hook脚本**：

```bash
# 手动测试Hook脚本
echo '{"session_id":"test","tool_name":"Bash","tool_input":{"command":"ls -la"}}' | bash your-hook-script.sh
echo "Exit code: $?"
```

**查看Hook执行日志**：

Hooks的标准错误输出会显示在Claude Code的调试信息中。启动时加上 `--verbose` 可以看到完整的Hook执行过程。

---

## 第三部分：批量任务编排——大规模自动化实战

### 3.1 三种批量执行模式对比

```mermaid
flowchart TB
    subgraph "模式一：Shell循环"
        A1["for file in *.ts"] --> A2["claude -p 处理单个文件"]
        A2 --> A3["下一个文件"]
    end

    subgraph "模式二：并行进程"
        B1["文件列表"] --> B2["xargs -P 并行"]
        B2 --> B3["多个claude -p同时执行"]
    end

    subgraph "模式三：/batch命令"
        C1["交互式输入"] --> C2["/batch"]
        C2 --> C3["自动并行spawn"]
    end
```

| 模式 | 优点 | 缺点 | 适用场景 |
|------|------|------|----------|
| Shell循环 | 简单、可控、顺序执行 | 速度慢 | 有依赖关系的任务 |
| 并行进程 | 快速、可控制并发数 | 需处理资源竞争 | 独立的大批量任务 |
| /batch命令 | 智能调度、内置并行 | 仅交互模式可用 | 代码库大规模改造 |

### 3.2 模式一：Shell循环顺序执行

适合有依赖关系的多步任务：

```bash
#!/bin/bash
# migrate-api-endpoints.sh — 顺序迁移API端点

APIS=("users" "products" "orders" "payments" "notifications")

for api in "${APIS[@]}"; do
  echo "=== 迁移 $api API ==="
  claude -p "将 src/api/$api.ts 从Express风格迁移到Fastify风格。保持所有接口签名不变，只修改框架相关代码。" \
    --output-format text \
    --max-turns 15 \
    --allowedTools "Read,Write,Edit,Bash,Glob,Grep"
  
  echo "=== 运行 $api 测试 ==="
  npx vitest run "src/api/$api.test.ts"
  
  if [ $? -ne 0 ]; then
    echo "❌ $api 测试失败，停止迁移"
    exit 1
  fi
  echo "✅ $api 迁移完成"
done

echo "🎉 所有API迁移完成"
```

### 3.3 模式二：并行进程批量执行

适合独立的、无依赖关系的任务：

```bash
#!/bin/bash
# batch-add-tests.sh — 并行为所有模块生成测试

MAX_PARALLEL=4  # 控制并发数

generate_test() {
  local file=$1
  local test_file="${file%.ts}.test.ts"
  
  if [ -f "$test_file" ]; then
    echo "跳过 $file（测试已存在）"
    return
  fi
  
  echo "为 $file 生成测试..."
  claude -p "为以下文件生成完整的单元测试：$file。使用vitest框架，覆盖所有导出函数，包含正常路径和边界情况。" \
    --output-format text \
    --max-turns 10 \
    --allowedTools "Read,Write,Glob,Grep" \
    > "$test_file"
  
  echo "✅ $test_file 已生成"
}

export -f generate_test

# 查找所有源文件并并行处理
find src -name "*.ts" ! -name "*.test.ts" ! -name "*.d.ts" | \
  xargs -P $MAX_PARALLEL -I {} bash -c 'generate_test "$@"' _ {}

echo "🎉 批量测试生成完成"
```

### 3.4 模式三：/batch命令

`/batch` 是Claude Code v2.1.63引入的内置命令，在交互模式下使用，能自动并行spawn子Agent处理多个文件：

**使用方式**：

```
> /batch 将所有 src/components/ 下的组件从 Class 组件迁移为函数组件
```

**/batch的工作机制**：

1. Claude分析任务，确定需要修改的文件列表
2. 为每个文件（或文件组）spawn独立的子Agent
3. 子Agent并行执行，各自处理分配的文件
4. 所有子Agent完成后，主Agent汇总结果

**/batch适用场景**：
- 大规模重命名/迁移（如替换API、更新import路径）
- 批量添加JSDoc注释
- 批量修改代码风格（如从Options API改Composition API）
- 批量添加错误处理

### 3.5 多步骤Pipeline：组合三大武器

将Headless模式、Hooks和批量执行组合成完整的自动化Pipeline：

```mermaid
flowchart TB
    A["Git Push触发"] --> B["PreToolUse Hook<br/>环境检查"]
    B --> C["Step 1: claude -p<br/>代码审查"]
    C --> D["PostToolUse Hook<br/>记录审查结果"]
    D --> E["Step 2: claude -p<br/>自动修复"]
    E --> F["PostToolUse Hook<br/>自动格式化+测试"]
    F --> G["Step 3: claude -p<br/>生成变更摘要"]
    G --> H["Notification Hook<br/>发送Slack通知"]
    H --> I["Stop Hook<br/>生成最终报告"]
```

**完整的Pipeline脚本**：

```bash
#!/bin/bash
# auto-code-review-pipeline.sh — 全自动代码审查Pipeline

set -euo pipefail

BRANCH=$(git branch --show-current)
DIFF=$(git diff main...HEAD --stat)
SESSION_ID=""

echo "🚀 启动代码审查Pipeline — 分支: $BRANCH"
echo "📊 变更文件统计:"
echo "$DIFF"

# Step 1: 安全审查
echo ""
echo "=== Step 1/3: 安全审查 ==="
SECURITY_REPORT=$(claude -p "审查以下Git diff中的安全隐患（SQL注入、XSS、硬编码密钥、不安全的依赖）。只报告确定的漏洞，不要误报。输出JSON格式：{\"issues\": [{\"file\": \"...\", \"line\": N, \"severity\": \"high|medium|low\", \"description\": \"...\"}]}

Diff:
$(git diff main...HEAD)" \
  --output-format json \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 8)

echo "$SECURITY_REPORT" | jq '.result' 2>/dev/null || echo "$SECURITY_REPORT"

# Step 2: 代码质量改进建议
echo ""
echo "=== Step 2/3: 质量审查 ==="
QUALITY_REPORT=$(claude -p "审查以下Git diff的代码质量。关注：1)性能问题 2)可维护性 3)测试覆盖率 4)错误处理。输出简洁的改进建议列表。

Diff:
$(git diff main...HEAD)" \
  --output-format text \
  --allowedTools "Read,Glob,Grep,Bash" \
  --max-turns 10)

echo "$QUALITY_REPORT"

# Step 3: 生成PR摘要
echo ""
echo "=== Step 3/3: 生成变更摘要 ==="
SUMMARY=$(claude -p "为以下代码变更生成一个简洁的PR描述，包括：1)主要变更内容（3-5个要点）2)影响范围 3)建议的测试重点

Diff stat:
$(git diff main...HEAD --stat)

最近的Commits:
$(git log main..HEAD --oneline)" \
  --output-format text \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 5)

echo "$SUMMARY"

# 输出最终报告
echo ""
echo "========================================="
echo "📋 审查报告已生成"
echo "========================================="
```

### 3.6 CI/CD集成实战

**GitHub Actions集成示例**：

```yaml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      
      - name: Run AI Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "你是高级代码审查员。审查这个PR的变更，重点关注：
          1. 安全漏洞（OWASP Top 10）
          2. 性能退化
          3. 逻辑错误
          4. 测试覆盖是否充分

          只报告确定的、可操作的问题。不要报告风格偏好。

          变更内容：
          $(git diff origin/main...HEAD)" \
            --output-format text \
            --allowedTools "Read,Glob,Grep,Bash" \
            --max-turns 15 \
            > review_output.md
      
      - name: Post Review Comment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr comment ${{ github.event.pull_request.number }} \
            --body-file review_output.md
```

**Git Pre-commit Hook集成**：

```bash
#!/bin/bash
# .git/hooks/pre-commit — 提交前自动审查

STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx|py)$')

if [ -z "$STAGED_FILES" ]; then
  exit 0
fi

echo "🔍 AI审查暂存文件..."

REVIEW=$(claude -p "快速审查以下文件的代码质量，只报告严重问题。如果代码质量可接受，输出PASS。

文件列表：
$STAGED_FILES

具体内容：
$(git diff --cached)" \
  --output-format text \
  --max-turns 5 \
  --allowedTools "Read,Glob,Grep")

echo "$REVIEW"

if echo "$REVIEW" | grep -q "BLOCK"; then
  echo "❌ 代码审查未通过，请修复上述问题后重新提交"
  exit 1
fi

echo "✅ 代码审查通过"
exit 0
```

### 3.7 高级模式：RALF循环

对于特别大的任务（如全项目迁移），可以采用RALF（Read-Analyze-Loop-Fix）循环模式，将多个Claude Code会话串联起来：

```bash
#!/bin/bash
# ralf-loop-migration.sh — RALF循环模式

TARGET_FILES=($(find src -name "*.vue" -type f))
MAX_ITERATIONS=5
PASS=0

while [ $PASS -lt $MAX_ITERATIONS ]; do
  PASS=$((PASS + 1))
  echo "=== 第 $PASS 轮 ==="
  
  # Read & Analyze
  ISSUES=$(claude -p "检查以下Vue组件是否已完全迁移到Vue 3 Composition API。列出仍使用Options API的组件。

文件列表：
$(printf '%s\n' "${TARGET_FILES[@]}")" \
    --output-format text \
    --allowedTools "Read,Glob,Grep" \
    --max-turns 8)
  
  if echo "$ISSUES" | grep -q "全部迁移完成\|没有遗留问题\|all migrated"; then
    echo "🎉 迁移完成！共 $PASS 轮"
    break
  fi
  
  echo "发现问题："
  echo "$ISSUES"
  
  # Loop & Fix
  claude -p "根据以下问题列表，修复所有未完成迁移的Vue组件。

问题：
$ISSUES" \
    --output-format text \
    --max-turns 20 \
    --allowedTools "Read,Write,Edit,Glob,Grep,Bash"
  
  # 运行测试验证
  npx vitest run 2>&1 | tail -10
done
```

---

## 第四部分：综合实战案例——全自动代码质量守护

### 4.1 场景描述

构建一个完整的自动化系统，当代码变更时自动：审查安全→运行测试→修复问题→更新文档→发送通知。

### 4.2 完整项目结构

```
project/
├── .claude/
│   ├── settings.json          # Hooks配置
│   └── settings.local.json    # 本地配置
├── scripts/
│   └── auto-quality-guard.sh  # 主Pipeline脚本
├── CLAUDE.md                  # Claude行为指引
└── .github/
    └── workflows/
        └── quality-guard.yml  # CI/CD配置
```

### 4.3 配置文件

**`.claude/settings.json`**——项目级Hooks：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); FILE=$(echo $INPUT | jq -r .tool_input.file_path); if echo \"$FILE\" | grep -qE \"\\.env|credentials|\\.pem|secret\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"安全策略：禁止修改敏感文件 $FILE\\\"}\"; exit 2; fi; exit 0'"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); CMD=$(echo $INPUT | jq -r .tool_input.command); echo \"[$(date -Iseconds)] BASH: $CMD\" >> .claude/command-log.txt; if echo \"$CMD\" | grep -qE \"rm\\s+-rf\\s+/|DROP\\s+TABLE|truncate\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"危险命令被拦截: $CMD\\\"}\"; exit 2; fi; exit 0'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); FILE=$(echo $INPUT | jq -r .tool_input.file_path); ext=${FILE##*.}; case $ext in ts|tsx|js|jsx) npx prettier --write \"$FILE\" 2>/dev/null; npx eslint --fix \"$FILE\" 2>/dev/null ;; py) black \"$FILE\" 2>/dev/null ;; esac; exit 0'"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'MSG=$(cat | jq -r .message // .text // empty); if [ -n \"$MSG\" ] && [ -n \"$SLACK_WEBHOOK\" ]; then curl -s -X POST \"$SLACK_WEBHOOK\" -H \"Content-Type: application/json\" -d \"{\\\"text\\\":\\\"[Claude Code] $MSG\\\"}\" > /dev/null; fi; exit 0'"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"项目: $(basename $(pwd)) | 分支: $(git branch --show-current 2>/dev/null || echo detached) | 最后提交: $(git log -1 --oneline 2>/dev/null || echo none) | Node: $(node -v 2>/dev/null || echo N/A)\"'"
          }
        ]
      }
    ]
  }
}
```

**`scripts/auto-quality-guard.sh`**：

```bash
#!/bin/bash
set -euo pipefail

PROJECT_DIR=$(pwd)
REPORT_DIR="$PROJECT_DIR/.claude/reports"
mkdir -p "$REPORT_DIR"

TIMESTAMP=$(date +%Y%m%d_%H%M%S)
REPORT_FILE="$REPORT_DIR/quality-$TIMESTAMP.md"

echo "# 代码质量报告 - $(date +%Y-%m-%d\ %H:%M)" > "$REPORT_FILE"
echo "" >> "$REPORT_FILE"

# Step 1: 安全扫描
echo "## 1. 安全扫描" >> "$REPORT_FILE"
SEC_RESULT=$(claude -p "扫描项目中所有源文件的安全问题。重点检查：
- 硬编码的密钥或Token
- SQL注入风险
- XSS风险
- 不安全的依赖引用
- 敏感信息泄露

输出格式：按严重程度排序，每条包含文件路径、行号、问题描述。" \
  --output-format text \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 12)

echo "$SEC_RESULT" >> "$REPORT_FILE"
echo "" >> "$REPORT_FILE"

# Step 2: 代码质量分析
echo "## 2. 代码质量分析" >> "$REPORT_FILE"
QUALITY_RESULT=$(claude -p "分析项目代码质量，输出以下指标：
1. 重复代码比例较高的区域
2. 圈复杂度超过10的函数
3. 过长的函数（超过50行）
4. 缺少错误处理的异步函数
5. 潜在的性能瓶颈

给出具体的文件路径和行号。" \
  --output-format text \
  --allowedTools "Read,Glob,Grep,Bash" \
  --max-turns 15)

echo "$QUALITY_RESULT" >> "$REPORT_FILE"
echo "" >> "$REPORT_FILE"

# Step 3: 测试覆盖率分析
echo "## 3. 测试覆盖分析" >> "$REPORT_FILE"
COV_RESULT=$(claude -p "分析项目的测试覆盖率。列出：
1. 没有对应测试的源文件
2. 测试中缺少的边界情况
3. 建议优先添加测试的模块（按风险排序）" \
  --output-format text \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 10)

echo "$COV_RESULT" >> "$REPORT_FILE"

# 输出报告位置
echo ""
echo "📊 质量报告已生成: $REPORT_FILE"
cat "$REPORT_FILE"
```

**`.github/workflows/quality-guard.yml`**：

```yaml
name: AI Quality Guard

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 2 * * 1'  # 每周一凌晨2点

jobs:
  quality-scan:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: |
          npm ci
          npm install -g @anthropic-ai/claude-code
      
      - name: Security Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "审查这个仓库的安全状况。检查所有源代码文件中是否存在：硬编码密钥、SQL注入、XSS、不安全的反序列化、路径遍历。输出JSON格式报告。" \
            --output-format json \
            --allowedTools "Read,Glob,Grep" \
            --max-turns 15 > security-report.json
      
      - name: Quality Analysis
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "分析代码库的整体质量。重点关注：代码复杂度、重复代码、错误处理、API设计。输出改进建议列表，按优先级排序。" \
            --output-format text \
            --allowedTools "Read,Glob,Grep,Bash" \
            --max-turns 12 > quality-report.md
      
      - name: Upload Reports
        uses: actions/upload-artifact@v4
        with:
          name: quality-reports
          path: |
            security-report.json
            quality-report.md
      
      - name: Comment on PR
        if: github.event_name == 'pull_request'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr comment ${{ github.event.pull_request.number }} \
            --body-file quality-report.md
```

---

## 第五部分：进阶技巧与最佳实践

### 5.1 成本控制策略

自动化场景容易产生大量API调用，需要严格控制：

```bash
# 限制最大轮数，防止Agent"跑飞"
claude -p "任务" --max-turns 5

# 使用更经济的模型处理简单任务
claude -p "格式化这个文件" --model claude-haiku-4-5

# 只读任务限制工具，减少不必要调用
claude -p "分析代码" --allowedTools "Read,Glob,Grep"
```

### 5.2 错误处理与重试

```bash
#!/bin/bash
# 带重试的Claude Code调用

call_claude_with_retry() {
  local prompt="$1"
  local max_retries=3
  local attempt=1
  
  while [ $attempt -le $max_retries ]; do
    RESULT=$(claude -p "$prompt" --output-format json 2>&1)
    EXIT_CODE=$?
    
    if [ $EXIT_CODE -eq 0 ]; then
      echo "$RESULT"
      return 0
    fi
    
    echo "尝试 $attempt/$max_retries 失败，退出码: $EXIT_CODE" >&2
    attempt=$((attempt + 1))
    sleep 5
  done
  
  echo "所有重试失败" >&2
  return 1
}
```

### 5.3 会话复用——`--resume`

对于复杂任务，可以保存会话ID并在后续继续：

```bash
# 第一次调用，获取session_id
RESULT=$(claude -p "分析项目架构" --output-format json)
SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')
echo "Session ID: $SESSION_ID" > .claude/last-session

# 后续调用，继续同一会话
claude -p "基于刚才的分析，生成架构改进方案" \
  --resume "$SESSION_ID" \
  --output-format text
```

### 5.4 Stream-JSON实时处理

使用 `jq` 实时过滤stream-json输出：

```bash
claude -p "重构整个auth模块" \
  --output-format stream-json \
  --max-turns 20 \
  | while read -r line; do
    TYPE=$(echo "$line" | jq -r '.type // empty')
    case "$TYPE" in
      tool_use)
        TOOL=$(echo "$line" | jq -r '.name')
        echo "🔧 使用工具: $TOOL"
        ;;
      tool_result)
        echo "✅ 工具执行完成"
        ;;
      result)
        COST=$(echo "$line" | jq -r '.cost_usd')
        DURATION=$(echo "$line" | jq -r '.duration_ms')
        echo "💰 费用: \$$COST | ⏱ 耗时: ${DURATION}ms"
        ;;
    esac
  done
```

### 5.5 完整工作流Mermaid图

```mermaid
flowchart TB
    subgraph "触发层"
        T1["Git Push"]
        T2["定时任务"]
        T3["手动触发"]
        T4["PR创建"]
    end

    subgraph "Hook拦截层"
        H1["SessionStart<br/>环境检测"]
        H2["PreToolUse<br/>安全防护"]
        H3["PostToolUse<br/>自动格式化"]
        H4["Notification<br/>消息推送"]
    end

    subgraph "执行层"
        E1["claude -p<br/>代码审查"]
        E2["claude -p<br/>自动修复"]
        E3["claude -p<br/>测试生成"]
        E4["claude -p<br/>文档更新"]
    end

    subgraph "输出层"
        O1["JSON报告"]
        O2["Git Commit"]
        O3["PR评论"]
        O4["Slack通知"]
    end

    T1 --> H1 --> E1
    T4 --> E1
    T2 --> E1
    T3 --> E1
    E1 --> E2 --> E3 --> E4
    E1 --> H2
    E2 --> H2
    E2 --> H3
    E4 --> H4
    E1 --> O1
    E2 --> O2
    E1 --> O3
    H4 --> O4
```

---

## 延伸阅读

| 资源 | 说明 |
|------|------|
| [Claude Code Headless模式官方文档](https://code.claude.com/docs/en/headless) | 编程式使用Claude Code的权威参考 |
| [Claude Code Hooks官方文档](https://code.claude.com/docs/en/hooks) | Hooks的完整Schema和事件参考 |
| [Claude Code CLI Reference](https://code.claude.com/docs/en/cli-reference) | 所有CLI标志和命令的完整列表 |
| [Stream-JSON Protocol Reference](https://github.com/claudification/claudewerk/blob/main/docs/stream-json-protocol.md) | stream-json协议的详细事件类型文档 |
| [Claude Code Hooks完整指南](https://aiorg.dev/blog/claude-code-hooks) | 20+个即用型Hooks配置示例 |

## 参考来源

1. [Run Claude Code programmatically - Claude Code Docs](https://code.claude.com/docs/en/headless) — Headless模式官方文档，涵盖-p标志、输出格式、stdin管道
2. [Hooks reference - Claude Code Docs](https://code.claude.com/docs/en/hooks) — Hooks官方参考，包含所有事件类型、JSON Schema、退出码说明
3. [Claude Code Batch Processing Complete Guide](https://smartscope.blog/en/generative-ai/claude/claude-code-batch-processing/) — /batch命令和批量处理模式的系统指南
4. [Claude Code Hooks Schemas Reference (GitHub Gist)](https://gist.github.com/FrancisBourre/50dca37124ecc43eaf08328cdcccdb34) — Hooks输入输出JSON Schema的精确实现参考
5. [Stream-JSON Protocol Reference (GitHub)](https://github.com/claudification/claudewerk/blob/main/docs/stream-json-protocol.md) — stream-json输出格式的完整事件类型文档

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