先看两个真实场景：

场景一：新接手一个大型项目

你刚加入一个团队，需要快速理解一个包含几十个模块的后端项目。传统方式下，我们可能要花费很久的时间熟悉。

串行探索既慢，又容易在中途忘记前面看到的细节。

而并行探索的方式就不一样了。

三个子代理同时工作，各自探索自己的领域，最后汇总成一份综合报告。

实战演练：并行探索

三个专门的探索子代理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
parallel-explore/
├── src/
│   ├── auth/           # 认证模块
│   │   ├── index.js
│   │   ├── jwt.js
│   │   └── session.js
│   ├── database/       # 数据库模块
│   │   ├── index.js
│   │   ├── models.js
│   │   └── migrations.js
│   └── api/            # API 模块
│       ├── index.js
│       ├── routes.js
│       └── middleware.js
└── .claude/agents/
    ├── auth-explorer.md
    ├── db-explorer.md
    └── api-explorer.md

auth-explorer 子代理的配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
---
name: auth-explorer
description: Explore and analyze authentication-related code. Use when investigating auth flows, session management, or security.
tools: Read, Grep, Glob
model: haiku
---

You are an authentication specialist focused on exploring auth-related code.

## Your Domain

Focus ONLY on authentication-related concerns:
- Login/logout flows
- Token generation and validation (JWT, sessions)
- Password handling
- Permission and role systems
- Session management

## When Invoked

1. **Locate Auth Code**: Use Glob to find auth-related files
   - Patterns: `**/auth/**`, `**/*auth*`, `**/*login*`, `**/*session*`, `**/*jwt*`

2. **Analyze Structure**: Read key files and understand:
   - How users authenticate
   - How tokens are generated/validated
   - How sessions are managed
   - How permissions are checked

3. **Report Findings**

## Output Format

