<!-- title: Claude Code多Agent编排实战：Task到并行工作树 -->

## 概述

本教程深入讲解 Claude Code 的多 Agent 编排体系——从内置 Task 工具的四种子代理类型，到自定义 Agent 的 YAML 声明，再到 Git Worktree 的并行隔离执行。适合已掌握 Claude Code 基础操作、希望将单会话工作流升级为多代理并行协作的开发者。学完后将能设计并实施复杂的多代理自动化工作流，实现探索、规划、执行、验证的完整编排。

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

## 前置条件

- Claude Code v2.1.71+ 已安装并完成 API Key 配置
- Git 2.30+（worktree 功能需要）
- 了解 Claude Code 基本操作（对话、/命令、settings.json 配置）
- 一个可供实验的 Git 仓库（建议准备含 10+ 源文件的项目）

---

## 一、Agent 编排架构全景

Claude Code 的代理体系采用**两级架构**：主会话代理（Primary Agent）作为编排器，通过 Task 工具按需派生子代理（Subagent）。每个子代理拥有独立的工具集、上下文窗口和执行生命周期。

```mermaid
graph TB
    subgraph Primary["主会话代理 (Primary Agent)"]
        P1[用户对话]
        P2[工具调用]
        P3[上下文管理]
    end

    subgraph TaskTool["Task 工具（编排中枢）"]
        T1[分析任务]
        T2[选择代理类型]
        T3[派发执行]
    end

    subgraph Subagents["子代理集群"]
        S1["🔍 Explore Agent<br/>快速搜索与探索"]
        S2["📋 Plan Agent<br/>架构设计与规划"]
        S3["⚙️ General-Purpose<br/>通用任务执行"]
        S4["🎯 Custom Agent<br/>自定义专业代理"]
    end

    subgraph Isolation["隔离机制"]
        W1["Worktree 隔离"]
        W2["独立上下文"]
        W3["工具白名单"]
    end

    P1 --> T1
    T1 --> T2 --> T3
    T3 --> S1
    T3 --> S2
    T3 --> S3
    T3 --> S4
    S1 & S2 & S3 & S4 --> W1 & W2 & W3
    S1 & S2 & S3 & S4 -->|结果返回| P2
```

核心设计原则：

| 原则 | 说明 |
|------|------|
| **最小权限** | 子代理只获得完成任务所需的工具子集 |
| **上下文隔离** | 每个子代理有独立上下文窗口，不污染主会话 |
| **结果聚合** | 子代理只返回最终结果摘要，不回传中间过程 |
| **并行执行** | 多个无依赖的子代理可同时运行 |

---

## 二、Task 工具四种子代理深度解析

### 2.1 Explore Agent —— 代码库侦察兵

Explore 是速度最快的子代理，专为**搜索与发现**设计。它只能使用只读工具（Glob、Grep、Read），无法修改任何文件。

**触发场景**：
- "这个项目用了什么认证方案？"
- "找到所有使用 deprecated API 的地方"
- "API 路由定义在哪个文件？"

**实战命令**：

```
# 在 Claude Code 会话中直接提问
> 帮我找出这个项目中所有的数据库迁移文件，并分析它们的执行顺序

# Claude 会自动派发 Explore 子代理
# Explore 只读搜索 → 返回结构化结果
```

**手动调用模式**（在高级场景中指定 thoroughness）：

当你在对话中描述搜索需求时，Claude 会根据复杂度自动选择探索深度：

| 深度级别 | 适用场景 | 典型耗时 |
|----------|---------|---------|
| `quick` | 单文件定位、简单关键词搜索 | < 5 秒 |
| `medium` | 多文件模式搜索、跨目录关联 | 5-15 秒 |
| `very thorough` | 全库架构分析、多轮递进搜索 | 15-60 秒 |

**最佳实践**：对大仓库（1000+ 文件）搜索时，在提问中给出目录范围提示，可以大幅减少搜索时间。

```
# 不好的提问（全库扫描）
> 找到所有错误处理相关的代码

# 好的提问（精准定位）
> 在 src/api/ 和 src/middleware/ 目录下，找到所有 try-catch 块和错误处理中间件
```

### 2.2 Plan Agent —— 软件架构师

Plan 代理专为**设计方案**而生。它可以读取代码、搜索文件，但不能修改代码或写入文件。它返回的是结构化的实施计划。

