Claude Code 子代理实战指南

很多人把 Claude Code 当作「一问一答」的工具在用，但它真正强大的地方在于子代理系统——你可以同时派出多个专精不同方向的子代理并行工作。这篇文章基于大量实际使用经验，记录每种子代理的真实表现和选择策略。

子代理和主对话是隔离的：每个子代理启动时看不到你之前的对话历史，所以 prompt 的质量直接决定子代理的表现。把它当作一个刚走进房间的聪明同事来 brief。

真实可用的子代理类型

Claude Code 目前提供以下子代理类型，每种有明确的工具权限和适用场景：

Explore — 快速代码探索

实际能力：只读操作，不能编辑文件。拥有 Glob、Grep、Read 等搜索工具，速度快。

什么时候该用：

在不确定某个关键词/类/函数在哪个文件时
需要快速了解一个不熟悉的目录结构
想搜索某个 API 在项目中的所有调用点

调用时的关键参数：你可以指定 thoroughness 级别——quick（简单定位）、medium（中等探索）、very thorough（全面分析）。大多数场景用 medium 就够了，very thorough 适合跨模块排查。

真实场景：

"这个项目里所有调用 sendNotification 的地方在哪？
包括直接调用和间接引用，重点看 src/services 和 src/workers 目录。"

踩坑经验：

Explore 代理不能编辑文件。如果你让它”找到并修改”，它只会找到但无法修改
对于简单的文件定位（你已经知道大概路径），直接用 Glob/Grep 比派子代理更快
搜索结果不会自动返回给你的主对话——你需要等它完成后才能看到汇总

Plan — 架构设计

实际能力：只读 + 分析。能读代码、搜索文件，但同样不能编辑。专门用来做方案设计。

什么时候该用：

准备重构一个复杂模块前，先让它出方案
需要评估某个改动的影响范围
想要对比两种技术方案的优劣

真实场景：

"我要把项目从 Webpack 迁移到 Vite。
当前项目是 React 18 + TypeScript，有自定义的 Webpack loader 处理 .svg 和 .graphql 文件。
帮我出一个分步迁移计划，标注哪些步骤风险高。"

踩坑经验：

Plan 代理出的方案质量高度依赖你给的上下文。只说”帮我重构”会得到泛泛之谈；告诉它具体文件路径、当前问题、约束条件，方案才有落地性
不要让 Plan 代理直接执行——它只做规划。规划确认后，由你或 general-purpose 代理来执行

general-purpose — 全能执行

实际能力：拥有完整的工具访问权限（读、写、搜索、Bash 命令、甚至再派子代理）。

什么时候该用：

需要实际修改文件的任务
需要运行命令（比如跑测试、装依赖）
复杂的多步骤任务

真实场景：

"在 src/utils/date.ts 里有一个 formatDate 函数，
它现在不处理时区。请修改它支持传入 timezone 参数，
默认用 Asia/Shanghai。同时更新对应的测试文件。"

踩坑经验：

general-purpose 是最常用但也最容易滥用的类型。如果任务只需要搜索，用 Explore 更快
它可以再派子代理（嵌套），但嵌套太深会导致上下文丢失和 token 浪费
对于需要 git 安全操作的场景，记得指定 isolation: "worktree" 让它在独立工作树中操作

writer — 内容创作

实际能力：拥有完整工具权限，但 prompt 模板专门针对网站内容写作优化。

什么时候该用：

写文档、博客、README
需要特定的文案风格（技术文档、营销文案等）

其他专用代理

Claude Code 还有几个窄领域的专用代理：

statusline-setup：配置状态行显示（只有 Read 和 Edit 权限）
code-reviewer：独立的代码审查视角，适合想要”第二意见”时使用

子代理的核心机制

隔离性：最重要的特性

每个子代理启动时是一张白纸——它不知道你之前聊了什么。这意味着：

# 差的 prompt（缺乏上下文）
"把刚才讨论的改动实现一下"
 
# 好的 prompt（自包含）
"在 /src/components/UserProfile.tsx 文件中，
将第 45 行的 useState 改为 useReducer 来管理表单状态。
原因：当前有 5 个独立的 useState 导致状态更新不一致。
改完后确保现有的 UserProfile.test.tsx 测试通过。"

前台 vs 后台运行

前台（默认）：你等它完成才能继续。适合「需要结果才能下一步」的场景
后台：它在后台跑，你继续做别的事。适合独立任务

实际建议：如果你要同时做多件不相关的事，比如一边让代理 A 跑测试、一边让代理 B 写文档，就用后台运行。但如果你需要代理 A 的搜索结果来决定下一步，必须用前台。

worktree 隔离：保护你的 git 状态

指定 isolation: "worktree" 后，子代理会在一个临时的 git worktree 中工作。它的所有文件修改都不会影响你当前的工作区。

适合用的场景：

让子代理尝试一个不确定的重构方案
并行尝试两种不同的实现思路
任何你不想污染当前分支的操作

注意：如果子代理没有做任何修改，worktree 会自动清理。如果有修改，会返回 worktree 的路径和分支名，你可以决定是否合并。

多代理并行的实战模式

模式一：探索 + 执行分离

先用 Explore 代理摸清情况，再用 general-purpose 执行：

第一步（Explore 代理）：
"找出所有使用 legacy API v1 的文件，列出文件路径和对应的行号"
 
第二步（general-purpose 代理，基于第一步结果）：
"把以下文件中的 v1 API 调用迁移到 v2：
- src/services/user.ts:23
- src/services/order.ts:45,67
- src/hooks/useAuth.ts:12
迁移规则是：xxx → yyy"

模式二：并行独立任务

同时派出多个代理处理不相关的任务：

代理 A（后台）："跑 npm test 并汇总失败的用例"
代理 B（后台）："检查 package.json 中有哪些依赖版本过旧"
代理 C（前台）："修复 src/utils/format.ts 中的日期解析 bug"

模式三：Plan → Review → Execute

1. Plan 代理："给这个需求出一个技术方案"
2. 你审阅方案并调整
3. general-purpose 代理："按照以下方案执行：[具体步骤]"
4. code-reviewer 代理（可选）："审查刚才的修改，给出独立意见"

常见错误与避坑

不要：让子代理自己决定做什么

子代理没有你的业务上下文。「帮我看看这个项目有什么可以改进的」这类开放指令会浪费大量 token 产出泛泛之谈。

改为：明确说出你要什么、为什么、在哪里。

不要：嵌套太多层子代理

general-purpose 代理可以再派子代理，但每多一层就会丢失更多上下文。两层通常是极限，三层以上基本会偏离目标。

不要：所有任务都用子代理

简单任务（修改一行代码、搜索一个文件名）直接在主对话里做更快。子代理有启动成本（context 准备、prompt 传输），只有在任务确实需要隔离或并行时才值得用。

不要：忘记子代理的工具限制

Explore 和 Plan 代理不能编辑文件。如果你的任务需要修改代码，必须用 general-purpose 或 writer。这是最常见的选错代理类型的场景。

选择决策树

任务需要修改文件吗？
├── 是 → 是写代码还是写文档？
│   ├── 写代码 → general-purpose
│   └── 写文档/内容 → writer
└── 否 → 是需要搜索还是需要方案？
    ├── 搜索/定位 → Explore
    ├── 方案设计 → Plan
    └── 代码审查 → code-reviewer