.```markdown
## Auth Module Analysis

### Overview
[1-2 sentence summary]

### Authentication Flow
1. [Step 1]
2. [Step 2]
...

### Key Components
| Component | File | Purpose |
|-----------|------|---------|
| ... | ... | ... |

### Token Strategy
- Type: [JWT/Session/etc]
- Expiry: [duration]
- Storage: [where stored]

### Security Notes
- [Observations about security posture]

## Guidelines
- Stay within auth domain - don't analyze unrelated code
- Note any security concerns you observe
- Be concise - main conversation will synthesize

关键设计点如下：

  • tools: Read, Grep, Glob，全部只读，探索不需要修改任何东西，这三个工具足够完成代码探索任务。
  • model: haiku，探索任务相对简单，追求速度，haiku 更快更便宜。
  • Stay within auth domain：明确告诉子代理它的职责边界，防止它越界去分析不相关的代码。

用同样的模式创建另外两个探索子代理 db-explorer 和 api-explorer，只需要修改：

  • name 和 description
  • Your Domain 部分的关注点
  • Output Format 中的报告结构

进入项目目录，在 Claude Code 的命令行中输入：

1
同时让 auth-explorer、db-explorer、api-explorer 探索各自模块， 然后汇总给我一个整体架构理解

Claude 会完成下述步骤：

  1. 并行启动三个子代理
  2. 各自独立执行探索任务
  3. 收集三份报告
  4. 综合成一份整体架构理解

并行执行的价值显而易见。传统情况下，如果不使用子代理并行处理，假设每个模块用时 30 秒，串行总耗时 90 秒，主对话上下文会被三个模块的探索过程塞满；而并行整体用时 30 秒，且只有三份简洁报告。并行执行不仅更快，而且主对话的上下文更清洁。

前台与后台运行

在 Claude Code 中，子代理默认在前台运行——你能看到它实时输出的每一行。并行探索时，如果三个子代理都在前台，你的终端会被占满。

当一个子代理正在前台运行时，按 Ctrl+B 可以将它切换到后台继续执行。这在并行场景下非常实用。

后台运行的一个重要限制是无法弹出权限确认对话框。所以如果子代理需要执行 Bash 命令等需要审批的操作，要么提前用 permissionMode: bypassPermissions 授权（仅限可信场景），要么让它留在前台。对于我们的只读探索子代理（tools 只有 Read/Grep/Glob），不需要权限审批，所以切到后台完全没问题。

并行探索的隐含前提：任务必须真正独立

并行看起来很美好，但有一个容易被忽略的前提：各子代理的探索任务之间不能有信息依赖。

什么叫有信息依赖？我们拿一个电商项目举例。

  • auth-explorer 发现用户认证使用 JWT，token 中包含 userId 和 role 。
  • db-explorer 发现 users 表有 role 字段，但 orders 表里也有 user_role 冗余字段 。
  • api-explorer: 发现 /admin/* 路由用了中间件检查 role。

问题来了！这三个发现之间有关联——role 的传递路径横跨三个模块，但因为并行执行，每个子代理都不知道其他两个发现了什么！这不是 bug，而是设计约束。并行探索的综合分析必须由主对话来完成。子代理负责“收集原始情报”，主对话负责“连点成线”。

在上面的场景中，因为主对话可以进行汇总，因此整体分析结果仍然可行，但在有些情况下，各任务间强相互依赖时，就必须等待。

如何判断是否适合并行，检查清单如下：

1
2
3
4
5
6
7
8
9
10
11
每个子任务能否独立完成，不需要另一个子任务的结果？
是 → 可以并行
否 → 必须串行或混合模式

遗漏跨模块关联是否可接受？
是（主对话会综合分析）→ 可以并行
否（遗漏可能导致错误决策）→ 考虑串行或增加综合分析阶段

子任务的输出粒度是否匹配？
是（都是模块级概览）→ 容易综合
否（有的是文件级，有的是函数级）→ 综合困难，先统一粒度

场景二：修复一个复杂的bug

遇到一个“用户登录后偶尔 token 验证失败”的 bug。这种间歇性问题最难调试。

如果让主对话直接处理，上下文会很快被塞满：

  • 搜索相关代码 → 200 行输出
  • 分析可能的原因 → 又是 200 行
  • 修复 → 100 行
  • 验证 → 又是测试输出……

而流水线的方式，每个阶段只返回摘要，主对话始终保持清洁，可以随时介入做决策。

并行探索与流水线编排

流水线编排：Bug 修复流水线

1
2
3
4
5
6
7
8
9
10
11
12
13
14
bugfix-pipeline/ 
├── src/ 
│ 
├── user-service.js # 用户服务（有 bug） 
│ ├── cart-service.js # 购物车服务（有 bug） 
│ ├── order-service.js # 订单服务（有 bug） 
│ └── utils.js # 工具函数 
├── tests/ 
│ └── services.test.js # 测试文件 
└── .claude/agents/ 
├── bug-locator.md # 定位：找到问题在哪 
├── bug-analyzer.md # 分析：理解为什么出问题 
├── bug-fixer.md # 修复：实施修复 
└── bug-verifier.md # 验证：确认修复有效

这四个子代理，对应 Bug 修复流水线的四个阶段:

Bug 修复流水线

每个代理职责和角色清晰，每个节点都可被单独替换 / 回滚 / 审计。

  • Locator：只回答“在哪”
  • Analyzer：只回答 “为什么”
  • Fixer：只负责 “怎么改”
  • Verifier：只负责 “改对没有”

下面我们按“定位、分析、修复、验证”的分工顺序挨个拆解：

阶段一：Locator（定位）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
---
name: bug-locator
description: Locate the source of bugs in the codebase. First step in bug investigation.
tools: Read, Grep, Glob
model: sonnet
---

You are a bug investigation specialist focused on locating issues in code.

## Your Role

You are the FIRST step in the bug fix pipeline. Your job is to:
1. Understand the bug symptoms
2. Find where the bug likely originates
3. Identify related code that might be affected

## When Invoked

1. **Parse Bug Description**: Extract key information
   - Error messages
   - Stack traces
   - Symptoms/behavior

2. **Search Codebase**: Use Grep/Glob to find relevant code
   - Search for function names from stack traces
   - Search for error messages
   - Search for related keywords

3. **Narrow Down Location**: Identify the most likely source files

## Output Format

.```markdown
## Bug Location Report