**触发场景**：
- "设计一个用户认证系统的实现方案"
- "如何将这个单体应用拆分为微服务？"
- "给我一个从 REST 迁移到 GraphQL 的路线图"

**与 Explore 的关键区别**：

```mermaid
flowchart LR
    subgraph Explore["Explore Agent"]
        E1[搜索] --> E2[定位] --> E3[报告发现]
    end

    subgraph Plan["Plan Agent"]
        P1[分析代码] --> P2[理解架构] --> P3[设计变更方案]
        P3 --> P4[识别关键文件]
        P4 --> P5[评估权衡]
        P5 --> P6[输出实施步骤]
    end
```

**实战案例**：为现有 Express 项目添加 WebSocket 支持。

```
> 分析当前项目架构，设计一个添加 WebSocket 实时通知功能的方案

# Plan Agent 将返回：
# 1. 架构分析：现有 Express 路由结构
# 2. 关键文件：server.js、routes/、middleware/
# 3. 变更方案：安装 ws 包、创建 WebSocket 管理器、修改 server.js
# 4. 风险点：与现有 HTTP server 的端口冲突
# 5. 步骤清单：5 个有序实施步骤
```

### 2.3 General-Purpose Agent —— 全能执行者

这是功能最完整的子代理类型，拥有所有工具的访问权限（包括 Edit、Write、Bash），可以自主完成多步骤任务。

**触发场景**：
- "修复登录页面在移动端的布局问题"
- "为用户模型添加邮箱验证功能"
- "重构这个模块，将回调改为 async/await"

**关键特性**：

```
┌─────────────────────────────────────────────────┐
│         General-Purpose Agent 执行流程           │
├─────────────────────────────────────────────────┤
│  1. 接收任务描述和上下文                          │
│  2. 自主规划执行步骤                              │
│  3. 调用所需工具（Read/Edit/Write/Bash）          │
│  4. 验证每步结果                                  │
│  5. 返回最终结果摘要                              │
│                                                  │
│  ⚡ 特点：完全自主，无需人工干预                    │
│  🔒 限制：上下文窗口独立，不共享主会话历史          │
└─────────────────────────────────────────────────┘
```

### 2.4 Custom Agent —— 你的专属代理

通过 `.claude/agents/` 目录下的 Markdown+YAML 文件，你可以创建任何专业领域的子代理。

**目录结构**：

```
.claude/
├── agents/
│   ├── security-auditor.md      # 安全审计代理
│   ├── test-writer.md           # 测试编写代理
│   ├── doc-generator.md         # 文档生成代理
│   └── perf-analyzer.md         # 性能分析代理
├── settings.json
└── CLAUDE.md
```

---

## 三、自定义 Agent 创建实战

### 3.1 基础结构：安全审计代理

创建文件 `.claude/agents/security-auditor.md`：

```markdown
---
name: security-auditor
description: |
  Scans code for OWASP Top 10 vulnerabilities, hardcoded secrets,
  and insecure patterns. Use when reviewing code for security issues
  or before committing sensitive changes.
model: sonnet
tools:
  - Glob
  - Grep
  - Read
  - Bash
allowed_commands:
  - "npx eslint"
  - "grep"
  - "git diff"
---

# Security Auditor Agent

You are a security-focused code reviewer. Your job is to find vulnerabilities,
not to fix them.

## Review Checklist

1. **Injection attacks** — SQL injection, command injection, XSS
2. **Authentication flaws** — hardcoded credentials, weak tokens
3. **Sensitive data exposure** — API keys in source, unencrypted PII
4. **Security misconfiguration** — CORS *, debug mode enabled
5. **Dependency vulnerabilities** — known CVEs in package.json

## Output Format

Return findings as a structured list:
- Severity: CRITICAL / HIGH / MEDIUM / LOW
- File: path:line_number
- Issue: description
- Recommendation: how to fix
```

**YAML Frontmatter 字段详解**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 代理唯一标识符，Claude 用此决定何时委派 |
| `description` | string | 功能描述，Claude 根据此文本匹配任务 |
| `model` | string | 使用的模型：`haiku`（快速）、`sonnet`（平衡）、`opus`（深度） |
| `tools` | string[] | 允许使用的工具白名单 |
| `allowed_commands` | string[] | Bash 工具中允许执行的命令前缀 |

### 3.2 进阶配置：测试编写代理

`.claude/agents/test-writer.md`：

