<!-- title: Claude Code自动化：Agent模式完全指南 -->

# Claude Code 自动化：Agent 模式与 -p 模式、Hooks、批量任务完全指南

## 概述

本教程面向已经熟悉 Claude Code 基础用法的开发者，深入讲解三大自动化核心能力：**Headless 模式（-p 模式）**、**Hooks 事件系统**、**子 Agent 并行调度与批量任务**。学完本教程，你将掌握将 Claude Code 嵌入 CI/CD 管道、编写事件驱动的安全防护、以及用循环 Agent 完成大规模自动化项目的全部技能。

**适用人群**：有一定 Claude Code 使用经验，希望提升自动化水平的后端/DevOps/全栈开发者。

## 前置条件

| 条件 | 说明 |
|------|------|
| Claude Code ≥ 1.0 | `claude --version` 确认 |
| Node.js ≥ 18 | Hooks 脚本运行环境 |
| Python ≥ 3.8（可选） | 复杂 Hooks 脚本需要 |
| Git + GitHub CLI | CI/CD 集成和 PR 自动化 |
| 基础 Shell 脚本能力 | 编写自动化循环和批处理 |

---

## 第一章：Headless 模式 —— 非交互式运行 Claude Code

### 1.1 核心概念

`-p`（`--print`）标志是 Claude Code 自动化的基石。它让 Claude Code 脱离交互式 REPL，接收一条 prompt、执行、输出结果后退出。本质上，它把 Claude Code 从一个对话工具变成了一个可编程的命令行工具。

```text
flowchart LR
    A[Shell 脚本 / CI Pipeline] -->|claude -p "prompt"| B[Claude Code Headless]
    B --> C{工具调用}
    C -->|FileRead| D[读取文件]
    C -->|Bash| E[执行命令]
    C -->|Grep/Glob| F[搜索代码]
    C -->|Edit/Write| G[修改文件]
    D & E & F & G --> B
    B -->|stdout| H[结构化输出 JSON/Text]
    H --> A
```

### 1.2 基础用法

```bash
# 最简单的用法：传入 prompt，获取文本输出
claude -p "解释 src/auth.ts 文件的核心逻辑"

# 通过管道传入内容
echo "为以下代码写单元测试：$(cat src/utils.py)" | claude -p

# 获取 JSON 格式输出，方便程序解析
claude -p --output-format json "列出 src/ 目录下所有 TODO 注释"

# 流式 JSON 输出（适合实时处理）
claude -p --output-format stream-json "重构 src/api/ 下的错误处理"
```

### 1.3 关键 CLI 参数一览

| 参数 | 作用 | 示例 |
|------|------|------|
| `-p` / `--print` | 非交互模式，输出后退出 | `claude -p "task"` |
| `--output-format` | 输出格式：`text` / `json` / `stream-json` | `--output-format json` |
| `--allowedTools` | 限制可用工具，降低风险 | `--allowedTools "FileRead,Grep,Glob"` |
| `--max-turns` | 限制 Agent 循环轮次 | `--max-turns 5` |
| `--max-budget-usd` | 设置单次运行费用上限 | `--max-budget-usd 1.00` |
| `--model` | 指定使用的模型 | `--model claude-haiku-4-5-20251001` |
| `--system-prompt` | 注入系统级指令 | `--system-prompt "你是一个代码审查专家"` |
| `--dangerously-skip-permissions` | 跳过所有权限确认（仅限沙箱环境） | 仅在 CI/Docker 中使用 |

### 1.4 实战：自动化代码审查脚本

```bash
#!/bin/bash
# auto-review.sh — 对比 main 分支，自动审查当前分支的变更

set -euo pipefail

DIFF=$(git diff main...HEAD --stat)
if [ -z "$DIFF" ]; then
  echo "没有发现与 main 分支的差异"
  exit 0
fi

echo "=== 开始自动代码审查 ==="

claude -p \
  --max-turns 3 \
  --allowedTools "FileRead,Grep,Glob" \
  --output-format text \
  --system-prompt "你是一位资深代码审查专家。审查时请关注：
1. 潜在的 Bug 和边界情况
2. 安全漏洞（注入、XSS、硬编码密钥）
3. 性能问题
4. 代码风格一致性
请用中文回复，每个问题给出严重级别（高/中/低）和修复建议。" \
  "请审查当前分支相对于 main 的所有代码变更：$(git diff main...HEAD)"
```