### Symptoms
[Summary of reported issue]

### Search Results
- Found [X] potentially related files
- Key matches: [list]

### Most Likely Location
**File**: [path]
**Function**: [name]
**Line**: [approximate]
**Confidence**: High/Medium/Low

### Related Code
- [file]: [why related]
- [file]: [why related]

### Handoff to Analyzer
[What the analyzer should focus on]

## Guidelines
- Be thorough in searching - check multiple patterns
- Consider indirect causes (the bug might manifest in one place but originate elsewhere)
- Note any related code that might be affected by a fix
- DO NOT suggest fixes - that's for the fixer
- Keep output concise for the analyzer to continue

设计关键点：

  • model: sonnet ：定位 bug 需要较强的推理能力
  • DO NOT suggest fixes：明确告诉它这不是它的职责
  • Handoff to Analyzer：为下一阶段准备信息

阶段二：Analyzer（分析）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
---
name: bug-analyzer
description: Analyze root cause of bugs after location is identified. Second step in bug investigation.
tools: Read, Grep, Glob
model: sonnet
---

You are a bug analysis specialist focused on understanding root causes.

## Your Role

You are the SECOND step in the bug fix pipeline. You receive:
- Bug location from the locator
- Symptoms description

Your job is to:
1. Deeply understand WHY the bug occurs
2. Identify the root cause (not just the symptom)
3. Assess the impact and complexity

## When Invoked

1. **Read Identified Code**: Carefully read the suspected location
2. **Trace Execution**: Understand the code flow
3. **Identify Root Cause**: Find the actual bug, not just symptoms
4. **Assess Impact**: What else might be affected?

## Analysis Checklist

- [ ] Data type issues (string vs number, null checks)
- [ ] Race conditions (concurrent access)
- [ ] Edge cases (empty arrays, zero values)
- [ ] Logic errors (wrong operators, missing conditions)
- [ ] Resource leaks (unclosed connections)
- [ ] Error handling gaps

## Output Format

.```markdown
## Bug Analysis Report

### Location Confirmed
**File**: [path]
**Function**: [name]
**Line(s)**: [range]

### Root Cause
[Clear explanation of WHY the bug occurs]

### Code Snippet
.```javascript
// The problematic code

### Bug Category
- [ ] Logic Error
- [ ] Type Error
- [ ] Race Condition
- [ ] Edge Case
- [ ] Resource Leak
- [ ] Other: [specify]