```markdown
---
name: test-writer
description: |
  Generates comprehensive test suites for any code module. Creates unit tests,
  integration tests, and edge case coverage. Triggered when user asks to add
  tests, improve coverage, or TDD a new feature.
model: sonnet
tools:
  - Glob
  - Grep
  - Read
  - Edit
  - Write
  - Bash
---

# Test Writer Agent

You are a test engineering specialist. You write thorough, well-structured tests.

## Workflow

1. **Analyze target** — Read the source file, identify all exported functions
2. **Detect framework** — Check package.json for jest/vitest/mocha/pytest
3. **Generate tests** — Cover happy path, edge cases, error conditions
4. **Run tests** — Execute and verify all tests pass
5. **Report coverage** — If coverage tool available, report results

## Test Structure Pattern

```javascript
describe('moduleName', () => {
  describe('functionName', () => {
    it('should handle normal input', () => { /* ... */ })
    it('should handle edge case: empty input', () => { /* ... */ })
    it('should handle edge case: null input', () => { /* ... */ })
    it('should throw on invalid input', () => { /* ... */ })
  })
})
```

## Rules

- Always run tests after writing them
- Fix any failing tests before returning
- Never modify source code — only create/edit test files
- Use existing test patterns from the project
```

### 3.3 代理选择策略

Claude 如何决定使用哪个子代理？这取决于 `description` 字段与用户请求的语义匹配。

```mermaid
flowchart TD
    A[用户请求到达] --> B{需要修改代码？}
    B -->|否| C{需要设计方案？}
    B -->|是| D{有匹配的自定义代理？}
    C -->|是| E[Plan Agent]
    C -->|否| F[Explore Agent]
    D -->|是| G[Custom Agent]
    D -->|否| H{需要执行多步骤？}
    H -->|是| I[General-Purpose Agent]
    H -->|否| J[主代理直接处理]

    style G fill:#e1f5fe
    style E fill:#fff3e0
    style F fill:#e8f5e9
    style I fill:#fce4ec
```

**description 编写技巧**：

```markdown
# ✅ 好的 description —— 明确触发条件
description: |
  Scans code for OWASP Top 10 vulnerabilities.
  Use when reviewing code for security issues or before
  committing sensitive changes.

# ❌ 差的 description —— 模糊不清
description: |
  Helps with code quality and stuff.
```

---

## 四、并行执行与 Worktree 隔离

### 4.1 为什么需要 Worktree？

当多个子代理同时修改文件时，会产生冲突。Git Worktree 为每个子代理创建独立的工作目录副本。

**无 Worktree 的问题场景**：

```
Agent A: 编辑 src/auth.js 第 15 行
Agent B: 同时编辑 src/auth.js 第 12 行
→ 文件冲突，Agent B 的修改覆盖 Agent A
```

**Worktree 解决方案**：

```
主仓库:     /project/
Agent A:    /project/.claude/worktrees/feature-auth/
Agent B:    /project/.claude/worktrees/feature-test/
→ 各自独立工作，完成后通过 Git 合并
```

### 4.2 Worktree 三种使用方式

#### 方式一：对话触发（最简单）

在 Claude Code 会话中直接说：

```
> 在一个独立的 worktree 中工作，实现用户注册功能
```

Claude 会调用 `EnterWorktree` 工具，自动创建隔离分支。

#### 方式二：Task 工具参数

```
> 使用两个并行代理：一个在 worktree 中修复 Bug #42，另一个在另一个 worktree 中添加日志功能
```

Claude 会通过 Task 工具的 `isolation: "worktree"` 参数为每个子代理创建独立工作树。

#### 方式三：命令行直接指定

```bash
# 启动 Claude Code 并自动进入 worktree
claude --worktree feature-auth

# 在后台运行并行任务
claude -p "修复登录 Bug" --worktree fix-login &
claude -p "添加注册功能" --worktree add-register &
wait
```

### 4.3 并行编排实战：三代理协同

以下是一个真实的并行开发工作流——同时进行 Bug 修复、测试补充、文档更新：

