你好，我是黄佳。
欢迎来到 Claude Code 工程化实战的第 7 讲。前面我们学习了只读型子代理和高噪声任务处理，今天我们要探索子代理的另外两个强大工程应用场景——并行探索和流水线编排。
这两个应用分别解决的问题是什么呢？并行探索,当你需要同时从多个角度理解或处理一件事时启用；流水线编排,当一个复杂任务可以拆成多个连续阶段时启用。
今天的内容比较多，学习目标包括：
掌握并行探索和流水线编排的基本使用。
通过实战项目体验两种模式的差异。
理解“独立→并行，依赖→流水线”的判断标准。
学会设计阶段间的“交接契约”，确保流水线信息不丢失。
掌握混合模式——当一个任务既有并行部分，又有串行部分时如何编排。
理解主对话作为“编排者”的角色定位和决策介入点。
我们还是老规矩，从两个真实场景来开始。
场景一：新接手一个大型项目
你刚加入一个团队，需要快速理解一个包含几十个模块的后端项目。传统方式下，我们可能要花费很久的时间熟悉。
- 看 auth 模块 → 花 3 小时
- 看 database 模块 → 花 5 小时
- 看 api 模块 → 花 40 分钟
- 综合理解 → ???
串行探索既慢，又容易在中途忘记前面看到的细节。
而并行探索的方式就不一样了。 
三个子代理同时工作，各自探索自己的领域，最后汇总成一份综合报告。
场景二：修复一个复杂的 bug
遇到一个“用户登录后偶尔 token 验证失败”的 bug。这种间歇性问题最难调试。
如果让主对话直接处理，上下文会很快被塞满：
搜索相关代码 → 200 行输出
分析可能的原因 → 又是 200 行
修复 → 100 行
验证 → 又是测试输出……
而流水线的方式，每个阶段只返回摘要，主对话始终保持清洁，可以随时介入做决策。 
项目一：并行探索
接下来我们直接进入实战演练。
并行探索子代理
实战项目位于 03-SubAgents/projects/04-parallel-explore/，包含三个专门的探索子代理。
04-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子代理的配置如下。
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
Locate Auth Code: Use Glob to find auth-related files
- Patterns:
**/auth/**,**/*auth*,**/*login*,**/*session*,**/*jwt*
- Patterns:
Analyze Structure: Read key files and understand:
- How users authenticate
- How tokens are generated/validated
- How sessions are managed
- How permissions are checked
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 的命令行中输入：
同时让 auth-explorer、db-explorer、api-explorer 探索各自模块， 然后汇总给我一个整体架构理解
此时 Claude 会完成下述步骤。
并行启动三个子代理
各自独立执行探索任务
收集三份报告
综合成一份整体架构理解
并行执行的价值显而易见。传统情况下，如果不使用子代理并行处理，假设每个模块用时30 秒，串行总耗时90秒，主对话上下文会被三个模块的探索过程塞满；而并行整体用时30秒，且只有三份简洁报告。并行执行不仅更快，而且主对话的上下文更清洁。
前台与后台运行
在 Claude Code 中，子代理默认在前台运行——你能看到它实时输出的每一行。并行探索时，如果三个子代理都在前台，你的终端会被占满。
当一个子代理正在前台运行时，按 Ctrl+B 可以将它切换到后台继续执行。这在并行场景下非常实用。
我们梳理一下操作流程。
触发 auth-explorer → 看到它开始搜索
按 Ctrl+B → auth-explorer 转入后台
触发 db-explorer → 看到它开始搜索
按 Ctrl+B → db-explorer 转入后台
触发 api-explorer → 看到它开始搜索
按 Ctrl+B → api-explorer 转入后台（或留在前台观察）
三个子代理在后台同时执行，完成后返回结果
后台运行的一个重要限制是无法弹出权限确认对话框。所以如果子代理需要执行 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，而是设计约束。并行探索的综合分析必须由主对话来完成。子代理负责“收集原始情报”，主对话负责“连点成线”。
在这个场景中，因为主对话可以进行汇总，因此整体分析结果仍然可行，但在有些情况下，各任务间强相互依赖时，就必须等待。
那么，如何判断是否适合并行，检查清单如下：
每个子任务能否独立完成，不需要另一个子任务的结果？
是 → 可以并行
否 → 必须串行或混合模式
遗漏跨模块关联是否可接受？
是（主对话会综合分析）→ 可以并行
否（遗漏可能导致错误决策）→ 考虑串行或增加综合分析阶段
子任务的输出粒度是否匹配？
是（都是模块级概览）→ 容易综合
否（有的是文件级，有的是函数级）→ 综合困难，先统一粒度
项目二：流水线编排
了解了并行探索的模式，我们再来看看流水线编排如何实现。
Bug修复流水线
实战项目位于03-SubAgents/projects/05-bugfix-pipeline/，包含四个流水线子代理。
05-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修复流水线的四个阶段。
每个代理职责和角色清晰，每个节点都可被单独替换 / 回滚 / 审计。
Locator：只回答“在哪”
Analyzer：只回答 “为什么”
Fixer：只负责 “怎么改”
Verifier：只负责 “改对没有”
下面我们按“定位、分析、修复、验证”的分工顺序挨个拆解。
阶段一：Locator（定位）
---
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（分析）
---
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（修复）
---
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（验证）
---
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：
我有一个 bug：用户登录后偶尔会 token 验证失败。
帮我用流水线方式修复：
1. 先让 bug-locator 找到相关代码
2. 让 bug-analyzer 分析原因
3. 让 bug-fixer 修复
4. 让 bug-verifier 跑测试验证
你会看到四个子代理依次执行，每个阶段返回简洁的报告，主对话保持清洁。对于复杂 bug、需要系统性排查的情况，流水线尤其有价值。而且每个子代理职责清晰，便于追踪问题；且权限递进，只有必要时才给写权限。
流水线的另一个优势是可中断性。比如：
Locator：找到了 3 个可能的位置
你：等等，第二个位置不太可能，那是测试代码
Locator：好的，聚焦到第一和第三个位置...
你可以在任何阶段介入，修正方向，而不用等整个流程跑完才发现问题。
流水线的架构约束：子代理不能嵌套
在设计流水线之前，有一个关键约束必须了解：子代理不能生成子代理。也就是说，Locator 不能自己去调用 Analyzer，Analyzer 也不能自己去调用 Fixer。
这意味着什么？流水线的编排者只能是主对话。
错误的想象：
Locator 自动调用 Analyzer → Analyzer 自动调用 Fixer → Fixer 自动调用 Verifier
（这在 Claude Code 中做不到）
实际的架构：
主对话 → 调用 Locator → 收到结果 → 调用 Analyzer → 收到结果 → 调用 Fixer → 收到结果 → 调用 Verifier
（每一步都经过主对话）
这个约束其实是一个好的设计，原因有三个。
主对话始终拥有全局视野：它看到了每个阶段的输出，可以在任何节点做出判断——继续、重试还是中止。
权限边界天然隔离：每个子代理只有自己配置的工具权限，不可能通过嵌套调用绕过限制。
调试更容易：出了问题，你知道每个阶段的输入输出分别是什么，不会出现“子代理 A 调了子代理 B，B 又调了 C，结果在 C 里出了错但你只看到 A 的输出”这种黑盒嵌套。
因此，你在写流水线子代理的 prompt 时，不要写“完成后调用 bug-analyzer 继续分析”。这样的指令子代理做不到。正确的做法是让子代理专注于自己的阶段，把输出格式设计好（交接契约），由主对话负责串接。
长流水线的保障：Resume 恢复机制
流水线越长，中途被打断的风险就越大——网络断了、终端关了，甚至只是你关上电脑去吃了个午饭。
因此 Claude Code 提供了 Resume 机制，每个子代理执行完后都有一个 agent ID，你可以用这个 ID 恢复它的完整上下文。对于流水线来说，这意味着，如果四阶段流水线跑到第三阶段时你的服务器重启了，你只需要：
重新打开 Claude Code。
Locator 和 Analyzer 的结果已经在主对话历史中（如果你用了–resume）。
Fixer 中途断了？用 claude --resume 命令恢复 Fixer 的上下文，让它继续。
或者直接用 Analyzer 之前的输出，重新触发 Fixer 从头开始。
在恢复的会话中，主对话记得之前每个阶段的结果，你可以直接说：“继续，从 Fixer 阶段重新开始”。
Resume 的工程价值在长流水线中尤为突出。
不怕中断：任何阶段断了都可以恢复。
支持跨时段工作：今天跑完 Locator + Analyzer，明天接着跑 Fixer + Verifier。
审批可以异步：Analyzer 跑完后你不需要立刻审批，关机走人，第二天 resume 回来继续。
流水线的核心工程问题：阶段间的“交接契约”
到目前为止，我们看到了流水线的骨架——四个阶段能够各司其职。但在实际使用中，流水线最容易出问题的不是每个阶段本身，而是阶段之间的信息传递。你可能已经意识到了，这里的所谓交接，就是我们在第 4 讲“量体裁衣”中所介绍的 Handoffs模式的应用。
什么是“交接契约”？
流水线中，前一个子代理的输出就是后一个子代理的输入（通过主对话转发）。如果前一个阶段输出的信息不完整或格式不对，后一个阶段就会“瞎干”。
如果Locator 输出："bug 可能在 auth 模块里。"
↓
Analyzer 收到这句话后："auth 模块？哪个文件？哪个函数？我该分析什么？"
↓
结果：Analyzer 自己又做了一遍 Locator 的工作，流水线形同虚设。
因此，在每个阶段的输出格式中，应该有一个明确的 Handoff（交接） 部分，告诉下一阶段“你需要关注什么”。
## Locator → Analyzer 的交接契约
### Locator 必须提供：
1. 具体文件路径（不是"大概在某模块"）
2. 具体函数/方法名
3. 嫌疑代码行号范围
4. 为什么怀疑这里（搜索证据）
5. 相关联的其他文件列表
### Analyzer 期望收到：
1. 明确的调查范围（文件+函数）
2. 症状描述（用户看到什么）
3. 已排除的可能性（Locator 搜索过但排除的位置）
## Analyzer → Fixer 的交接契约
### Analyzer 必须提供：
1. 根因定位（一句话）
2. 修复方向建议（不超过 3 个方案）
3. 推荐方案及理由
4. 修改涉及的文件列表
5. 需要注意的边界条件
### Fixer 期望收到：
1. 明确的"改什么"（文件+位置+原因）
2. 明确的"怎么改"（方向，不需要具体代码）
3. 明确的"别碰什么"（不应该修改的部分）
## Fixer → Verifier 的交接契约
### Fixer 必须提供：
1. 改了哪些文件（diff 格式）
2. 为什么这么改
3. 可能的副作用清单
4. 需要运行的测试命令
5. 验证通过的标准是什么
### Verifier 期望收到：
1. 变更清单（知道要验证什么）
2. 测试命令（知道怎么验证）
3. 预期结果（知道什么算通过）
在 prompt 中实现交接契约
回看 Locator 的配置，它的输出格式中有：
### Handoff to Analyzer
[What the analyzer should focus on]
这一段就是交接契约的实现。但原始版本太模糊了——“What the analyzer should focus on”没有约束输出什么。
我们可以这样改进一下原始版本。
### Handoff to Analyzer
- **Primary suspect**: [file:function:line_range]
- **Symptoms to reproduce**: [具体步骤]
- **Hypothesis**: [为什么怀疑这里]
- **Already excluded**: [搜索过但排除的位置及原因]
- **Related files to check**: [可能受影响的其他文件]
此处需要遵循的经验法则是——交接时信息量要充足，让下一阶段无需重复上一阶段的工作。如果 Analyzer 收到 Locator 的输出后，还需要自己 Grep 一遍才能开始分析，说明交接契约设计不合格。
主对话的角色：编排者，而非旁观者
在 Claude Code 中，流水线不是一个“启动后自动跑完”的系统。主对话就是编排者——它负责触发每个阶段、审查每个阶段的输出，决定是否继续、重试或中止、同时在阶段之间注入人工判断。
编排者的四种介入形式
编排者有全自动、关键阶段审批、逐阶段审批和回退重试四种介入形式。
形式一：全自动（信任度高）
┌─────────┐ 自动 ┌─────────┐ 自动 ┌─────────┐ 自动 ┌─────────┐
│ Locator │ ────→ │ Analyzer│ ────→ │ Fixer │ ────→ │Verifier │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
形式二：关键阶段审批（推荐）
┌─────────┐ 自动 ┌─────────┐ ┌─────────┐ 自动 ┌─────────┐
│ Locator │ ────→ │ Analyzer│ ─?──→ │ Fixer │ ────→ │Verifier │
└─────────┘ └─────────┘ ↑ └─────────┘ └─────────┘
人工审批
"这个根因分析对吗？
确认后再让它改代码"
形式三：逐阶段审批（谨慎）
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Locator │ ─?──→ │ Analyzer│ ─?──→ │ Fixer │ ─?──→ │Verifier │
└─────────┘ ↑ └─────────┘ ↑ └─────────┘ ↑ └─────────┘
人工审批 人工审批 人工审批
形式四：回退重试（遇到问题时）
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Locator │ ────→ │ Analyzer│ ────→ │ Fixer │
└─────────┘ └─────────┘ └────┬────┘
↑ │
└──────────────────┘
"修复方向不对，
回退到分析阶段"
就Bug修复这个具体问题而言，并不是每个阶段都需要人工审批，但有一个关键决策点必须把关：
Analyzer → Fixer
↑
这个位置最关键！
为什么？因为这是从只读到读写的跨越——一旦 Fixer 开始修改代码，回退成本就高了。在这个位置审查 Analyzer 的根因分析，确认方向正确后再继续，是性价比最高的介入方式。
编排者的 prompt 设计
你可以在触发流水线时明确编排方式：
帮我修复这个 bug：用户登录后偶尔 token 验证失败。
执行方式：
1. 先让 bug-locator 定位 → 自动传给 bug-analyzer
2. bug-analyzer 分析完后 → 先给我看根因分析，我确认后再继续
3. 我确认后 → 让 bug-fixer 修复 → 自动传给 bug-verifier
4. bug-verifier 验证完给我最终报告
这就是形式二：关键阶段审批的实际使用方式。
当流水线阶段失败时怎么办？
真实使用中，流水线不总是顺利的。每个阶段都可能失败，需要不同的处理策略：
死循环是流水线设计中一个常见陷阱，避免死循环的一个关键原则是——Verifier 失败时不要让 Fixer “再试一次”。
错误做法：
Verifier 说测试失败 → 让 Fixer 再改一次 → Verifier 又失败 → 再改...
（进入死循环，Fixer 在瞎猜）
正确做法：
Verifier 说测试失败 → 回退到 Analyzer
→ Analyzer 结合 Fixer 的修改和 Verifier 的失败信息重新分析
→ 可能发现根因判断有误
→ 给出新的修复方向
→ Fixer 基于新分析修复
这是因为Verifier 的失败信息是新的证据，应该反馈给 Analyzer 而不是 Fixer。Fixer 只负责执行，不负责判断方向。
在实际使用中，建议设定一个心理上的重试上限。
同一阶段重试超过 2 次 → 停下来重新审视问题
整个流水线回退超过 1 次 → 可能需要人工介入深度分析
如果 AI 在反复循环但没有进展，这时你需要考虑以下原因。
问题比预想的复杂，需要更多上下文
问题的根因不在当前代码中（可能是配置、环境、数据问题）
子代理的 prompt 对这类问题的覆盖不够
并行 vs 流水线：什么时候用什么
至此，我们已经全面了解了并行和流水线这两种子代理模式，在一个特定场景中，核心判断标准是：
任务之间独立吗？→ 并行
任务之间有依赖吗？→ 流水线
真实工程任务很少是纯并行或纯流水线。更常见的是混合模式——一部分任务并行，一部分串行。
模式一：Fan-out → Fan-in（扇出→聚合）
典型场景：接手新项目时，先并行探索各模块，再综合分析。
┌─── Explorer A ───┐
│ │
Input ──→ Split ──→├─── Explorer B ───├──→ Synthesizer ──→ Output
│ │
└─── Explorer C ───┘
串行 并行 串行
prompt：
帮我理解这个项目的架构：
1. 同时让 auth-explorer、db-explorer、api-explorer 各自探索
2. 收到三份报告后，综合分析模块间的依赖关系和数据流
主对话在这里充当了Split 和 Synthesize的角色——它拆分任务、分发给子代理、收集结果、综合分析。
模式二：Pipeline + Parallel Stage（流水线中嵌套并行）
典型场景：定位到问题位置后，需要从多个维度分析（安全性、性能、兼容性），再综合决定修复方案。
┌──────────┐ ┌───────────────────────┐ ┌──────────┐
│ │ │ ┌─── Check A ───┐ │ │ │
│ Locator │ ──→ │ ├─── Check B ───├ │ ──→ │ Fixer │
│ │ │ └─── Check C ───┘ │ │ │
└──────────┘ │ 并行检查多维度 │ └──────────┘
└───────────────────────┘
串行 并行 串行
prompt：
bug-locator 已经定位到 user-service.js 的 validateToken 函数。现在：
1. 同时从三个角度分析这个函数：
- 安全性（有没有漏洞）
- 性能（有没有阻塞）
- 兼容性（改了会不会影响调用方）
2. 综合三份分析，决定修复方案
3. 让 bug-fixer 执行修复
模式三：Parallel Pipelines（多条流水线并行）
典型场景：同时修复多个互不相关的 bug。每个 bug 走独立的流水线，最后统一做集成测试。
Pipeline 1: Locator A → Analyzer A → Fixer A
──→ Integration Test
Pipeline 2: Locator B → Analyzer B → Fixer B
这里给出选择混合模式的判断树。
你的任务有多个子任务吗？
├── 否 → 不需要混合，用单个子代理或简单流水线
└── 是 → 子任务之间有依赖关系吗？
├── 全部独立 → 纯并行
├── 全部依赖 → 纯流水线
└── 部分独立、部分依赖 → 混合模式
├── 先并行收集，再串行综合 → Fan-out → Fan-in
├── 串行流程中某一步需要多角度 → Pipeline + Parallel Stage
└── 多个独立的串行流程 → Parallel Pipelines
本讲小结
今天我们学习了子代理的两个高级模式。
并行探索支持多个子代理同时工作，适合独立任务的同时处理，提供快速 + 清洁的上下文，其核心价值是速度 + 独立性。
流水线编排支持多个子代理顺序工作，适合有依赖关系的连续阶段，子代理之间职责清晰 + 权限递进，其核心价值是清晰度 + 可控性。
总结一下并行探索的设计原则。
明确边界：每个子代理只关注自己的领域。
统一格式：所有子代理输出格式一致，便于综合。
用快模型：探索任务用 haiku 更高效。
只读权限：探索不需要修改任何东西。
验证独立性：并行前检查子任务是否真正独立——如果存在信息依赖，要么改为串行，要么在综合阶段补充跨模块分析。
流水线的设计原则如下。
职责分离：每个阶段只做一件事。
权限递进：只在必要时给写权限。
清晰交接：每个阶段为下一阶段准备信息。
可中断：允许人工介入任何阶段。
可回滚：修复阶段要考虑回滚方案。
交接契约化：每个阶段的 Handoff 部分应该有明确的字段约束，而不是一句模糊的“告诉下一阶段该关注什么”。
失败回退到分析，而非重试执行：Verifier 失败时，回到 Analyzer 而不是让 Fixer “再试一次”。
在读写跨越点设置人工审批：Analyzer → Fixer 是流水线中成本最高的决策点，推荐在此处设置审批。
在工程层面，并行探索的隐含前提是任务真正独立——跨模块关联需要主对话在综合阶段补充分析。
流水线的核心不是简单分成多个阶段，而是阶段间的交接契约设计——信息必须完整传递，不能让下游重复上游的工作。主对话不是旁观者，而是编排者——它负责审查、决策、介入和回退。流水线失败时，回退到分析阶段而非重试执行阶段——这是避免死循环的关键。
真实任务通常是混合模式——需要掌握 Fan-out→Fan-in、Pipeline+Parallel Stage、Parallel Pipelines 三种混合模式的判断标准。
思考题
你的项目中有没有适合并行探索的场景？比如需要同时理解多个模块的情况？
除了 bug 修复，还有哪些任务适合用流水线模式？比如代码迁移、功能开发等。
如果一个任务既有并行部分又有串行部分，你会怎么设计子代理的组合？
为以下流水线设计交接契约——需求文档 → 技术方案 → 代码实现 → 测试验证。每个阶段的 Handoff 应该包含哪些字段？
假设你的 bug-fixer 修复后，bug-verifier 跑测试发现原来的 bug 没修好，但引入了一个新的测试失败。你作为编排者应该怎么操作？写出具体的指令。
动手练习
练习一：并行探索
进入 projects/04-parallel-explore/ 目录
运行 同时让三个 explorer 探索各自模块，汇总成整体架构理解
观察三份报告和最终综合结果
练习二：流水线编排
进入 projects/05-bugfix-pipeline/ 目录
用流水线方式修复其中一个 bug
在中间阶段试着介入，看看如何影响后续阶段
练习三：交接契约验证
在练习二中，当 Locator 完成后，阅读它的 Handoff 部分。
判断：如果你是 Analyzer，这些信息够不够你开始分析？缺什么？
修改 Locator 的 prompt，让 Handoff 部分更完整，重新跑一次，对比差异。
练习四：混合模式实操
用 Fan-out → Fan-in 模式理解项目：同时让三个 explorer 探索，然后综合分析。
基于综合分析中发现的问题，切换到流水线模式修复其中一个。
思考：哪些步骤你做了人工介入？哪些步骤你让它自动继续了？为什么？
按照原定计划下一讲我们将进入新的主题：Skills 技能系统。不过，Claude在2026年2月6日最新推出的“团队协作”（Agent Teams）功能很明显更适合整合进入SubAgent专题，因此佳哥正在积极创作相关内容，期待周五和大家见面。
欢迎你在留言区和我交流讨论。如果这一讲对你有启发，别忘了分享给身边更多朋友。