📚 编程进阶教程站

第 12 章 · 子代理与并行工作流 ​

本章目标：掌握 Claude Code 的子代理（subagent）派发机制，学会用并行编辑、maker-checker 模式和 git worktree 隔离来构建高效的多代理工作流。

12.1 什么是子代理 ​

Claude Code 的 Agent tool 允许主代理派发独立的"子任务执行者"。每个子代理拥有：

  • 独立的上下文窗口——不会占用主对话的空间；
  • 专属的工具集——可以限制其能力范围；
  • 明确的任务目标——完成后只返回结果摘要给主代理。
text
主代理（协调者）
├── 子代理 A：搜索代码库中的所有 API 端点
├── 子代理 B：阅读测试文件了解测试模式
└── 子代理 C：检查 package.json 的依赖版本

这种设计的核心价值是上下文隔离：大量中间探索结果留在子代理内部，主代理只收到精炼的结论。

12.2 派发子代理 ​

在对话中，Claude Code 会自动判断何时需要派发子代理。你也可以显式要求：

text
> 用一个子代理去搜索项目中所有使用 deprecated API 的地方，
  另一个子代理检查测试覆盖率，同时进行。

Claude Code 内部通过 Agent tool 调用实现：

json
{
  "tool": "Agent",
  "parameters": {
    "description": "Search deprecated APIs",
    "prompt": "Search the codebase for uses of deprecated APIs...",
    "tools": ["Read", "Grep", "Glob"]
  }
}

12.3 并行文件编辑 ​

当需要修改多个互不依赖的文件时，可以让多个子代理并行工作：

text
> 同时做以下三件事：
1. 给 src/api/users.ts 添加分页参数支持
2. 给 src/api/orders.ts 添加排序功能
3. 更新 src/types/api.ts 中对应的类型定义

Claude Code 会评估这些修改是否有冲突：

  • 无冲突 → 派发多个子代理并行执行；
  • 有冲突（如共享同一文件）→ 串行执行或合并为一个子代理。

并行的前提

并行子代理各自操作不同文件时最安全。如果两个子代理都要改同一个文件，后完成的会覆盖先完成的修改。Claude Code 通常能识别这种情况并自动串行化。

12.4 Maker-Checker 模式 ​

Anthropic 官方推荐的高可靠性模式：让一个子代理写代码，另一个独立子代理审查。

text
主代理
│
├── Maker 子代理：实现用户认证模块
│   └── 输出：auth.ts, auth.test.ts
│
└── Checker 子代理：审查 auth.ts 的安全性与正确性
    ├── 输入：diff + 原始需求描述
    ├── 工具限制：只有 Read/Grep（不能写文件）
    └── 返回：PASS 或 FAIL + 具体问题列表

为什么不让同一个代理自己检查自己？Anthropic 研究发现：模型评价自己的工作时存在系统性正向偏差——即使质量不达标也倾向于给出积极评估。分离"做事的人"和"验收的人" 是解决方案。

在 Anthropic 的受控实验中，同样的 Opus 4.5 模型和提示：

  • 单代理裸跑：20 分钟 / $9 / 核心功能不可用；
  • 三代理架构（planner + generator + evaluator）：6 小时 / $200 / 游戏完全可玩。

12.5 Worktree 隔离 ​

对于可能产生破坏性修改的长任务，用 git worktree 创建隔离工作区：

bash
# 主仓库不受影响
git worktree add ../feature-auth -b feature/auth

# 在隔离环境中运行 Claude Code
cd ../feature-auth
claude
text
~/my-project/           ← 主仓库（main 分支）
~/feature-auth/         ← worktree（feature/auth 分支）

实验完成后合并回主分支：

bash
cd ~/my-project
git merge feature/auth
git worktree remove ../feature-auth

这保证了即使子代理产生了错误修改，主分支依然干净。

本章小结 ​

  • 子代理拥有独立上下文和工具集，完成后只返回摘要；
  • 无冲突的文件修改可以并行派发，有冲突则自动串行；
  • Maker-Checker 模式分离创建者和审查者，克服自我评估偏差；
  • Git worktree 提供物理级隔离，适合高风险长任务。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 子代理的核心优势是什么？

2. Maker-Checker 模式中，Checker 子代理应该被限制哪些工具？

3. 什么时候应该使用 git worktree 隔离子代理的工作？

4. 两个子代理分别要修改同一个文件的同一区域，Claude Code 会怎么处理？

🛠️ 动手实践 ​

  1. 让 Claude Code 用两个并行子代理分别为你项目中的两个不同模块添加 JSDoc 注释，观察执行过程。
  2. 实现 Maker-Checker 流程：让一个子代理写一个函数，另一个子代理审查它，把审查意见反馈给第一个修正。
  3. 用 git worktree 创建隔离环境，在里面让 Claude Code 做一次大范围重构，对比主分支是否受到影响。

完成后进入下一章：Hooks 自动化钩子。