```mermaid
sequenceDiagram
    participant User as 开发者
    participant Primary as 主代理
    participant BugFix as Bug修复代理
    participant Test as 测试代理
    participant Doc as 文档代理

    User->>Primary: 并行处理三项任务
    
    par 并行派发
        Primary->>BugFix: Task(isolation: worktree)<br/>修复 Issue #42
        Primary->>Test: Task(isolation: worktree)<br/>补充测试覆盖
        Primary->>Doc: Task(model: haiku)<br/>更新 API 文档
    end

    Note over BugFix,Doc: 三个代理同时执行<br/>各自在独立 worktree 中工作
    
    BugFix-->>Primary: 修复完成，返回变更摘要
    Test-->>Primary: 测试编写完成，覆盖率 85%→95%
    Doc-->>Primary: 文档已更新
    
    Primary->>Primary: 合并三个 worktree 的变更
    Primary->>Primary: 运行完整测试套件验证
    Primary-->>User: 三项任务全部完成
```

**在 Claude Code 中触发**：

```
> 我需要同时完成三件事，请并行派发：
> 1. 在独立 worktree 中修复 src/api/auth.js 的 token 过期 Bug
> 2. 在独立 worktree 中为 src/utils/ 下所有工具函数补充单元测试
> 3. 更新 docs/api.md 中认证部分的文档
> 
> 修复和测试用 sonnet 模型，文档用 haiku 模型节省 token
```

### 4.4 Worktree 生命周期管理

```mermaid
stateDiagram-v2
    [*] --> Created: 创建 worktree
    Created --> Working: 子代理开始执行
    Working --> Completed: 任务完成
    Working --> Failed: 任务失败
    Completed --> Merged: Git merge/cherry-pick
    Failed --> Retried: 重试
    Failed --> Abandoned: 放弃
    Merged --> Cleaned: 自动清理
    Abandoned --> Cleaned: 手动清理
    Retried --> Working
    Cleaned --> [*]
```

**关键行为**：
- 任务成功且变更已合并 → worktree **自动清理**
- 子代理未做任何修改 → worktree **自动清理**
- 任务失败或部分完成 → worktree **保留**，供开发者手动检查

**手动管理命令**：

```bash
# 查看所有 worktree
git worktree list

# 清理已合并的 worktree
git worktree prune

# 删除特定 worktree
git worktree remove .claude/worktrees/feature-auth
```

---

## 五、Agent 生命周期钩子

子代理的创建和销毁过程可以通过钩子拦截和增强。

### 5.1 四大 Agent 钩子

| 钩子事件 | 触发时机 | 典型用途 |
|----------|---------|---------|
| `SubagentStart` | 子代理即将启动 | 注入额外上下文、限制资源 |
| `SubagentStop` | 子代理执行完毕 | 收集结果、触发通知 |
| `SubagentError` | 子代理异常 | 告警、自动重试、日志记录 |
| `SubagentResult` | 子代理返回结果 | 结果验证、格式转换 |

### 5.2 配置示例：子代理启动通知

在 `.claude/settings.json` 中添加：

```json
{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[$(date)] Subagent started: $CLAUDE_SUBAGENT_NAME' >> .claude/agent-log.txt"
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[$(date)] Subagent completed: $CLAUDE_SUBAGENT_NAME, duration: $CLAUDE_DURATION seconds' >> .claude/agent-log.txt"
          }
        ]
      }
    ]
  }
}
```

### 5.3 安全守卫：限制子代理权限

通过钩子在子代理启动时强制注入安全规则：

```json
{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "general-purpose",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$CLAUDE_SUBAGENT_TOOLS' | grep -q 'Bash'; then echo 'approve'; else echo 'deny'; fi"
          }
        ]
      }
    ]
  }
}
```

---

## 六、完整实战案例：多代理代码审查流水线

### 6.1 场景描述

假设你有一个 Node.js 项目，每次提交 PR 时需要：
1. 安全审计（检查漏洞）
2. 性能分析（识别 N+1 查询、内存泄漏风险）
3. 测试覆盖分析（评估覆盖率变化）

使用 `-p` 模式 + 多代理编排，构建一个自动化的 PR 审查流水线。

### 6.2 步骤一：创建自定义代理

**安全审计代理** `.claude/agents/security-auditor.md`（见上文第三章）

**性能分析代理** `.claude/agents/perf-analyzer.md`：