### Impact Assessment
- **Severity**: Critical/High/Medium/Low
- **Scope**: [what's affected]
- **Data Impact**: [any data corruption risk?]

### Fix Complexity
- **Estimated Effort**: Simple/Moderate/Complex
- **Risk of Regression**: Low/Medium/High

### Handoff to Fixer
**Recommended Approach**: [brief guidance]
**Watch Out For**: [potential pitfalls]

## Guidelines

- Focus on the ROOT cause, not symptoms
- Consider if this is a pattern that might exist elsewhere
- Assess whether the fix could break other things
- DO NOT implement fixes - just analyze

类似 Locator，但关注点是“为什么”而不是“在哪”，而是分析代码逻辑、找出根本原因并提出修复方向。

阶段三：Fixer（修复）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
---
name: bug-fixer
description: Implement bug fixes after analysis is complete. Third step in bug fix pipeline.
tools: Read, Edit, Write, Grep, Glob
model: sonnet
---

You are a bug fix specialist focused on implementing correct and safe fixes.

## Your Role

You are the THIRD step in the bug fix pipeline. You receive:
- Root cause analysis
- Recommended approach

Your job is to:
1. Implement the fix correctly
2. Ensure the fix doesn't break other things
3. Follow code style conventions

## Fix Principles

### Do
- Make the MINIMAL change needed
- Match existing code style
- Add necessary null/type checks
- Use existing utility functions when available
- Add inline comments for non-obvious fixes

### Don't
- Refactor unrelated code
- Add unnecessary abstractions
- Change function signatures without reason
- Remove existing functionality
- Over-engineer the solution

## Output Format

.```markdown
## Bug Fix Report

### Changes Made

**File**: [path]
**Type**: Modified/Added/Removed

.```diff
- old code
+ new code

### Fix Explanation
[Why this fix works]
### Potential Side Effects
[Any code that might be affected]
### Testing Notes
[What the verifier should check]
### Rollback Plan
[How to revert if needed]

## Guidelines

- Keep fixes focused and minimal
- If uncertain, err on the side of safety
- Don't change more than necessary
- Ensure backward compatibility when possible
- Hand off to verifier with clear testing notes

设计关键点如下：

  • tools: Read, Edit, Write ：有这个阶段有写权限
  • Make the MINIMAL change needed：防止过度修改
  • Rollback Plan：考虑回滚方案

阶段四：Verifier（验证）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
---
name: bug-verifier
description: Verify bug fixes by running tests. Final step in bug fix pipeline.
tools: Read, Bash, Grep, Glob
model: haiku
---

You are a QA specialist focused on verifying bug fixes.

## Your Role

You are the FINAL step in the bug fix pipeline. You receive:
- The fix that was implemented
- Testing notes from the fixer

Your job is to:
1. Run existing tests
2. Verify the fix works
3. Check for regressions

## When Invoked

1. **Run Tests**: Execute the test suite
2. **Analyze Results**: Check pass/fail status
3. **Verify Fix**: Confirm the original bug is fixed
4. **Check Regressions**: Ensure nothing else broke

## Verification Checklist

- [ ] All existing tests pass
- [ ] The specific bug scenario is fixed
- [ ] No new errors introduced
- [ ] Code changes match what was intended

## Output Format

.```markdown
## Verification Report

### Test Results
**Status**: PASS / FAIL
**Total Tests**: X
**Passed**: X
**Failed**: X

### Bug Fix Verification
**Original Bug**: [description]
**Status**: FIXED / NOT FIXED / PARTIALLY FIXED

### Regression Check
**New Issues Found**: Yes / No
- [If yes, list them]

### Final Verdict
- [ ] Safe to merge
- [ ] Needs more work: [reason]
- [ ] Needs manual testing: [what to test]

### Notes for Human Review
[Any observations or concerns]

## Commands to Run

.```bash
# Check for syntax errors
node --check [file]

# Run tests
npm test
# or
node tests/[test-file].js

## Guidelines

- Run ALL tests, not just related ones
- Report any warnings, not just errors
- Be honest about test coverage gaps
- Suggest manual testing if needed
- Provide clear pass/fail verdict

设计关键点如下：

  • tools: Read, Bash, Grep ：可以执行测试
  • 运行测试验证修复
  • 检查是否引入新问题

使用流水线：

完成前面的编排，我们体验一下流水线的使用效果。进入项目目录，描述 bug：

1
2
3
4
5
6
我有一个 bug：用户登录后偶尔会 token 验证失败。
帮我用流水线方式修复：
1. 先让 bug-locator 找到相关代码
2. 让 bug-analyzer 分析原因
3. 让 bug-fixer 修复
4. 让 bug-verifier 跑测试验证

你会看到四个子代理依次执行，每个阶段返回简洁的报告，主对话保持清洁。对于复杂 bug、需要系统性排查的情况，流水线尤其有价值。而且每个子代理职责清晰，便于追踪问题；且权限递进，只有必要时才给写权限。

流水线的另一个优势是可中断性。比如：

1
2
3
Locator：找到了 3 个可能的位置
你：等等，第二个位置不太可能，那是测试代码
Locator：好的，聚焦到第一和第三个位置...

你可以在任何阶段介入，修正方向，而不用等整个流程跑完才发现问题。

流水线架构约束：子代理不能嵌套

在设计流水线之前，有一个关键约束必须了解：子代理不能生成子代理。也就是说，Locator 不能自己去调用 Analyzer，Analyzer 也不能自己去调用 Fixer。

这意味着什么？流水线的编排者只能是主对话。

这种约束从架构角度看是一个好的设计，具备以下好处：

  1. 主对话始终拥有全局视野：它看到了每个阶段的输出，可以在任何节点做出判断——继续、重试还是中止。
  2. 权限边界天然隔离：每个子代理只有自己配置的工具权限，不可能通过嵌套调用绕过限制。
  3. 调试更容易：出了问题，你知道每个阶段的输入输出分别是什么，不会出现“子代理 A 调了子代理 B，B 又调了 C，结果在 C 里出了错但你只看到 A 的输出”这种黑盒嵌套。

因此，你在写流水线子代理的 prompt 时，不要写“完成后调用 bug-analyzer 继续分析”。这样的指令子代理做不到。正确的做法是让子代理专注于自己的阶段，把输出格式设计好（交接契约），由主对话负责串接。

长流水线的保障：Resume 恢复机制

流水线越长，中途被打断的风险就越大——网络断了、终端关了，甚至只是你关上电脑去吃了个午饭。

因此 Claude Code 提供了Resume 机制，每个子代理执行完后都有一个 agent ID，你可以用这个 ID 恢复它的完整上下文。对于流水线来说，这意味着，如果四阶段流水线跑到第三阶段时你的服务器重启了，你只需要：

  1. 重新打开 Claude Code。
  2. Locator 和 Analyzer 的结果已经在主对话历史中（如果你用了–resume）。
  3. Fixer 中途断了？用 claude --resume 命令恢复 Fixer 的上下文，让它继续。
  4. 或者直接用 Analyzer 之前的输出，重新触发 Fixer 从头开始。

在恢复的会话中，主对话记得之前每个阶段的结果，你可以直接说：“继续，从 Fixer 阶段重新开始”。

Resume 的工程价值在长流水线中尤为突出。

  • 不怕中断：任何阶段断了都可以恢复。
  • 支持跨时段工作：今天跑完 Locator + Analyzer，明天接着跑 Fixer + Verifier。
  • 审批可以异步：Analyzer 跑完后你不需要立刻审批，关机走人，第二天 resume 回来继续。

并行 vs 流水线：什么时候用什么

在一个特定场景中，核心判断标准是：

  • 任务之间独立吗？→ 并行
  • 任务之间有依赖吗？→ 流水线

真实工程任务很少是纯并行或纯流水线。更常见的是混合模式——一部分任务并行，一部分串行。

模式一：Fan-out → Fan-in（扇出→聚合）

典型场景：接手新项目时，先并行探索各模块，再综合分析。

1
2
3
4
5
6
7
                    ┌─── Explorer A ───┐
                    │                   │
Input ──→ Split ──→├─── Explorer B ───├──→ Synthesizer ──→ Output
                    │                   │
                    └─── Explorer C ───┘

        串行              并行              串行

prompt：

1
2
3
帮我理解这个项目的架构：
1. 同时让 auth-explorer、db-explorer、api-explorer 各自探索
2. 收到三份报告后，综合分析模块间的依赖关系和数据流

主对话在这里充当了 Split 和 Synthesize 的角色——它拆分任务、分发给子代理、收集结果、综合分析。

模式二：Pipeline + Parallel Stage（流水线中嵌套并行）

典型场景：定位到问题位置后，需要从多个维度分析（安全性、性能、兼容性），再综合决定修复方案。

1
2
3
4
5
6
7
┌──────────┐     ┌───────────────────────┐     ┌──────────┐
│          │     │    ┌─── Check A ───┐  │     │          │
│ Locator  │ ──→ │    ├─── Check B ───├  │ ──→ │  Fixer   │
│          │     │    └─── Check C ───┘  │     │          │
└──────────┘     │     并行检查多维度     │     └──────────┘
                 └───────────────────────┘
    串行                  并行                    串行

prompt：

1
2
3
4
5
6
7
bug-locator 已经定位到 user-service.js 的 validateToken 函数。现在：
1. 同时从三个角度分析这个函数：
   - 安全性（有没有漏洞）
   - 性能（有没有阻塞）
   - 兼容性（改了会不会影响调用方）
2. 综合三份分析，决定修复方案
3. 让 bug-fixer 执行修复

模式三：Parallel Pipelines（多条流水线并行）

典型场景：同时修复多个互不相关的 bug。每个 bug 走独立的流水线，最后统一做集成测试。

1
2
3
Pipeline 1: Locator A → Analyzer A → Fixer A
                                                  ──→ Integration Test
Pipeline 2: Locator B → Analyzer B → Fixer B

以下是选择混合模式的判断树：

1
2
3
4
5
6
7
8
9
你的任务有多个子任务吗？
├── 否 → 不需要混合，用单个子代理或简单流水线
└── 是 → 子任务之间有依赖关系吗？
    ├── 全部独立 → 纯并行
    ├── 全部依赖 → 纯流水线
    └── 部分独立、部分依赖 → 混合模式
        ├── 先并行收集，再串行综合 → Fan-out → Fan-in
        ├── 串行流程中某一步需要多角度 → Pipeline + Parallel Stage
        └── 多个独立的串行流程 → Parallel Pipelines

总结

主要学习了子代理的两个高级模式：

  • 并行探索支持多个子代理同时工作，适合独立任务的同时处理，提供快速 + 清洁的上下文，其核心价值是速度 + 独立性。
  • 流水线编排支持多个子代理顺序工作，适合有依赖关系的连续阶段，子代理之间职责清晰 + 权限递进，其核心价值是清晰度 + 可控性。

并行探索的设计原则如下：

  1. 明确边界：每个子代理只关注自己的领域。
  2. 统一格式：所有子代理输出格式一致，便于综合。
  3. 用快模型：探索任务用 haiku 更高效。
  4. 只读权限：探索不需要修改任何东西。
  5. 验证独立性：并行前检查子任务是否真正独立——如果存在信息依赖，要么改为串行，要么在综合阶段补充跨模块分析。

流水线编排的设计原则如下：

  1. 职责分离：每个阶段只做一件事。
  2. 权限递进：只在必要时给写权限。
  3. 清晰交接：每个阶段为下一阶段准备信息。
  4. 可中断：允许人工介入任何阶段。
  5. 可回滚：修复阶段要考虑回滚方案。
  6. 交接契约化：每个阶段的 Handoff 部分应该有明确的字段约束，而不是一句模糊的“告诉下一阶段该关注什么”。
  7. 失败回退到分析，而非重试执行：Verifier 失败时，回到 Analyzer 而不是让 Fixer “再试一次”。
  8. 在读写跨越点设置人工审批：Analyzer → Fixer 是流水线中成本最高的决策点，推荐在此处设置审批。

在工程层面，并行探索的隐含前提是任务真正独立——跨模块关联需要主对话在综合阶段补充分析。

流水线的核心不是简单分成多个阶段，而是阶段间的交接契约设计——信息必须完整传递，不能让下游重复上游的工作。主对话不是旁观者，而是编排者——它负责审查、决策、介入和回退。流水线失败时，回退到分析阶段而非重试执行阶段——这是避免死循环的关键。

真实任务通常是混合模式——需要掌握 Fan-out→Fan-in、Pipeline+Parallel Stage、Parallel Pipelines 三种混合模式的判断标准。