运行方式：

```bash
chmod +x auto-review.sh
./auto-review.sh
```

### 1.5 实战：JSON 输出 + 程序化处理

```bash
#!/bin/bash
# find-tech-debt.sh — 自动发现技术债务并生成报告

RESULT=$(claude -p \
  --max-turns 4 \
  --allowedTools "FileRead,Grep,Glob" \
  --output-format json \
  "扫描整个项目，找出以下技术债务：
  1. 含有 TODO/FIXME/HACK 注释的代码
  2. 超过 300 行的函数
  3. 重复代码模式
  4. 缺少错误处理的异步函数
  以 JSON 格式输出结果，按严重程度排序。")

# 提取结果消息
echo "$RESULT" | jq -r '.result' > tech-debt-report.json
echo "报告已保存到 tech-debt-report.json"

# 可选：发送到 Slack
# jq -r '.result' tech-debt-report.json | slack-cli post --channel eng-alerts
```

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

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 脚本挂起无输出 | Claude 等待权限确认 | 添加 `--allowedTools` 限制工具，或确认权限已授权 |
| API 费用超预期 | Agent 循环过多 | 设置 `--max-turns` 和 `--max-budget-usd` |
| JSON 解析失败 | 输出包含非 JSON 内容 | 使用 `--output-format json` 确保格式正确 |
| 权限被拒绝 | 工具未授权 | 在 `.claude/settings.json` 中预授权所需工具 |

---

## 第二章：Hooks 事件系统 —— 为 Claude Code 添加"条件反射"

### 2.1 什么是 Hooks

Hooks 是 Claude Code 的可编程事件响应机制。你可以在特定事件发生时（如工具调用前、会话开始时、Agent 停止时）自动执行自定义脚本。可以把它理解为 Claude Code 的"中间件层"——在不修改 Claude Code 核心逻辑的前提下，注入自定义行为。


![图表2](images/claude-code-tutorial-r4-1729-mermaid-1.png)

> *图表 2*


### 2.2 Hook 事件类型

截至 2026 年初，Claude Code 支持 17+ 种 Hook 事件。以下是核心事件分类：

| 事件 | 触发时机 | 典型用途 |
|------|----------|----------|
| `PreToolUse` | 工具调用**之前** | 安全拦截、输入验证、日志记录 |
| `PostToolUse` | 工具调用**之后** | 自动格式化、通知、统计 |
| `SessionStart` | 会话启动时 | 加载项目配置、注入上下文 |
| `Stop` | Agent 准备退出时 | 循环拦截（Ralph Loop）、总结报告 |
| `SubagentStop` | 子 Agent 完成时 | 汇总子 Agent 结果 |
| `Notification` | 系统通知时 | 转发到 Slack/邮件 |

### 2.3 Hook 配置结构

Hook 在 `.claude/settings.json`（项目级）或 `~/.claude/settings.json`（全局级）中配置：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/pre_bash.py"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/pre_edit.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '项目规范已加载：请遵循 CLAUDE.md 中的编码规范'"
          }
        ]
      }
    ]
  }
}
```

### 2.4 Hook 脚本的输入输出协议

Hook 脚本通过 **stdin** 接收 JSON 输入，通过 **exit code** 控制行为：

**输入格式**（stdin JSON）：

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

**Exit Code 语义**：

| Exit Code | 含义 | 适用场景 |
|-----------|------|----------|
| `0` | 允许继续，无额外信息 | 正常放行 |
| `0` + stderr 输出 | 允许继续，但向 Agent 显示反馈 | 警告提示 |
| `2` | 阻止操作，显示 stderr 中的消息 | 安全拦截 |

### 2.5 实战：危险命令拦截 Hook

创建 `.claude/hooks/pre_bash.py`：

```python
#!/usr/bin/env python3
"""PreToolUse Hook: 拦截危险的 Bash 命令"""
import json
import sys
import re

