<!-- title: Claude Code自动化实战：-p模式到Hooks全攻略 -->

# Claude Code自动化实战：从-p模式到Hooks全攻略

## 概述

本教程面向已经掌握 Claude Code 基础操作的开发者，系统讲解如何将 Claude Code 从"人机对话工具"升级为"可编程自动化引擎"。你将学会：用 `-p` 模式构建命令行工具链、用 Hooks 实现确定性安全守卫、用子 Agent 编排并行任务、用 GitHub Actions 接入 CI/CD 流水线。学完后，你可以在团队中部署全自动代码审查、安全检查、批量重构等生产级工作流。

**适用人群**：有 3 个月以上 Claude Code 使用经验的开发者、DevOps 工程师、技术团队负责人。

## 前置条件

| 条件 | 说明 |
|------|------|
| Claude Code CLI | 已安装并完成认证（`claude` 命令可用） |
| Node.js 18+ | Claude Code 运行环境 |
| Git 基础 | 了解分支、diff、PR 概念 |
| 基础 Bash | 能编写简单 shell 脚本 |
| Anthropic API Key | 用于非交互模式的 API 调用 |

---

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

### 1.1 核心概念

交互模式（默认）下，Claude Code 是一个 REPL（读取-执行-打印循环），需要人类在终端中逐步引导。而 `-p`（`--print`）模式彻底改变了这个范式：

- **输入**：通过命令行参数或管道接收 prompt
- **执行**：Claude 自主完成工具调用链
- **输出**：将最终结果打印到 stdout 后退出
- **无交互**：全程无需人类介入

这意味着 Claude Code 可以嵌入任何脚本、管道、CI 流水线中，成为一个**可编程的 AI 命令行工具**。

### 1.2 基础用法

```bash
# 最简单的用法：直接传入提示词
claude -p "解释 src/index.ts 的入口函数功能"

# 等价写法
claude --print "解释 src/index.ts 的入口函数功能"
```

**预期输出**：Claude 会读取文件、分析代码，将解释文本输出到终端，然后自动退出。

### 1.3 管道输入——解锁无限可能

管道是 `-p` 模式最强大的用法之一。任何程序的输出都可以成为 Claude 的输入：

```bash
# 将 git diff 传给 Claude 做代码审查
git diff HEAD~3..HEAD | claude -p "审查这些变更，列出潜在的安全问题和性能瓶颈"

# 将测试输出传给 Claude 做错误分析
npm test 2>&1 | claude -p "分析测试失败原因并给出具体修复建议"

# 将日志文件传给 Claude 做故障诊断
tail -100 /var/log/app.log | claude -p "分析最近的错误日志，判断根因"

# 将 JSON API 响应传给 Claude 做数据提取
curl -s https://api.example.com/users | claude -p "提取所有活跃用户的邮箱地址"
```

### 1.4 输出格式控制

通过 `--output-format` 参数控制输出格式，这是接入自动化流水线的关键：

```bash
# 纯文本（默认，适合人类阅读）
claude -p "列出 src/ 目录下所有 API 端点" --output-format text

# JSON 格式（适合程序解析）
claude -p "列出所有 TODO 注释" --output-format json

# 流式 JSON（适合实时监控长任务）
claude -p "重构 src/auth.ts 模块" --output-format stream-json
```

**JSON 输出示例**：
```json
{
  "type": "result",
  "subtype": "success",
  "cost_usd": 0.0342,
  "duration_ms": 4521,
  "duration_api_ms": 3100,
  "num_turns": 3,
  "result": "发现 7 个 TODO 注释：\n1. src/auth.ts:42 - TODO: 添加 token 过期检查..."
}
```

### 1.5 结构化输出——JSON Schema 约束

当你需要 Claude 的输出严格符合某个数据结构时，使用 `--json-schema`：

```bash
claude -p \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "findings": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "file": {"type": "string"},
            "line": {"type": "integer"},
            "severity": {"type": "string", "enum": ["low", "medium", "high"]},
            "description": {"type": "string"}
          },
          "required": ["file", "line", "severity", "description"]
        }
      },
      "summary": {"type": "string"}
    },
    "required": ["findings", "summary"]
  }' \
  "审查当前 git diff，输出所有代码质量问题"
```

**预期输出**：Claude 被强制按照 Schema 输出结构化 JSON，可以直接用 `jq` 解析：

