Subagent 使用技巧

什么是 Subagent

Subagent（子代理）是 Claude Code 内部使用的一种任务委派机制。当 Claude 面对复杂的任务时，它可以启动一个或多个子代理来处理特定的子任务，而主代理继续管理整体工作流。

在 Claude Code 的实现中，子代理对应的是内部的 Task 工具。你可以把它理解为 Claude 雇佣的”助手”——主 Claude 负责统筹规划，子代理负责执行具体的调研、分析或操作任务。

Subagent 的核心优势

• 减少主上下文消耗：子代理有自己的上下文窗口，不会占用主对话的空间
• 并行处理：多个子代理可以同时工作，加快任务完成速度
• 专注性：每个子代理只处理一个子任务，结果更精准
• 隔离性：子代理的失败不会影响主对话的上下文

Claude 何时会启动 Subagent

Claude Code 会在以下场景中自动创建子代理：

场景一：代码搜索与探索

当需要在大型代码库中搜索信息时：

> 这个项目中有哪些地方使用了 deprecated 的 API？

Claude 可能会启动一个子代理，专门负责搜索所有文件中的 deprecated 标记，然后将汇总结果返回给主代理。

场景二：多文件分析

当需要同时分析多个文件来理解一个问题时：

> 帮我梳理一下用户认证的完整流程，从前端登录到后端验证的每一步。

Claude 可能启动子代理分别分析前端组件、API 路由、中间件和服务层，最后在主对话中整合分析结果。

场景三：并行独立任务

当多个子任务之间相互独立时：

> 请同时检查以下三个模块的单元测试覆盖情况：
  - src/services/user-service.ts
  - src/services/order-service.ts
  - src/services/payment-service.ts

Claude 可以并行启动三个子代理分别处理，效率远高于顺序执行。

场景四：复杂的调试任务

当需要从多个角度调查问题时：

> 用户反馈登录偶尔失败，请排查可能的原因。

Claude 可能同时让子代理检查认证逻辑、数据库连接、Redis 会话管理和网络配置。

Subagent 的类型

根据任务性质，Claude 会启动不同类型的子代理。

探索型子代理（Explore）

专门用于代码搜索和项目探索。这类子代理会大量使用文件搜索和内容搜索工具：

• 搜索特定模式或关键词
• 分析目录结构
• 读取和理解特定文件
• 追踪函数调用链

这类子代理的特点是只读——它们不会修改任何文件，只负责收集和分析信息。

规划型子代理（Plan）

用于分析问题并制定解决方案。规划型子代理会：

• 阅读相关代码
• 分析架构和依赖关系
• 评估不同方案的优劣
• 输出结构化的执行计划

执行型子代理（Bash）

用于运行命令和脚本。这类子代理会：

• 执行构建命令
• 运行测试
• 检查命令输出
• 安装依赖

通用型子代理

处理不属于以上类别的综合性任务，可能同时涉及文件读取、分析和写入操作。

Subagent 如何减少主上下文消耗

这是 Subagent 最重要的优势之一。来看一个具体的对比。

不使用 Subagent 的情况

用户: 分析项目中所有的 API 端点，列出它们的路径、方法和参数。

Claude (主上下文):
- 读取 src/routes/user.ts (200 行) -> +200 行上下文
- 读取 src/routes/product.ts (350 行) -> +350 行上下文
- 读取 src/routes/order.ts (280 行) -> +280 行上下文
- 读取 src/routes/payment.ts (190 行) -> +190 行上下文
- 读取 src/routes/admin.ts (420 行) -> +420 行上下文
...

总消耗: 1440+ 行直接进入主上下文

使用 Subagent 的情况

用户: 分析项目中所有的 API 端点，列出它们的路径、方法和参数。

Claude (主上下文):
- 启动子代理，任务："分析所有路由文件，提取 API 端点信息"
- 等待子代理返回结果

子代理 (独立上下文):
- 读取所有路由文件
- 分析和整理端点信息
- 返回结构化的摘要给主代理

主上下文只接收: 子代理返回的精简摘要 (~50 行)

通过子代理，主上下文只需要接收最终的分析结果，而不是所有原始文件内容。这意味着你的主对话可以承载更多轮次的交互。

并行 Subagent 执行

当多个子任务互不依赖时，Claude 会并行启动多个子代理。

并行执行的表现

你可能会在 Claude 的输出中看到类似这样的进度指示：

正在执行 3 个并行任务...

[任务 1/3] 分析 user-service 模块...
[任务 2/3] 分析 order-service 模块...
[任务 3/3] 分析 payment-service 模块...