def is_dangerous(command):
    normalized = ' '.join(command.lower().split())
    
    # 检测 rm -rf 及其变体
    dangerous_patterns = [
        r'\brm\s+.*-[a-z]*r[a-z]*f',
        r'\brm\s+.*-[a-z]*f[a-z]*r',
        r'\brm\s+--recursive\s+--force',
    ]
    
    # 检测危险路径
    dangerous_targets = ['/', '/*', '~', '$HOME', '..']
    
    for pattern in dangerous_patterns:
        if re.search(pattern, normalized):
            for target in dangerous_targets:
                if re.search(re.escape(target), normalized):
                    return True
    return False

def is_env_access(command):
    """检测对 .env 文件的访问"""
    env_patterns = [
        r'\bcat\s+.*\.env\b',
        r'\becho\s+.*>\s*\.env\b',
        r'\btouch\s+.*\.env\b',
    ]
    for pattern in env_patterns:
        if re.search(pattern, command):
            return True
    return False

# 读取 Hook 输入
data = json.load(sys.stdin)
tool_name = data.get("tool_name", "")
tool_input = data.get("tool_input", {})

if tool_name == "Bash":
    command = tool_input.get("command", "")
    
    if is_dangerous(command):
        print("⛔ 安全拦截：检测到危险的 rm 命令。请确认操作目标后手动执行。", file=sys.stderr)
        sys.exit(2)
    
    if is_env_access(command):
        print("⚠️ 警告：正在访问 .env 文件，请确保不会泄露敏感信息。", file=sys.stderr)
        sys.exit(0)  # 允许但警告

sys.exit(0)  # 正常放行
```

在 `.claude/settings.json` 中注册：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/pre_bash.py"
          }
        ]
      }
    ]
  }
}
```

### 2.6 实战：PostToolUse 自动格式化 Hook

每次 Claude 编辑代码文件后自动运行 Prettier 和 ESLint：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto_format.sh"
          }
        ]
      }
    ]
  }
}
```

`.claude/hooks/auto_format.sh`：

```bash
#!/bin/bash
# 自动格式化 Hook：在 Claude 编辑文件后运行

# 从 stdin 读取 Hook 数据
DATA=$(cat)
FILE_PATH=$(echo "$DATA" | jq -r '.tool_input.file_path // empty')

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

# 根据文件扩展名选择格式化工具
case "$FILE_PATH" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$FILE_PATH" 2>/dev/null
    npx eslint --fix "$FILE_PATH" 2>/dev/null
    ;;
  *.py)
    python3 -m black "$FILE_PATH" 2>/dev/null
    python3 -m isort "$FILE_PATH" 2>/dev/null
    ;;
  *.go)
    gofmt -w "$FILE_PATH" 2>/dev/null
    ;;
esac

# 输出反馈给 Agent
echo "✅ 已自动格式化: $FILE_PATH" >&2
exit 0
```

### 2.7 实战：SessionStart Hook —— 注入项目上下文

```bash
#!/bin/bash
# .claude/hooks/session_start.sh
# 在每次会话开始时向 Agent 注入项目规范

echo "📋 项目规范提醒：
- 本项目使用 TypeScript 严格模式
- 所有 API 端点必须有输入验证
- 提交前确保测试通过
- 数据库迁移使用 Drizzle ORM
- 禁止使用 any 类型" >&2

exit 0
```

### 2.8 Stop Hook 的妙用：Ralph Loop

Stop Hook 最强大的用途是创建 **自循环 Agent**——当 Claude 想退出时，Hook 拦截退出并注入新的 prompt，让 Agent 持续工作直到满足条件。这就是 Claude Code 官方 `ralph-wiggum` 插件的核心原理：


![图表3](images/claude-code-tutorial-r4-1729-mermaid-2.png)

> *图表 3*


官方 Ralph Wiggum 插件的 Stop Hook 核心逻辑：

```bash
#!/bin/bash
# hooks/stop-hook.sh — Ralph Loop 的核心