```bash
# 提取高严重性问题
claude -p --output-format json --json-schema '...' "审查代码" | jq '.findings[] | select(.severity == "high")'
```

### 1.6 成本与轮次控制

在自动化场景中，必须防止 Claude 无限循环消耗 token：

```bash
# 限制单次运行费用（美元）
claude -p "重构这个模块" --max-budget-usd 0.50

# 限制 Agent 循环轮次
claude -p "修复所有 lint 错误" --max-turns 10

# 同时限制（双重保险）
claude -p "升级依赖" --max-turns 15 --max-budget-usd 2.00
```

### 1.7 工具权限控制

在非交互模式中，精确控制 Claude 可以使用哪些工具：

```bash
# 只允许读取和搜索（安全审查场景）
claude -p "审查代码安全性" \
  --allowedTools "Read,Glob,Grep"

# 允许执行但禁止危险命令
claude -p "运行测试并修复" \
  --allowedTools "Read,Write,Edit,Bash(npm:*),Bash(node:*)" \
  --disallowedTools "Bash(rm -rf:*)"

# 完全无限制（仅限 Docker/沙箱环境）
claude -p "全面重构" --dangerously-skip-permissions
```

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

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| `-p` 模式下 Claude 不读文件 | 未赋予 Read 工具权限 | 添加 `--allowedTools "Read,Glob,Grep"` |
| 输出被截断 | 达到 `--max-turns` 上限 | 增大轮次限制或优化 prompt |
| JSON 输出格式不对 | 未指定 `--output-format json` | 确保同时使用 `--output-format json` |
| 费用超预期 | 任务复杂度超预估 | 始终设置 `--max-budget-usd` |
| CI 环境中 workspace trust 弹窗 | 非交互模式跳过了信任确认 | 仅在可信目录中运行 |

---

## 第二章：Hooks 生命周期钩子 —— 确定性安全守卫

### 2.1 Hooks 与 CLAUDE.md 的本质区别

很多开发者只用 CLAUDE.md 来告诉 Claude "不要做什么"，但这本质上是一种**建议**——Claude 可能忽略它。Hooks 则是**硬约束**：

| 维度 | CLAUDE.md | Hooks |
|------|-----------|-------|
| 执行保证 | 不保证（AI 可能忽略） | 100% 保证执行 |
| 触发时机 | 被 AI 读取并"理解" | 事件驱动的确定性回调 |
| 可预测性 | 低（依赖 AI 判断） | 高（代码逻辑完全确定） |
| 适用场景 | 行为指导、风格偏好 | 安全策略、强制规范、审计 |

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

```
~/.claude/settings.json          ← 全局（所有项目生效）
.claude/settings.json            ← 项目级（提交到 Git，团队共享）
.claude/settings.local.json      ← 项目本地（不提交 Git，个人定制）
```

**优先级**：项目本地 > 项目级 > 全局。推荐将安全相关的 Hooks 放在 `.claude/settings.json` 中，随代码仓库共享给整个团队。

### 2.3 Hooks 配置结构

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/protect-sensitive.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto-format.sh"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/notify.sh"
          }
        ]
      }
    ]
  }
}
```

### 2.4 三种 Hook 类型

| 类型 | 机制 | 典型场景 |
|------|------|---------|
| `command` | 执行 shell 命令 | 格式化、lint、安全检查 |
| `http` | 发送 HTTP 请求 | Slack/钉钉通知、外部系统集成 |
| `prompt` | 调用 LLM 做复杂决策 | 代码质量评分、合规性审查 |

### 2.5 核心事件类型详解

```mermaid
flowchart TD
    A[SessionStart<br/>会话启动] --> B[UserPromptSubmit<br/>用户提交Prompt]
    B --> C{Claude 决策}
    C -->|调用工具| D[PreToolUse<br/>工具执行前]
    D -->|exit 0| E[工具执行]
    D -->|exit 2| F[❌ 阻止执行]
    E --> G[PostToolUse<br/>工具执行后]
    E -->|失败| H[PostToolUseFailure<br/>执行失败]
    G --> I{还有工具调用?}
    I -->|是| D
    I -->|否| J[Stop<br/>Agent 退出]
    J -->|Stop Hook| K[可注入新 Prompt<br/>Ralph Loop]

    style F fill:#ff6b6b,color:#fff
    style D fill:#ffd93d
    style G fill:#6bcb77
    style K fill:#4d96ff,color:#fff