```markdown
---
name: perf-analyzer
description: |
  Analyzes code for performance bottlenecks including N+1 queries,
  memory leaks, unnecessary re-renders, and algorithmic complexity issues.
  Use when reviewing code for performance or optimizing existing modules.
model: sonnet
tools:
  - Glob
  - Grep
  - Read
  - Bash
allowed_commands:
  - "npx eslint"
  - "node"
  - "wc"
---

# Performance Analyzer Agent

You are a performance engineering specialist.

## Analysis Targets

1. **Database queries** — N+1 patterns, missing indexes, full table scans
2. **Memory patterns** — closures holding references, growing arrays, event listener leaks
3. **Algorithmic complexity** — O(n²) loops that should be O(n), nested iterations
4. **Network calls** — sequential requests that could be parallel, missing caching
5. **Bundle size** — large imports, unused dependencies

## Output Format

For each finding:
- Category: DB / Memory / Algorithm / Network / Bundle
- Severity: HIGH / MEDIUM / LOW
- Location: file:line
- Impact: estimated performance degradation
- Fix: recommended optimization with code example
```

### 6.3 步骤二：创建编排脚本

创建 `scripts/multi-review.sh`：

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

# 获取当前分支相对于 main 的变更文件
CHANGED_FILES=$(git diff --name-only main...HEAD 2>/dev/null || git diff --name-only HEAD~1)

if [ -z "$CHANGED_FILES" ]; then
    echo "No changes detected."
    exit 0
fi

echo "=== Multi-Agent Code Review ==="
echo "Changed files:"
echo "$CHANGED_FILES"
echo ""

# 将变更文件列表写入临时文件供各代理读取
DIFF_FILE=$(mktemp)
git diff main...HEAD > "$DIFF_FILE" 2>/dev/null || git diff HEAD~1 > "$DIFF_FILE"

# 1. 安全审计（sonnet 模型，较深层分析）
echo "🔍 [1/3] Running security audit..."
claude -p \
    --model sonnet \
    "你是一个安全审计专家。审查以下代码变更，重点检查：
    - 硬编码密钥或凭证
    - SQL 注入 / XSS 风险
    - 不安全的依赖
    - CORS / CSRF 配置错误
    
    变更内容：
    $(cat "$DIFF_FILE")
    
    输出格式：每条发现包含严重程度(CRITICAL/HIGH/MEDIUM/LOW)、文件路径、问题描述。" \
    > /tmp/security-report.md 2>&1 &
SEC_PID=$!

# 2. 性能分析（sonnet 模型）
echo "⚡ [2/3] Running performance analysis..."
claude -p \
    --model sonnet \
    "你是一个性能分析专家。审查以下代码变更，重点检查：
    - N+1 数据库查询模式
    - 内存泄漏风险（未清理的事件监听器、闭包引用）
    - O(n²) 或更高复杂度的算法
    - 可并行化但被串行执行的网络请求
    
    变更内容：
    $(cat "$DIFF_FILE")
    
    输出格式：每条发现包含类别、严重程度、位置、影响评估、优化建议。" \
    > /tmp/perf-report.md 2>&1 &
PERF_PID=$!

# 3. 测试覆盖分析（haiku 模型，快速检查）
echo "🧪 [3/3] Analyzing test coverage..."
claude -p \
    --model haiku \
    "分析以下变更文件的测试覆盖情况：
    
    变更文件列表：
    $CHANGED_FILES
    
    对于每个变更文件，检查是否存在对应的测试文件。
    报告缺少测试的文件，以及已有测试但可能需要更新的文件。
    输出简洁的覆盖情况摘要。" \
    > /tmp/coverage-report.md 2>&1 &
COV_PID=$!

# 等待所有代理完成
wait $SEC_PID $PERF_PID $COV_PID

# 合并报告
echo ""
echo "============================================"
echo "       Multi-Agent Review Report"
echo "============================================"
echo ""
echo "## 🔒 Security Audit"
cat /tmp/security-report.md
echo ""
echo "## ⚡ Performance Analysis"
cat /tmp/perf-report.md
echo ""
echo "## 🧪 Test Coverage"
cat /tmp/coverage-report.md
echo ""
echo "============================================"

# 清理
rm -f "$DIFF_FILE" /tmp/security-report.md /tmp/perf-report.md /tmp/coverage-report.md
```

### 6.4 步骤三：配置为 Git Hook

将脚本集成到 Git 工作流中，在每次 push 前自动运行：

```bash
# 赋予执行权限
chmod +x scripts/multi-review.sh

# 创建 pre-push hook
cat > .git/hooks/pre-push << 'EOF'
#!/bin/bash
echo "Running multi-agent code review..."
bash scripts/multi-review.sh

# 如果任何代理报告 CRITICAL 级别问题，阻止 push
if grep -q "CRITICAL" /tmp/security-report.md 2>/dev/null; then
    echo "❌ Critical security issues found. Push blocked."
    exit 1