DATA=$(cat)
RESULT=$(echo "$DATA" | jq -r '.result // empty')
COMPLETION_PROMISE="COMPLETE"
MAX_ITERATIONS=50

# 检查是否包含完成信号
if echo "$RESULT" | grep -q "$COMPLETION_PROMISE"; then
  echo "🎉 任务完成！" >&2
  exit 0  # 允许退出
fi

# 检查迭代次数
ITERATION_FILE="/tmp/ralph_iteration"
CURRENT=$(cat "$ITERATION_FILE" 2>/dev/null || echo "0")
CURRENT=$((CURRENT + 1))
echo "$CURRENT" > "$ITERATION_FILE"

if [ "$CURRENT" -ge "$MAX_ITERATIONS" ]; then
  echo "⏰ 达到最大迭代次数 ($MAX_ITERATIONS)，退出循环。" >&2
  exit 0
fi

# 注入 prompt 继续循环
echo "⏳ 第 $CURRENT/$MAX_ITERATIONS 次迭代。继续工作..." >&2
PROMPT=$(cat /tmp/ralph_prompt)
echo "$PROMPT" >&2  # 将 prompt 输出到 stderr，Agent 会看到

exit 0
```

---

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

### 3.1 子 Agent 架构

Claude Code 的 Task 工具允许主 Agent 派遣专门的子 Agent 并行处理独立任务。每个子 Agent 拥有独立的上下文窗口，不会污染主对话的历史记录。


![图表4](images/claude-code-tutorial-r4-1729-mermaid-3.png)

> *图表 4*


### 3.2 内置子 Agent 类型

| 类型 | 用途 | 可用工具 |
|------|------|----------|
| `general-purpose` | 通用研究、多步骤任务 | 全部工具 |
| `Explore` | 快速代码库搜索 | 只读工具（不可编辑） |
| `Plan` | 架构设计、实现规划 | 只读工具（不可编辑） |

### 3.3 自定义子 Agent

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

```markdown
<!-- .claude/agents/security-scanner.md -->
---
name: security-scanner
description: 专门扫描代码中的安全漏洞
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: claude-haiku-4-5-20251001
---

你是一位安全审计专家。你的任务是：

1. 扫描给定目录下的所有源代码文件
2. 检查以下安全漏洞：
   - SQL 注入
   - XSS 跨站脚本
   - 命令注入
   - 硬编码密钥/密码
   - 不安全的反序列化
3. 对每个发现的问题，给出：
   - 文件路径和行号
   - 严重级别（严重/高/中/低）
   - 修复建议

输出格式为 Markdown 表格。
```

使用时在对话中通过 Task 工具调用，或直接在 prompt 中提及该子 Agent。

### 3.4 并行子 Agent 的调度模式

**模式一：Fan-out（扇出）**—— 同一任务，多角度分析


![图表5](images/claude-code-tutorial-r4-1729-mermaid-4.png)

> *图表 5*


这正是官方 `code-review` 插件的工作方式——启动 4 个并行 Agent 独立审查 PR，每个 Agent 从不同角度分析，然后用置信度评分过滤掉误报（低于 80 分的直接丢弃），最终只输出高置信度的审查意见。

**模式二：Pipeline（管道）**—— 串行依赖，逐步深化


![图表6](images/claude-code-tutorial-r4-1729-mermaid-5.png)

> *图表 6*


官方 `feature-dev` 插件采用这种模式：先探索代码库，再设计方案，最后实现。

**模式三：Map-Reduce（映射归约）**—— 大规模批量任务


![图表7](images/claude-code-tutorial-r4-1729-mermaid-6.png)

> *图表 7*


### 3.5 实战：并行子 Agent 批量重构

假设你需要将项目中所有 API 端点添加输入验证。可以创建一个自定义 Agent 并在主会话中批量调度：

```markdown
<!-- .claude/agents/validation-adder.md -->
---
name: validation-adder
description: 为单个 API 端点文件添加输入验证
tools:
  - Read
  - Edit
  - Grep
  - Glob