```

| 事件 | 触发时机 | 能否阻止操作 | 关键用途 |
|------|---------|------------|---------|
| `SessionStart` | 会话启动/恢复 | 否 | 初始化环境、加载配置 |
| `UserPromptSubmit` | 用户提交 prompt 后 | 是 | 输入验证、上下文注入 |
| `PreToolUse` | 工具执行**之前** | **是**（exit 2） | 安全防护、参数校验 |
| `PostToolUse` | 工具执行**之后** | 否 | 自动格式化、审计日志 |
| `PostToolUseFailure` | 工具执行失败 | 否 | 错误告警、自动重试 |
| `Stop` | Agent 准备退出时 | 是 | 注入新 prompt（Ralph Loop） |
| `Notification` | 发送通知时 | 否 | 转发到 IM 工具 |
| `SubagentStart/Stop` | 子 Agent 生命周期 | Stop 可阻止 | 跟踪并行任务 |
| `PreCompact` | 上下文压缩前 | 否 | 归档完整对话记录 |

### 2.6 Matcher 匹配规则

Matcher 是正则表达式，匹配工具名称：

```json
"matcher": "Bash"                    // 精确匹配 Bash 工具
"matcher": "Write|Edit"              // 匹配 Write 或 Edit
"matcher": "Write|Edit|MultiEdit"    // 所有文件写入操作
"matcher": "mcp__github__*"          // 匹配 GitHub MCP 工具
"matcher": ""                        // 空字符串 = 匹配所有
```

### 2.7 Hook 脚本输入输出协议

**输入（stdin JSON）**：

```json
{
  "session_id": "abc123-def456",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/test"
  }
}
```

**Exit Code 语义**：

| Exit Code | 含义 | 行为 |
|-----------|------|------|
| `0` + 无 stderr | 允许继续 | 正常通过 |
| `0` + 有 stderr | 允许但警告 | Agent 看到 stderr 中的反馈 |
| `2` + 有 stderr | **阻止操作** | Agent 收到阻止原因 |

### 2.8 实战案例一：保护敏感文件

创建 `.claude/hooks/protect-sensitive.sh`：

```bash
#!/bin/bash
# 读取 Hook 输入
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 定义敏感文件模式
SENSITIVE_PATTERNS=(".env" "credentials" "secrets" ".pem" ".key" "id_rsa" "private")

# 检查文件路径是否匹配敏感模式
for pattern in "${SENSITIVE_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "🚫 安全策略：禁止修改包含 '$pattern' 的文件：$FILE_PATH" >&2
    exit 2  # 阻止操作
  fi
done

# 允许通过
echo '{}'
exit 0
```

配置注册：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/protect-sensitive.sh"
          }
        ]
      }
    ]
  }
}
```

**预期效果**：当 Claude 尝试编辑 `.env` 文件时，脚本返回 exit 2，操作被阻止，Claude 看到错误信息并改用其他方案。

### 2.9 实战案例二：自动代码格式化

创建 `.claude/hooks/auto-format.sh`：

```bash
#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 根据文件类型选择格式化工具
case "$FILE_PATH" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$FILE_PATH" 2>/dev/null
    echo "✅ Prettier 已格式化: $FILE_PATH" >&2
    ;;
  *.py)
    python -m black "$FILE_PATH" 2>/dev/null
    echo "✅ Black 已格式化: $FILE_PATH" >&2
    ;;
  *.go)
    gofmt -w "$FILE_PATH" 2>/dev/null
    echo "✅ gofmt 已格式化: $FILE_PATH" >&2
    ;;
esac

exit 0  # 格式化不影响操作
```

### 2.10 实战案例三：拦截危险命令

创建 `.claude/hooks/block-dangerous.sh`：

```bash
#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 危险命令模式列表
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "DROP TABLE"
  "drop table"
  "git push --force"
  "chmod 777"
  "> /etc/"
  "mkfs"
  "dd if="
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$CMD" | grep -qiE "$pattern"; then
    echo "🚫 危险命令被拦截: 检测到 '$pattern'" >&2
    echo "完整命令: $CMD" >&2
    exit 2
  fi
done

exit 0
```

配置注册：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/block-dangerous.sh"
          }
        ]
      }
    ]
  }
}
```

### 2.11 HTTP Hook：Slack/钉钉通知

无需编写脚本，直接配置 HTTP 请求：

```json
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
            "method": "POST",
            "headers": {
              "Content-Type": "application/json"
            }
          }
        ]
      }
    ]
  }
}
```

### 2.12 Stop Hook 与 Ralph Loop

Stop Hook 是最强大的 Hook 类型之一——当 Agent 想要退出时，你可以拦截退出并注入新的 prompt，让 Agent 持续工作：

```bash
#!/bin/bash
# .claude/hooks/ralph-loop.sh
INPUT=$(cat)