fi

echo "✅ Review passed."
exit 0
EOF

chmod +x .git/hooks/pre-push
```

### 6.5 步骤四：运行验证

```bash
# 手动触发审查
./scripts/multi-review.sh

# 预期输出示例：
# === Multi-Agent Code Review ===
# Changed files:
# src/api/auth.js
# src/utils/token.js
# src/middleware/cors.js
#
# 🔍 [1/3] Running security audit...
# ⚡ [2/3] Running performance analysis...
# 🧪 [3/3] Analyzing test coverage...
#
# ============================================
#        Multi-Agent Review Report
# ============================================
#
# ## 🔒 Security Audit
# MEDIUM: src/api/auth.js:42 — Token not validated on refresh
# LOW: src/middleware/cors.js:8 — Wildcard CORS origin in development
#
# ## ⚡ Performance Analysis
# HIGH: src/api/auth.js:56 — Sequential DB queries can be parallelized
# MEDIUM: src/utils/token.js:23 — Token decode called twice per request
#
# ## 🧪 Test Coverage
# src/api/auth.js → Missing test file
# src/utils/token.js → Test exists, may need update
# src/middleware/cors.js → Test exists, coverage adequate
```

### 6.6 流程全览

```mermaid
flowchart TB
    subgraph Trigger["触发源"]
        T1["git push"]
        T2["手动执行脚本"]
        T3["CI/CD Pipeline"]
    end

    subgraph Orchestrator["编排层"]
        O1["multi-review.sh"]
        O2["读取 git diff"]
        O3["写入临时文件"]
    end

    subgraph Agents["并行代理集群"]
        A1["🔒 Security Agent<br/>model: sonnet"]
        A2["⚡ Perf Agent<br/>model: sonnet"]
        A3["🧪 Coverage Agent<br/>model: haiku"]
    end

    subgraph Aggregate["聚合层"]
        G1["合并三份报告"]
        G2{"有 CRITICAL？"}
        G3["✅ 通过"]
        G4["❌ 阻止推送"]
    end

    T1 & T2 & T3 --> O1
    O1 --> O2 --> O3
    O3 --> A1 & A2 & A3
    A1 & A2 & A3 -->|并行执行| G1
    G1 --> G2
    G2 -->|否| G3
    G2 -->|是| G4
```

---

## 七、高级模式：会话管理与跨会话编排

### 7.1 会话持久化

多代理工作流经常跨越长时间运行的任务。Claude Code 提供三种会话管理策略：

```bash
# 策略一：--continue 继续上一次会话
claude --continue
# 自动加载最近一次会话的完整上下文

# 策略二：--resume 恢复指定会话
claude --resume
# 交互式选择历史会话

# 策略三：--name 命名会话（推荐用于多代理编排）
claude --name "security-review-sprint-42"
# 后续可通过名称精确恢复
```

### 7.2 跨会话编排模式

当任务复杂到需要跨越多个独立会话时：

```mermaid
flowchart LR
    subgraph Session1["会话 1：探索"]
        S1["Explore Agent<br/>扫描代码库"]
        S1 --> S2["输出：架构分析报告"]
    end

    subgraph Session2["会话 2：规划"]
        S3["读取架构分析"]
        S3 --> S4["Plan Agent<br/>设计重构方案"]
        S4 --> S5["输出：实施计划"]
    end

    subgraph Session3["会话 3：执行"]
        S6["读取实施计划"]
        S6 --> S7["并行 General-Purpose Agents"]
        S7 --> S8["输出：代码变更"]
    end

    subgraph Session4["会话 4：验证"]
        S9["读取变更"]
        S9 --> S10["运行测试"]
        S10 --> S11["输出：验证报告"]
    end

    S2 -->|传递| S3
    S5 -->|传递| S6
    S8 -->|传递| S9