任务 2 完成 ✓
任务 1 完成 ✓
任务 3 完成 ✓

整合结果中...

并行的优势

假设每个子任务需要 10 秒：

• 顺序执行：3 个任务 = 30 秒
• 并行执行：3 个任务 ≈ 10 秒（取决于最慢的子代理）

在需要分析大型代码库的多个部分时，并行子代理能够显著缩短等待时间。

监控 Subagent 进度

Claude Code 会在终端中显示子代理的执行状态。

状态显示

在 Claude 使用子代理时，你通常能看到：

• 子代理的任务描述
• 子代理正在执行的操作（读取文件、运行命令等）
• 子代理完成的状态

通过对话了解进度

你可以直接询问当前的执行状况：

> 子代理的任务进行得怎样了？

不过在大多数情况下，你只需要等待最终结果即可。

高效利用 Subagent 的技巧

技巧一：给出清晰的任务分解

当你的需求天然包含多个独立部分时，明确地列出来：

> 请分别检查以下几个方面：
  1. 所有 API 端点的错误处理是否完善
  2. 数据库查询是否存在 N+1 问题
  3. 敏感数据是否有适当的脱敏处理

这种结构化的请求更容易让 Claude 启动并行子代理。

技巧二：利用 Subagent 做前期调研

在动手修改代码之前，先让 Claude 用子代理做一轮调研：

> 在修改任何代码之前，请先分析以下内容并给我一份报告：
  - 当前项目的测试覆盖率
  - 所有使用了 deprecated API 的文件
  - 可能受到这次修改影响的下游依赖

调研完成后，你可以基于报告决定下一步的行动。

技巧三：让 Subagent 处理冗长的验证工作

代码修改后的验证工作通常涉及大量输出（测试结果、lint 报告等），让子代理处理并返回摘要：

> 运行完整的测试套件，然后给我一份失败测试的摘要报告，
  不需要显示通过的测试。

技巧四：大型代码库中的定向搜索

在大型项目中搜索信息时，给子代理明确的搜索范围：

> 在 src/services/ 目录下搜索所有直接调用数据库的地方（没有通过 Repository 层），
  列出文件名和行号。

技巧五：多角度代码审查

利用子代理的并行能力做多维度的代码审查：

> 请从以下角度审查 src/services/payment-service.ts：
  1. 安全性：是否有注入风险或敏感数据泄露
  2. 错误处理：异常路径是否都有处理
  3. 性能：是否有不必要的重复计算或 I/O 操作
  4. 可维护性：代码结构、命名、注释是否清晰

Subagent 的局限性

了解子代理的局限性同样重要，这能帮你避免不切实际的期望。

局限一：上下文隔离

子代理无法访问主对话的完整上下文。如果你之前在主对话中讨论了很多细节，子代理并不知道这些内容。Claude 在创建子代理时会传递必要的任务描述，但不会传递整个对话历史。

这意味着，如果你在对话中定义了特定的术语或约定，需要在给子代理的任务描述中明确提及。

局限二：结果可能被简化

子代理返回给主代理的结果通常是经过精简的摘要。如果你需要完整的原始数据，可能需要直接让主代理处理而不是委派给子代理。

局限三：无法与子代理直接交互

你无法与正在执行的子代理直接对话或调整它的行为。只能等它完成后，在主对话中对结果提出反馈。

局限四：子代理的权限

子代理继承主代理的权限设置。如果主代理被限制了某些操作（例如通过 Hooks 阻止修改特定文件），子代理同样会受到这些限制。

局限五：结果不一定完美

子代理可能遗漏某些信息或做出不完全准确的分析。对于关键决策，建议你审查子代理的输出，必要时让主代理深入检查特定部分。

Subagent vs 直接操作

什么时候让 Claude 使用 Subagent

• 需要搜索大量文件
• 任务可以被分解为独立的子任务
• 主上下文空间紧张
• 多个维度的分析需要并行进行

什么时候避免使用 Subagent

• 简单的单文件操作
• 需要基于主对话完整上下文的决策
• 需要你实时介入和调整的操作
• 结果精度要求极高的关键操作

小结

Subagent 是 Claude Code 处理复杂任务的高效机制。核心要点：

• 自动委派：Claude 会根据任务复杂度自动决定是否使用子代理
• 上下文节约：子代理在独立上下文中工作，只将精简结果返回主对话
• 并行加速：多个独立子任务可以并行处理
• 结构化请求：清晰地分解任务有助于 Claude 更好地利用子代理
• 了解局限：子代理的上下文隔离、结果简化和不可交互等限制
• 合理使用：大规模搜索和分析适合子代理，精细操作适合直接处理