# 检查是否已经完成
if [ -f "TASK_COMPLETE.marker" ]; then
  exit 0  # 允许退出
fi

# 检查迭代次数
ITERATIONS=$(cat .claude/iteration-count 2>/dev/null || echo "0")
if [ "$ITERATIONS" -ge 20 ]; then
  exit 0  # 安全阀：最多 20 轮
fi

# 注入新 prompt，让 Agent 继续
NEW_ITERATIONS=$((ITERATIONS + 1))
echo "$NEW_ITERATIONS" > .claude/iteration-count
echo "继续工作。当前进度: 第 ${NEW_ITERATIONS} 次迭代。" >&2
exit 2  # 阻止退出，Agent 收到 stderr 反馈后继续
```

**应用场景**：大规模代码迁移、批量 bug 修复、长期运行的研究任务。

---

## 第三章：子 Agent 与并行调度

### 3.1 为什么需要子 Agent

在大型任务中，单个 Agent 的上下文窗口会成为瓶颈。子 Agent 的核心价值：

1. **上下文隔离**：子 Agent 的探索不污染父 Agent 的上下文
2. **并行执行**：多个子 Agent 同时运行，大幅缩短耗时
3. **模型路由**：简单任务用 Haiku（低成本），复杂任务用 Sonnet（高质量）
4. **权限隔离**：子 Agent 可以限制为只读，防止意外修改

### 3.2 内置子 Agent 类型

| 子 Agent | 默认模型 | 工具权限 | 最佳用途 |
|----------|---------|---------|---------|
| Explore | Haiku（快速低成本） | 只读 | 代码搜索、文件发现、命名模式扫描 |
| Plan | 继承父会话 | 只读 | 架构研究、方案设计 |
| General-purpose | 继承父会话 | 全部工具 | 复杂多步骤任务 |
| claude-code-guide | Haiku | 只读 | Claude Code 使用帮助 |

**Explore 深度级别**：
- `quick`：快速扫描，5-10 秒出结果
- `medium`：适度探索，30 秒左右
- `very thorough`：深度搜索，适合大型代码库

### 3.3 自定义子 Agent

在 `.claude/agents/` 目录下创建 Markdown 文件定义自定义子 Agent：

```markdown
---
name: security-auditor
description: 安全审计专家，检测 OWASP Top 10 漏洞
model: claude-haiku-4-5
tools:
  - Read
  - Glob
  - Grep
---

你是一位专业的安全审计员。扫描代码中的以下漏洞类型：

1. SQL 注入（未参数化的查询）
2. XSS（未转义的用户输入）
3. 硬编码密钥和凭证
4. 不安全的反序列化
5. 路径遍历

输出格式：
- 文件路径:行号
- 漏洞类型
- 严重程度（高/中/低）
- 修复建议
```

保存到 `.claude/agents/security-auditor.md` 后，Claude 会自动识别并在适当场景中调用。

### 3.4 并行模式三种范式

```mermaid
flowchart TB
    subgraph Fan-out["Fan-out 扇出模式"]
        FO_Parent[父 Agent] --> FO_A1[Agent 1: 安全审查]
        FO_Parent --> FO_A2[Agent 2: 性能分析]
        FO_Parent --> FO_A3[Agent 3: 风格检查]
        FO_Parent --> FO_A4[Agent 4: 可维护性]
        FO_A1 & FO_A2 & FO_A3 & FO_A4 --> FO_Synthesis[结果汇总]
    end

    subgraph Pipeline["Pipeline 管道模式"]
        PL_Explore[探索] --> PL_Design[设计]
        PL_Design --> PL_Implement[实现]
        PL_Implement --> PL_Verify[验证]
    end

    subgraph MapReduce["Map-Reduce 模式"]
        MR_Input[输入: 50个文件] --> MR_M1[Agent: 文件1-10]
        MR_Input --> MR_M2[Agent: 文件11-20]
        MR_Input --> MR_M3[Agent: 文件21-30]
        MR_Input --> MR_M4[Agent: 文件31-40]
        MR_Input --> MR_M5[Agent: 文件41-50]
        MR_M1 & MR_M2 & MR_M3 & MR_M4 & MR_M5 --> MR_Reduce[聚合去重]
    end

    style Fan-out fill:#e8f5e9
    style Pipeline fill:#e3f2fd
    style MapReduce fill:#fff3e0