```

**实现脚本** `scripts/phased-refactor.sh`：

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

PROJECT_DIR=$(pwd)
WORK_DIR="/tmp/claude-orchestration"
mkdir -p "$WORK_DIR"

# 阶段一：探索
echo "Phase 1: Exploring codebase..."
claude -p --model sonnet \
    "分析这个项目的架构，输出一份结构化的分析报告，包含：
    - 目录结构和模块划分
    - 核心依赖关系
    - 代码规模统计
    - 潜在的重构点
    保存报告到 $WORK_DIR/architecture.md" \
    --output-format text

# 阶段二：规划
echo "Phase 2: Planning refactoring..."
claude -p --model opus \
    "读取 $WORK_DIR/architecture.md，基于其中的分析，
    设计一个分步骤的重构方案。优先处理高耦合、低内聚的模块。
    输出每个步骤的具体文件变更清单。
    保存方案到 $WORK_DIR/plan.md" \
    --output-format text

# 阶段三：执行（并行）
echo "Phase 3: Executing refactoring in parallel..."
# 读取计划中的步骤数
STEPS=$(grep -c "^## Step" "$WORK_DIR/plan.md" 2>/dev/null || echo 1)

for i in $(seq 1 "$STEPS"); do
    echo "  Starting step $i..."
    claude -p --model sonnet \
        "读取 $WORK_DIR/plan.md，执行第 $i 步骤中的所有变更。
        完成后运行相关测试验证。" \
        --worktree "refactor-step-$i" \
        > "$WORK_DIR/step-$i-result.md" 2>&1 &
done

echo "  Waiting for all steps to complete..."
wait

# 阶段四：验证
echo "Phase 4: Validating all changes..."
claude -p --model sonnet \
    "检查所有 worktree 中的变更：
    1. 运行完整测试套件
    2. 检查是否有合并冲突
    3. 验证代码风格一致性
    输出最终验证报告到 $WORK_DIR/validation.md" \
    --output-format text

echo "All phases complete. Results in $WORK_DIR/"
```

### 7.3 模型路由策略

不同代理任务适合不同模型，合理路由可以节省 60%+ 的 API 成本：

```mermaid
graph TD
    A[任务到达] --> B{任务复杂度评估}
    B -->|简单搜索/格式化| C["Haiku<br/>$0.25/M tokens"]
    B -->|中等开发/重构| D["Sonnet<br/>$3/M tokens"]
    B -->|架构设计/安全审计| E["Opus<br/>$15/M tokens"]

    C --> F["Explore 快速搜索<br/>文档更新<br/>简单格式化"]
    D --> G["Bug 修复<br/>功能实现<br/>测试编写"]
    E --> H["架构评审<br/>安全审计<br/>复杂重构规划"]
```

**成本对比示例**（处理一个 50 文件的项目）：

| 策略 | 总 Token 消耗 | 预估成本 | 耗时 |
|------|-------------|---------|------|
| 全部 Opus | ~2M | ~$30 | 15 min |
| 智能路由 | ~2M | ~$8 | 15 min |
| 全部 Haiku | ~2M | ~$0.50 | 15 min |

智能路由的核心理念：**把 token 预算花在需要深度思考的任务上**。

---

## 八、常见问题与解决方案

### Q1：子代理返回结果不完整

**原因**：子代理的上下文窗口有限，处理大型文件时可能截断。

**解决方案**：

```
# 在任务描述中明确指定输出格式和长度限制
> 分析 src/ 目录的代码结构，只输出目录级别的问题摘要，
> 不要输出每个文件的逐行分析
```

### Q2：并行代理产生 Git 冲突

**原因**：即使使用 worktree，如果两个代理修改了同一个文件的不同部分，合并时仍可能冲突。

**解决方案**：
1. 在任务描述中明确划定各代理的职责边界
2. 使用文件级别的任务分配，避免重叠
3. 合并后让 Claude 自动解决冲突：`claude -p "解决当前 Git 合并冲突"`

### Q3：子代理使用了不应该使用的工具

**原因**：自定义代理的 `tools` 白名单未精确配置。

**解决方案**：

```yaml
# 最小权限原则——只授权必要的工具
tools:
  - Read      # 只读文件
  - Grep      # 搜索内容
  # 不给 Edit/Write/Bash 权限
```

### Q4：代理执行超时

**解决方案**：通过 `maxTurns` 参数限制子代理的最大交互轮次。

```
# 在对话中指定
> 使用 maxTurns=10 的 Explore 代理搜索所有 TODO 注释

# 或在 -p 模式中使用
claude -p "搜索所有 TODO" --max-turns 10
```

### Q5：多代理协调时上下文丢失

**原因**：每个子代理有独立的上下文窗口，无法访问主会话的对话历史。

**解决方案**：通过文件传递上下文。