model: claude-sonnet-4-6
---

你是一个代码重构专家。给定一个 API 路由文件，你需要：

1. 读取文件内容
2. 找到所有没有输入验证的端点
3. 使用 zod schema 添加请求体验证
4. 添加适当的错误处理中间件
5. 确保不破坏现有功能

项目使用的技术栈：Express.js + TypeScript + zod
```

然后在主会话中：

```
请找到 src/routes/ 下的所有路由文件，然后为每个文件启动一个
validation-adder 子 Agent 并行添加输入验证。
```

---

## 第四章：批量任务与持续 Agent 循环

### 4.1 /batch 命令

Claude Code 内置了 `/batch` 命令，用于对多个目标执行相同的操作：

```
/batch "为以下文件添加 JSDoc 注释" src/**/*.ts
```

`/batch` 的工作流程：
1. 展开文件 glob 模式
2. 为每个文件（或文件组）启动独立的 Agent
3. 并行执行相同的 prompt
4. 汇总所有结果

### 4.2 /simplify 命令

`/simplify` 是另一个内置命令，专门用于代码审查和简化：

```
/simplify
```

它会启动 3 个并行 Agent 对你的代码变更进行审查：
1. **可读性审查**：检查命名、结构、复杂度
2. **冗余检测**：发现重复代码和过度抽象
3. **简化建议**：提出更简洁的实现方式

### 4.3 Continuous Claude —— 持续循环 Agent

**Continuous Claude** 是一个开源工具（`github.com/AnandChowdhary/continuous-claude`），它将 Claude Code 包装在一个持续循环中，自动完成"编码 → 创建 PR → 等待 CI → 合并"的完整生命周期：

```bash
# 安装
curl -fsSL https://raw.githubusercontent.com/AnandChowdhary/continuous-claude/main/install.sh | bash

# 使用：自动增加测试覆盖率
continuous-claude \
  --prompt "增加测试覆盖率，直到覆盖率达到 80%" \
  --max-runs 10
```

其工作流程：


![图表8](images/claude-code-tutorial-r4-1729-mermaid-7.png)

> *图表 8*


关键设计——**上下文持久化**：每次迭代结束后，Agent 将进度和发现写入 `SHARED_TASK_NOTES.md`。下一次迭代时，新的 Claude Code 实例读取该文件，获得之前的上下文。这解决了 LLM 上下文窗口有限的根本问题。

### 4.4 自己写一个简单的 Agent 循环

不想安装额外工具？一个 while 循环就够了：

```bash
#!/bin/bash
# agent-loop.sh — 最简 Agent 循环

PROMPT_FILE="agent-task.md"
NOTES_FILE="AGENT_NOTES.md"
MAX_ITERATIONS=20

# 初始化笔记文件
if [ ! -f "$NOTES_FILE" ]; then
  echo "# Agent 进度笔记" > "$NOTES_FILE"
  echo "" >> "$NOTES_FILE"
  echo "## 任务" >> "$NOTES_FILE"
  cat "$PROMPT_FILE" >> "$NOTES_FILE"
fi