```

**Fan-out（扇出）**：同一个任务，多角度并行分析。适合代码审查、风险评估。

**Pipeline（管道）**：串行依赖，逐步深化。适合"探索→设计→实现→验证"的开发流程。

**Map-Reduce（映射归约）**：大规模批量任务。适合全代码库迁移、批量重构。

### 3.5 成本控制策略

| 策略 | 做法 | 预期效果 |
|------|------|---------|
| 模型路由 | 探索用 Haiku，实现用 Sonnet | 成本降低 60-80% |
| 限制工具 | 只读子 Agent 禁止 Write/Edit | 避免意外修改 |
| 精简提示 | 子 Agent 提示控制在 100-300 字 | 减少 input token 消耗 |
| 控制并发 | API Tier 1 最多 5 个并发 Agent | 避免排队和超时 |

---

## 第四章：CI/CD 集成实战

### 4.1 GitHub Actions 自动代码审查

这是一个完整的、可直接使用的 GitHub Actions 工作流：

```yaml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 获取完整历史，diff 才准确
      
      - 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: |
          # 获取变更文件列表和 diff
          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)
          DIFF=$(git diff origin/main...HEAD)
          
          # 使用 -p 模式运行审查
          claude -p "你是一位高级代码审查员。审查以下变更：
          
          变更文件：
          ${CHANGED_FILES}
          
          Diff 内容：
          ${DIFF}
          
          请从以下维度审查：
          1. 代码正确性（逻辑错误、边界条件）
          2. 安全漏洞（注入、XSS、信息泄露）
          3. 性能问题（N+1 查询、内存泄漏）
          4. 可维护性（命名、注释、复杂度）
          
          用中文输出，按严重程度排序。" \
          --output-format text \
          --allowedTools "Read,Glob,Grep" \
          --max-turns 5 \
          --max-budget-usd 1.00 \
          > review_output.md
      
      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const review = require('fs').readFileSync('review_output.md', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🤖 Claude Code Review\n\n${review}`
            });
```

**预期效果**：每次创建或更新 PR 时，Claude 自动审查代码并将结果作为 PR 评论发布。

### 4.2 自动 Issue 处理

当 Issue 被标记为 `claude-fix` 时，自动创建修复 PR：

```yaml
name: Claude Auto Fix
on:
  issues:
    types: [labeled]

jobs:
  auto-fix:
    if: github.event.label.name == 'claude-fix'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      
      - name: Process Issue
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          ISSUE_TITLE: ${{ github.event.issue.title }}
          ISSUE_BODY: ${{ github.event.issue.body }}
          ISSUE_NUMBER: ${{ github.event.issue.number }}
        run: |
          # 创建修复分支
          git checkout -b "fix/issue-${ISSUE_NUMBER}"
          
          # 让 Claude 分析并修复
          claude -p \
            --max-turns 15 \
            --max-budget-usd 3.00 \
            --dangerously-skip-permissions \
            "GitHub Issue #${ISSUE_NUMBER}: ${ISSUE_TITLE}
          
          问题描述：
          ${ISSUE_BODY}
          
          请分析这个 Issue，定位相关代码文件，实现修复，确保代码通过测试。"
      
      - name: Create Pull Request
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git add -A
          git commit -m "fix: resolve #${{ github.event.issue.number }} — ${{ github.event.issue.title }}"
          git push origin "fix/issue-${{ github.event.issue.number }}"
          gh pr create \
            --title "fix: #${{ github.event.issue.number }} — ${{ github.event.issue.title }}" \
            --body "自动修复 Issue #${{ github.event.issue.number }}" \
            --label "auto-generated"
```

### 4.3 CI/CD 安全最佳实践

```mermaid
flowchart LR
    A[CI/CD 安全层级] --> B[1. 工具白名单<br/>--allowedTools]
    A --> C[2. 费用上限<br/>--max-budget-usd]
    A --> D[3. 轮次上限<br/>--max-turns]
    A --> E[4. 环境隔离<br/>Docker 容器]
    A --> F[5. 禁用遥测<br/>CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC]

    B --> G[✅ 安全的自动化]
    C --> G
    D --> G
    E --> G
    F --> G
```

| 安全措施 | 配置方式 | 必要性 |
|----------|----------|-------|
| 限制工具 | `--allowedTools "Read,Glob,Grep"` | **必须**：防止 Agent 修改代码 |
| 费用上限 | `--max-budget-usd 2.00` | **必须**：防止循环导致费用暴增 |
| 轮次上限 | `--max-turns 5` | **必须**：防止 Agent 无限循环 |
| 环境变量 | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | 推荐：CI 环境不需要遥测 |
| 沙箱执行 | Docker 容器 | 推荐：隔离文件系统和网络 |
| 只读文件系统 | `--allowedTools` 不含 Write/Edit | 推荐：审查场景 |

---

## 第五章：实战项目——构建全自动代码质量门禁

### 5.1 项目目标

构建一个完整的自动化系统，在每次 Git 提交时自动执行：
1. 代码格式化（Prettier/Black）
2. 安全漏洞扫描
3. AI 代码审查
4. 自动发布审查报告

### 5.2 项目结构

```
my-project/
├── .claude/
│   ├── settings.json          # Hooks 配置
│   ├── hooks/
│   │   ├── auto-format.sh     # 自动格式化
│   │   ├── block-sensitive.sh # 敏感文件保护
│   │   └── block-dangerous.sh # 危险命令拦截
│   └── agents/
│       └── security-auditor.md
├── .github/
│   └── workflows/
│       └── claude-review.yml  # CI/CD 工作流
├── scripts/
│   └── quality-gate.sh        # 本地质量门禁脚本
└── src/
    └── ...
```

### 5.3 步骤一：配置 Hooks 安全层

创建 `.claude/settings.json`：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/block-sensitive.sh"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/block-dangerous.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto-format.sh"
          }
        ]
      }
    ]
  }
}
```

### 5.4 步骤二：创建本地质量门禁脚本

创建 `scripts/quality-gate.sh`：

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

echo "🔍 Claude Code 质量门禁"
echo "========================"

# 获取变更文件
CHANGED_FILES=$(git diff --name-only --cached)
if [ -z "$CHANGED_FILES" ]; then
  echo "✅ 没有暂存的变更，跳过审查。"
  exit 0
fi

echo "📝 待审查文件："
echo "$CHANGED_FILES"
echo ""

# 阶段 1: 安全扫描
echo "🔒 阶段 1/3: 安全漏洞扫描..."
SECURITY_RESULT=$(echo "$CHANGED_FILES" | claude -p \
  --output-format json \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 3 \
  --max-budget-usd 0.50 \
  --json-schema '{
    "type": "object",
    "properties": {
      "vulnerabilities": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "file": {"type": "string"},
            "line": {"type": "integer"},
            "type": {"type": "string"},
            "severity": {"type": "string", "enum": ["low", "medium", "high", "critical"]}
          }
        }
      },
      "passed": {"type": "boolean"}
    },
    "required": ["vulnerabilities", "passed"]
  }' \
  "扫描以下文件中的安全漏洞（SQL注入、XSS、硬编码密钥等）：$(echo "$CHANGED_FILES" | tr '\n' ' ')")

PASSED=$(echo "$SECURITY_RESULT" | jq -r '.passed')
if [ "$PASSED" != "true" ]; then
  echo "❌ 安全扫描未通过！"
  echo "$SECURITY_RESULT" | jq '.vulnerabilities[]'
  exit 1
fi
echo "✅ 安全扫描通过"

# 阶段 2: 代码质量审查
echo "📐 阶段 2/3: 代码质量审查..."
DIFF=$(git diff --cached)
claude -p \
  --output-format text \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 3 \
  --max-budget-usd 0.50 \
  "用简洁的中文审查以下 diff 的代码质量。只列出严重问题，忽略风格偏好：
  
  $DIFF" | tee .claude/review-output.md

# 阶段 3: 统计
echo ""
echo "📊 阶段 3/3: 审查统计"
echo "变更文件数: $(echo "$CHANGED_FILES" | wc -l)"
echo "审查报告: .claude/review-output.md"
echo ""
echo "✅ 质量门禁完成！"
```