```bash
# 先让主代理输出上下文到文件
claude -p "分析项目架构，输出摘要到 context.md"

# 子代理读取上下文文件
claude -p "读取 context.md，基于其中的信息执行重构"
```

---

## 九、生产环境最佳实践清单

| 维度 | 最佳实践 | 风险等级 |
|------|---------|---------|
| **隔离** | 所有修改性任务使用 worktree | 🔴 高 |
| **权限** | 自定义代理使用最小工具白名单 | 🔴 高 |
| **成本** | 简单任务用 haiku，复杂任务才用 opus | 🟡 中 |
| **验证** | 子代理执行后必须运行测试 | 🔴 高 |
| **日志** | 配置 SubagentStart/Stop 钩子记录执行日志 | 🟡 中 |
| **超时** | 为所有 -p 模式任务设置 --max-turns | 🟡 中 |
| **幂等** | 确保子代理任务可安全重试 | 🟢 低 |
| **监控** | 合并后运行完整 CI 流水线验证 | 🔴 高 |

---

## 十、架构总结：多代理编排的三个层次

```mermaid
graph TB
    subgraph L1["第一层：单代理自动化<br/>（入门级）"]
        L1A["-p 模式<br/>单次执行"]
        L1B["--continue<br/>会话延续"]
        L1C["/loop<br/>定时循环"]
    end

    subgraph L2["第二层：多代理编排<br/>（进阶级）"]
        L2A["Task 工具<br/>子代理派发"]
        L2B["Worktree<br/>并行隔离"]
        L2C["Custom Agents<br/>专业代理"]
    end

    subgraph L3["第三层：流水线自动化<br/>（生产级）"]
        L3A["Shell 脚本<br/>多阶段编排"]
        L3B["CI/CD 集成<br/>GitHub Actions"]
        L3C["Routines<br/>云端定时任务"]
    end

    L1 --> L2 --> L3

    style L1 fill:#e8f5e9
    style L2 fill:#fff3e0
    style L3 fill:#e1f5fe
```

- **第一层**：适合个人开发者日常使用，命令行即可完成
- **第二层**：适合复杂项目开发，需要理解代理隔离和并行机制
- **第三层**：适合团队协作和持续交付，需要脚本化编排能力

---

## 延伸阅读

- [Create custom subagents - Claude Code 官方文档](https://code.claude.com/docs/en/sub-agents) — 自定义代理的完整参考
- [Hooks reference - Claude Code 官方文档](https://code.claude.com/docs/en/hooks) — 所有钩子事件的详细说明
- [Run parallel sessions with worktrees](https://code.claude.com/docs/en/worktrees) — Worktree 并行会话指南
- [Claude Code Agents & Subagents: Complete Guide](https://skillsplayground.com/guides/claude-code-agents/) — 代理类型和使用场景详解
- [Agent System & Subagents - DeepWiki](https://deepwiki.com/anthropics/claude-code/3.1-agent-system-and-subagents) — Claude Code 源码级架构分析
- [Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions) — CI/CD 集成官方文档
- [Choosing the right Claude model](https://claude.com/resources/tutorials/choosing-the-right-claude-model) — 模型选择指南

## 参考来源

1. [Create custom subagents - Claude Code Docs](https://code.claude.com/docs/en/sub-agents) — Anthropic 官方自定义子代理创建指南
2. [Hooks reference - Claude Code Docs](https://code.claude.com/docs/en/hooks) — 官方钩子事件参考文档
3. [Run parallel sessions with worktrees - Claude Code Docs](https://code.claude.com/docs/en/worktrees) — 官方 Worktree 并行会话文档
4. [The Task Tool: Claude Code's Agent Orchestration System](https://dev.to/bhaidar/the-task-tool-claude-codes-agent-orchestration-system-4bf2) — Task 工具深度解析
5. [Mastering Claude Code Sub-agents - timewell.jp](https://timewell.jp/en/columns/claude-code-subagents-practical-guide) — 子代理实战模式指南

## 训练营适用性评估

| 评估维度 | 说明 |
|----------|------|
| **适合训练营** | AI 工程师进阶训练营、DevOps 自动化训练营、团队效能提升工作坊 |
| **教学时长** | 4-5 小时（含实操练习） |
| **前置要求** | Claude Code 基础使用经验、Git 操作熟练、Shell 脚本基础 |
| **实操占比** | 60%（三代理并行审查流水线为完整实操项目） |
| **难度评级** | ⭐⭐⭐⭐（中高级） |

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