for i in $(seq 1 $MAX_ITERATIONS); do
  echo "=== 迭代 $i/$MAX_ITERATIONS ==="
  
  RESULT=$(claude -p \
    --max-turns 10 \
    --output-format text \
    "你正在进行第 $i 次迭代（共 $MAX_ITERATIONS 次）。
    
    请阅读 $NOTES_FILE 了解之前的进度。
    
    你的核心任务是：$(cat $PROMPT_FILE)
    
    规则：
    1. 每次只做有意义的进展，不要试图一次完成全部工作
    2. 完成后更新 $NOTES_FILE，记录你做了什么、发现了什么、下一步应该做什么
    3. 如果你认为任务已经全部完成，在输出的最后一行写上 TASK_COMPLETE
    4. 如果遇到无法解决的问题，在最后一行写上 TASK_BLOCKED 和原因")
  
  echo "$RESULT"
  
  # 检查完成信号
  if echo "$RESULT" | grep -q "TASK_COMPLETE"; then
    echo "🎉 任务完成！"
    break
  fi
  
  if echo "$RESULT" | grep -q "TASK_BLOCKED"; then
    echo "⚠️ Agent 遇到阻碍，需要人工干预。"
    break
  fi
done

echo "=== Agent 循环结束 ==="
```

### 4.5 实战：多仓库批量操作

对一组 Git 仓库执行批量操作：

```bash
#!/bin/bash
# batch-repos.sh — 对多个仓库执行相同的 Claude Code 任务

REPOS=("api-gateway" "user-service" "payment-service" "notification-service")
TASK="升级所有依赖到最新版本，修复所有 breaking changes，确保测试通过"
MODEL="claude-sonnet-4-6"

for repo in "${REPOS[@]}"; do
  echo "=== 处理 $repo ==="
  cd "/projects/$repo" || continue
  
  claude -p \
    --max-turns 15 \
    --model "$MODEL" \
    "$TASK。项目：$repo。完成后运行测试确保一切正常。"
  
  echo "=== $repo 处理完毕 ==="
  cd - || exit
done
```

并行版本（使用 `&` 后台运行）：

```bash
#!/bin/bash
# batch-repos-parallel.sh — 并行处理多个仓库

REPOS=("api-gateway" "user-service" "payment-service" "notification-service")
TASK="升级所有依赖到最新版本，修复所有 breaking changes，确保测试通过"

for repo in "${REPOS[@]}"; do
  (
    echo "=== 开始处理 $repo ==="
    cd "/projects/$repo" || exit 1
    
    claude -p \
      --max-turns 15 \
      --output-format json \
      "$TASK。项目：$repo。" \
      > "/tmp/claude-result-$repo.json" 2>&1
    
    echo "=== $repo 处理完毕 ==="
  ) &
done

# 等待所有后台任务完成
wait
echo "=== 所有仓库处理完毕 ==="

# 汇总结果
for repo in "${REPOS[@]}"; do
  echo "--- $repo ---"
  jq -r '.result // .error' "/tmp/claude-result-$repo.json" 2>/dev/null || echo "处理失败"
done
```

---

## 第五章：CI/CD 集成

### 5.1 GitHub Actions 集成

Claude Code 提供了官方的 GitHub Actions 集成。通过在 PR 上 `@claude` 即可触发 AI 审查：

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

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p \
            --max-turns 3 \
            --allowedTools "FileRead,Grep,Glob" \
            --output-format text \
            "审查这个 PR 的代码变更，关注安全漏洞、性能问题和代码质量。
            Diff: $(git diff origin/main...HEAD)"
```

### 5.2 自动 Issue 处理

```yaml
# .github/workflows/claude-issue-handler.yml
name: Claude Issue Handler

on:
  issues:
    types: [labeled]

jobs:
  auto-fix:
    if: contains(github.event.label.name, 'claude-fix')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Process Issue
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          ISSUE_TITLE="${{ github.event.issue.title }}"
          ISSUE_BODY="${{ github.event.issue.body }}"
          
          claude -p \
            --max-turns 10 \
            --dangerously-skip-permissions \
            "根据以下 Issue 描述修复代码：
            标题：$ISSUE_TITLE
            内容：$ISSUE_BODY
            
            修复后运行测试确保通过。"
      
      - name: Create PR
        run: |
          BRANCH="fix/issue-${{ github.event.issue.number }}"
          git checkout -b "$BRANCH"
          git add -A
          git commit -m "fix: resolve #${{ github.event.issue.number }}"
          git push origin "$BRANCH"
          gh pr create \
            --title "fix: ${{ github.event.issue.title }}" \
            --body "Closes #${{ github.event.issue.number }}" \
            --base main
```

### 5.3 安全最佳实践

在 CI/CD 中使用 Claude Code时务必遵循以下安全准则：


![图表9](images/claude-code-tutorial-r4-1729-mermaid-8.png)

> *图表 9*


| 安全措施 | 配置方式 | 原因 |
|----------|----------|------|
| 限制工具 | `--allowedTools "FileRead,Grep,Glob"` | 防止 Agent 修改代码或执行命令 |
| 费用上限 | `--max-budget-usd 2.00` | 防止循环导致 API 费用暴增 |
| 轮次上限 | `--max-turns 5` | 防止 Agent 无限循环 |
| 禁用遥测 | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | CI 环境不需要遥测 |
| 沙箱执行 | Docker 容器 | 隔离 Agent 的文件系统和网络访问 |

---

## 第六章：综合实战项目 —— 全自动代码质量守护者

将本章所有知识整合，构建一个完整的自动化代码质量系统：

### 6.1 项目结构

```
project/
├── .claude/
│   ├── settings.json          # Hooks 配置
│   ├── agents/
│   │   ├── security-scanner.md
│   │   ├── test-writer.md
│   │   └── doc-generator.md
│   └── hooks/
│       ├── pre_bash.py        # 危险命令拦截
│       ├── auto_format.sh     # 自动格式化
│       └── session_start.sh   # 会话上下文注入
├── scripts/
│   ├── auto-review.sh         # 自动代码审查
│   ├── agent-loop.sh          # Agent 循环
│   └── batch-repos.sh         # 多仓库批量操作
└── .github/
    └── workflows/
        ├── claude-review.yml
        └── claude-issue-handler.yml
```

### 6.2 完整的 settings.json

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/pre_bash.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto_format.sh"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/session_start.sh"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "FileRead",
      "Grep",
      "Glob",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff*)"
    ]
  }
}
```

### 6.3 端到端工作流

```text
flowchart TD
    A[开发者提交 PR] --> B[GitHub Actions 触发]
    B --> C[claude -p 代码审查]
    C --> D{审查结果}
    D -->|发现问题| E[评论到 PR]
    D -->|通过| F[等待人工确认]

    G[开发者本地编辑] --> H[Claude Code 交互模式]
    H --> I{PreToolUse Hook}
    I -->|危险命令| J[拦截 ❌]
    I -->|安全命令| K[执行]
    K --> L{PostToolUse Hook}
    L --> M[自动格式化]
    M --> N[继续工作]

    O[/batch 模式] --> P[并行处理多文件]
    P --> Q[批量添加测试/文档]

    R[大型任务] --> S[agent-loop.sh]
    S --> T[持续迭代直到完成]

    style J fill:#E74C3C,color:white
    style F fill:#2ECC71,color:white
    style M fill:#3498DB,color:white
```

---

## 延伸阅读

- [Claude Code 官方文档 - Headless 模式](https://code.claude.com/docs/en/headless)
- [Claude Code 官方文档 - Hooks 参考](https://code.claude.com/docs/en/hooks)
- [Claude Code 官方文档 - 子 Agent](https://code.claude.com/docs/en/sub-agents)
- [Claude Code 官方文档 - GitHub Actions](https://code.claude.com/docs/en/github-actions)
- [Continuous Claude 开源项目](https://github.com/AnandChowdhary/continuous-claude)
- [Claude Code 官方插件集](https://github.com/anthropics/claude-code/tree/main/plugins)
- [Hooks Mastery 示例仓库](https://github.com/disler/claude-code-hooks-mastery)

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | DevOps 自动化训练营、AI 工程师训练营、高级开发者训练营 |
| **预计教学时长** | 4-6 小时（含动手实践） |
| **难度级别** | 中高级（需要 Shell 脚本和 CI/CD 基础） |
| **推荐实验环节** | 1) 编写并测试一个 PreToolUse Hook 2) 用 -p 模式实现自动化审查 3) 配置一个 Agent 循环完成小型项目 |
| **前置课程** | Claude Code 入门篇（Round 1）和 Skills 开发实战（Round 2） |

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