### 5.5 步骤三：设置 Git Pre-commit Hook

```bash
# 在项目根目录执行
chmod +x scripts/quality-gate.sh
ln -sf ../../scripts/quality-gate.sh .git/hooks/pre-commit
```

**预期效果**：每次 `git commit` 时自动触发 AI 质量审查。如果安全扫描发现高危漏洞，commit 会被阻止。

### 5.6 步骤四：配置 CI/CD 自动审查

将第四章的 GitHub Actions 配置放入 `.github/workflows/claude-review.yml`，实现 PR 级别的自动化审查。

### 5.7 完整工作流架构

```mermaid
flowchart TD
    A[开发者 git commit] --> B{Pre-commit Hook}
    B -->|安全扫描| C{有高危漏洞?}
    C -->|是| D[❌ 阻止 Commit]
    C -->|否| E[✅ Commit 成功]
    E --> F[git push]
    F --> G[创建 Pull Request]
    G --> H[GitHub Actions 触发]
    H --> I[Claude -p 模式审查]
    I --> J[结构化审查报告]
    J --> K[发布 PR 评论]
    K --> L[团队评审 & 合并]

    M[Claude Code 交互模式] --> N{Hooks 守卫}
    N -->|PreToolUse| O[敏感文件保护]
    N -->|PreToolUse| P[危险命令拦截]
    N -->|PostToolUse| Q[自动格式化]

    style D fill:#ff6b6b,color:#fff
    style E fill:#6bcb77,color:#fff
    style J fill:#4d96ff,color:#fff
```

---

## 第六章：批量任务与高级编排

### 6.1 多仓库批量操作

```bash
#!/bin/bash
# batch-upgrade.sh - 批量升级多个仓库的依赖
REPOS=("api-gateway" "user-service" "payment-service" "notification-service")

for repo in "${REPOS[@]}"; do
  echo "🔄 处理仓库: $repo"
  cd "/projects/$repo"
  
  claude -p \
    --max-turns 15 \
    --max-budget-usd 2.00 \
    --dangerously-skip-permissions \
    "将所有 npm 依赖升级到最新的稳定版本。确保不引入 breaking changes。运行测试确认一切正常。"
  
  echo "✅ $repo 处理完成"
done
```

### 6.2 Agent 循环模式

对于复杂任务，使用"循环-检查-继续"模式：

```bash
#!/bin/bash
# agent-loop.sh - 持续迭代直到任务完成
MAX_ITERATIONS=10
TASK_FILE="AGENT_TASK.md"

cat > "$TASK_FILE" << 'EOF'
# 任务：将所有 class 组件转换为函数组件
## 进度：0%
## 已完成：无
## 剩余：全部
EOF

for i in $(seq 1 $MAX_ITERATIONS); do
  echo "🔄 迭代 $i/$MAX_ITERATIONS"
  
  RESULT=$(claude -p \
    --max-turns 20 \
    --max-budget-usd 1.00 \
    "阅读 $TASK_FILE 了解任务和当前进度。
    转换下一个 class 组件为函数组件。
    更新 $TASK_FILE 中的进度。
    如果所有组件已转换完毕，在最后一行输出 TASK_COMPLETE。")
  
  if echo "$RESULT" | grep -q "TASK_COMPLETE"; then
    echo "✅ 任务完成！"
    break
  fi
  
  if echo "$RESULT" | grep -q "TASK_BLOCKED"; then
    echo "⚠️ 任务受阻，需要人工介入。"
    break
  fi
done
```

### 6.3 定时任务

Claude Code 内置了 `/loop` 命令用于定时任务：

```bash
# 每 5 分钟检查部署状态
/loop 5m check if the deployment finished

# 动态间隔（Claude 智能选择间隔）
/loop check whether CI passed
```

也可以通过 CronCreate API 创建持久化定时任务：

```javascript
CronCreate({
  cron: "57 8 * * 1-5",    // 工作日 8:57
  prompt: "检查未处理的 PR 并生成摘要",
  recurring: true,
  durable: true            // 持久化，重启后恢复
})
```

> **注意**：所有循环任务 7 天后自动过期。长期运行的任务需要手动续期。

---

## 第七章：权限模式深度解析

### 7.1 五种权限模式

```bash
# plan 模式：只规划不执行，适合架构评审
claude -p --permission-mode plan "分析这个微服务架构的问题"

# auto 模式：自动处理大部分权限请求，适合受信任脚本
claude -p --permission-mode auto "升级依赖并运行测试"

# dontAsk 模式：不询问直接执行，仅在沙箱中使用
claude -p --permission-mode dontAsk "全面重构代码"

# bypassPermissions 模式：绕过权限检查
claude -p --permission-mode bypassPermissions "执行迁移"

# default 模式：正常交互式权限确认（默认值）
claude -p --permission-mode default "修复 bug"
```

### 7.2 settings.json 权限配置

```json
{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(npx:*)",
      "Bash(node:*)",
      "Bash(jest:*)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)",
      "Bash(curl|wget:*)"
    ]
  }
}
```

### 7.3 安全层级总览

```mermaid
flowchart TD
    A[用户发起操作] --> B{1. 权限白名单<br/>permissions.allow/deny}
    B -->|deny 列表| C[❌ 直接拒绝]
    B -->|allow 列表| D{2. PreToolUse Hooks}
    B -->|未匹配| D
    D -->|exit 2| E[❌ Hook 拦截]
    D -->|exit 0| F{3. Claude 自主判断<br/>AI 安全评估}
    F -->|风险过高| G[❌ Claude 拒绝]
    F -->|安全| H[✅ 执行操作]
    D -->|exit 0 + stderr| I[⚠️ 警告但允许]
    I --> F

    style C fill:#ff6b6b,color:#fff
    style E fill:#ff6b6b,color:#fff
    style G fill:#ffd93d
    style H fill:#6bcb77,color:#fff
    style I fill:#ffd93d
```

---

## 第八章：调试与故障排查

### 8.1 调试技巧

```bash
# 启用调试日志
claude -p "任务描述" --debug-file ./claude-debug.log

# 查看 Hook 输入输出
CLAUDE_CODE_DEBUG_HOOKS=1 claude -p "任务描述"

# 查看工具调用链（stream-json 模式）
claude -p "任务描述" --output-format stream-json | jq '.type'
```

### 8.2 常见问题速查表

| 现象 | 可能原因 | 排查方法 |
|------|---------|---------|
| Hook 未触发 | matcher 不匹配 | 检查工具名大小写和正则 |
| Hook 触发但无效 | exit code 不对 | 用 `echo $?` 检查脚本退出码 |
| `-p` 模式无输出 | 费用/轮次超限 | 检查 `--max-budget-usd` 和 `--max-turns` |
| JSON Schema 不生效 | 格式错误 | 用 `jq` 验证 Schema JSON |
| Agent 循环不停止 | 无终止条件 | 添加 `--max-turns` 和 `--max-budget-usd` |
| CI 中 workspace trust 弹窗 | 目录未标记为信任 | 使用 `--dangerously-skip-permissions` |
| 子 Agent 超时 | 任务过于复杂 | 拆分任务或增大预算 |

---

## 延伸阅读

- [Claude Code 官方文档 - CLI 使用](https://docs.anthropic.com/en/docs/claude-code/cli-usage) — Anthropic 官方 CLI 参数完整参考
- [Claude Code 官方文档 - Hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) — Hooks 事件类型与配置详解
- [Claude Code 子 Agent 文档](https://code.claude.com/docs/en/sub-agents) — 子 Agent 类型与自定义方法
- [awesome-claude-code-hooks](https://github.com/ithiria894/awesome-claude-code-hooks) — 社区维护的 Hooks 示例集合
- [Continuous Claude](https://github.com/AnandChowdhary/continuous-claude) — 开源的 Claude Code 持续循环框架

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | 企业 AI 工程师培训、DevOps 自动化训练营、高级开发者工作坊 |
| **前置要求** | 已掌握 Claude Code 基础操作（安装、对话、文件读写） |
| **预计教学时长** | 4-6 小时（含实操练习） |
| **实操占比** | 60%（建议学员自带项目，边学边配置） |
| **难度等级** | ⭐⭐⭐⭐（高级，需要 shell 脚本和 CI/CD 基础） |
| **最佳分组** | 2-3 人一组，每组一个真实项目 |

## 参考来源

1. [Claude Code CLI Usage - Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/cli-usage) — `-p` 模式、输出格式、权限控制完整参考
2. [Claude Code Hooks - Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/hooks) — Hooks 事件类型、配置结构、matcher 规则
3. [Claude Code Sub-agents 文档](https://code.claude.com/docs/en/sub-agents) — 子 Agent 类型、自定义方法、并行模式
4. [awesome-claude-code-hooks - GitHub](https://github.com/ithiria894/awesome-claude-code-hooks) — 社区维护的 Hooks 最佳实践集合
5. [Continuous Claude - GitHub](https://github.com/AnandChowdhary/continuous-claude) — Agent 循环框架与持续集成模式

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