SubAgent 子代理

SubAgent: In-Session Worker Agents

SubAgent 是 Claude Code 多代理架构的核心组件。它允许主 Agent 在同一个会话内启动一个或多个工作者代理，将复杂任务拆解为可并行或串行执行的子任务。每个 SubAgent 拥有独立的上下文窗口，但共享同一个项目环境。

核心概念

Core Concepts

SubAgent 本质上是主 Agent 通过 Agent 工具调用启动的子进程。它们在同一个 Claude Code 会话中运行，受主 Agent 的生命周期管理。

为什么需要 SubAgent？

Why SubAgent?

场景	不使用 SubAgent	使用 SubAgent
搜索多个代码库	串行搜索，耗时长	并行搜索，速度翻倍
多模块测试	逐个执行测试	同时运行所有测试套件
代码审查 + 修复	审查完再修复	一个探索问题，一个准备修复
大型重构	单线程处理	多个 Agent 分别处理不同文件

SubAgent 与普通工具调用的区别

SubAgent vs. Regular Tool Calls

┌──────────────────────────────────────────┐
│              主 Agent (Main)              │
│                                          │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  │
│  │SubAgent │  │SubAgent │  │SubAgent │  │
│  │   #1    │  │   #2    │  │   #3    │  │
│  │(Explore)│  │(General)│  │ (Plan)  │  │
│  └─────────┘  └─────────┘  └─────────┘  │
│                                          │
└──────────────────────────────────────────┘

普通工具调用（如 Read、Bash）是同步的、无状态的。而 SubAgent 拥有：

独立的上下文窗口：不占用主 Agent 的上下文空间
独立的工具集：根据类型可使用不同的工具
可并行执行：多个 SubAgent 可同时工作
状态保持：在其生命周期内保持对话状态

Agent 工具调用方式

How to Invoke the Agent Tool

主 Agent 通过 Agent 工具启动 SubAgent。基本调用格式如下：

json

{
  "tool": "Agent",
  "parameters": {
    "prompt": "搜索项目中所有使用了 deprecated API 的文件，列出文件路径和行号",
    "subagent_type": "explore"
  }
}

完整参数示例

Full Parameter Example

json

{
  "tool": "Agent",
  "parameters": {
    "prompt": "在 src/components 目录下，将所有 class 组件重构为函数组件",
    "subagent_type": "general-purpose",
    "run_in_background": true,
    "isolation": "worktree"
  }
}

参数说明表

Parameter Reference

参数	类型	必填	说明
`prompt`	string	是	传递给 SubAgent 的任务描述
`subagent_type`	string	否	SubAgent 的类型，默认 `general-purpose`
`run_in_background`	boolean	否	是否在后台执行，默认 `false`
`isolation`	string	否	隔离模式，如 `worktree`

SubAgent 类型

SubAgent Types

Claude Code 提供多种预定义的 SubAgent 类型，每种类型针对不同的使用场景进行了优化。

general-purpose 通用代理

General-Purpose Agent

通用代理拥有完整的工具集，可以读写文件、执行命令、搜索代码等。适合需要对项目进行实际修改的场景。

json

{
  "prompt": "修复 src/utils/parser.ts 中的类型错误",
  "subagent_type": "general-purpose"
}

可用工具：Read、Write、Edit、Bash、Grep、Glob 等全部工具

适用场景：

代码修改与重构
Bug 修复
新功能实现
文件创建与编辑

Explore 探索代理

Explore Agent — Read-Only Code Explorer

探索代理是只读的，专注于代码库分析与信息搜集。它无法修改任何文件，因此可以安全地并行运行多个探索代理。

json

{
  "prompt": "分析 src/auth 模块的架构，说明认证流程和关键组件",
  "subagent_type": "explore"
}

可用工具：Read、Grep、Glob（仅只读工具）

适用场景：

代码库结构分析
依赖关系梳理
接口和类型定义查找
代码模式识别

Plan 规划代理

Plan Agent — Architecture Planner

规划代理同样是只读的，但其 system prompt 经过优化，专注于架构级别的分析与方案设计。

json

{
  "prompt": "设计一个从 REST API 迁移到 GraphQL 的分步方案",
  "subagent_type": "plan"
}

可用工具：Read、Grep、Glob（仅只读工具）

适用场景：

架构设计与规划
迁移方案制定
技术选型分析
重构策略规划

类型对比表

Type Comparison

特性	general-purpose	explore	plan
文件读取	支持	支持	支持
文件写入	支持	不支持	不支持
命令执行	支持	不支持	不支持
并行安全	需隔离	安全	安全
上下文优化	通用	搜索优化	规划优化
典型用时	较长	快速	中等

启动参数详解

Launch Parameters in Detail

prompt 任务提示

Task Prompt

prompt 是传递给 SubAgent 的核心指令。编写高质量的 prompt 对 SubAgent 的执行效果至关重要。

好的 prompt 示例：

在 src/api/routes/ 目录下查找所有没有错误处理中间件的路由处理函数。
列出每个文件的路径、函数名以及当前的错误处理方式（如果有的话）。
重点关注 async 函数中缺少 try-catch 的情况。

不好的 prompt 示例：

检查代码中的错误处理

run_in_background 后台执行

Background Execution

设置 run_in_background: true 时，SubAgent 将在后台运行，主 Agent 可以继续执行其他任务。

json

{
  "prompt": "运行完整的端到端测试套件并报告结果",
  "subagent_type": "general-purpose",
  "run_in_background": true
}

主 Agent 稍后可通过 TaskOutput 获取结果。

isolation 隔离模式

Isolation Mode

isolation: "worktree" 启用 Git 工作树隔离，SubAgent 在独立的工作目录中操作，避免文件冲突。

json

{
  "prompt": "重构 database 层的连接池管理",
  "subagent_type": "general-purpose",
  "isolation": "worktree"
}

隔离模式：Worktree

Isolation Mode: Git Worktree

Worktree 隔离是 Claude Code 多代理架构中保证安全并行写入的关键机制。

工作原理

How It Works

主仓库 (main repo)
├── .git/
├── src/
└── ...

Worktree #1 (SubAgent A)          Worktree #2 (SubAgent B)
├── src/ (独立副本)                ├── src/ (独立副本)
└── ...                           └── ...

每个使用 worktree 隔离的 SubAgent 会获得项目的一个独立 Git 工作树。修改互不干扰，完成后可合并回主分支。

使用场景

When to Use Worktree Isolation

场景	是否需要 Worktree
多个 SubAgent 修改同一文件	必须使用
多个 SubAgent 修改不同文件	建议使用
只读探索	不需要
运行测试	视情况而定

注意事项

Caveats

Worktree 创建需要 Git 仓库支持
创建和销毁 worktree 有一定开销
合并冲突需要手动或由主 Agent 处理

前台 vs 后台执行

Foreground vs. Background Execution

前台执行（默认）

Foreground Execution (Default)

主 Agent 等待 SubAgent 完成后再继续。适合结果需要立即使用的场景。

json

{
  "prompt": "查找项目中 API 密钥的使用方式",
  "subagent_type": "explore",
  "run_in_background": false
}
// 主 Agent 在此等待，直到 SubAgent 返回结果
// 然后基于结果继续下一步操作

后台执行

Background Execution

主 Agent 启动 SubAgent 后立即继续其他工作。适合耗时较长、结果不急需的场景。

json

// 第一步：启动后台任务
{
  "prompt": "运行所有单元测试",
  "subagent_type": "general-purpose",
  "run_in_background": true
}

// 第二步：主 Agent 继续做其他事情
// ...

// 第三步：需要结果时获取
{
  "tool": "TaskOutput",
  "parameters": { "task_id": "<subagent-task-id>" }
}

执行模式选择指南

Choosing the Right Execution Mode

因素	前台	后台
结果依赖性	下一步依赖此结果	结果可稍后使用
预计耗时	短（< 30秒）	长（> 30秒）
并行需求	无	需要同时做其他事
典型场景	代码查询、快速分析	测试运行、大规模重构

上下文隔离与共享

Context Isolation vs. Sharing

上下文隔离

Context Isolation

每个 SubAgent 拥有独立的上下文窗口，不会消耗主 Agent 的上下文空间。这是 SubAgent 的核心优势之一。

主 Agent 上下文窗口：
┌─────────────────────────────────┐
│ 用户对话历史                      │
│ 主任务指令                        │
│ SubAgent 返回的摘要结果            │  ← 只占少量空间
└─────────────────────────────────┘

SubAgent 上下文窗口（独立）：
┌─────────────────────────────────┐
│ 任务 prompt                      │
│ 工具调用和结果                    │
│ 详细的分析过程                    │  ← 不影响主 Agent
└─────────────────────────────────┘

信息共享方式

How Information Is Shared

SubAgent 通过返回值将结果传回主 Agent。主 Agent 获得的是 SubAgent 执行结果的摘要，而非完整的执行过程。

SubAgent 之间的通信

Inter-SubAgent Communication

SubAgent 之间不能直接通信。所有协调都通过主 Agent 进行。

SubAgent A ──结果──→ 主 Agent ──指令──→ SubAgent B
                        ↑
                        │
                     协调中心

协调模式

Coordination Patterns

模式一：扇出-汇聚（Fan-out/Fan-in）

python

# 伪代码：主 Agent 的执行逻辑
results = parallel([
    Agent(prompt="分析 frontend 模块", type="explore"),
    Agent(prompt="分析 backend 模块", type="explore"),
    Agent(prompt="分析 database 模块", type="explore"),
])
summary = synthesize(results)

模式二：流水线（Pipeline）

python

# 伪代码：主 Agent 的执行逻辑
analysis = Agent(prompt="分析当前代码架构", type="plan")
plan = Agent(prompt=f"基于分析结果制定重构方案：{analysis}", type="plan")
Agent(prompt=f"按照方案执行重构：{plan}", type="general-purpose")

使用示例

Practical Examples

示例一：并行代码搜索

Example 1: Parallel Code Search

场景：需要在多个目录中搜索特定模式。

主 Agent 收到请求：查找项目中所有硬编码的数据库连接字符串

主 Agent 启动三个 explore SubAgent：

SubAgent 1: "在 src/ 目录搜索包含 mongodb://, postgresql://, mysql:// 的文件"
SubAgent 2: "在 config/ 目录搜索数据库相关的配置项"
SubAgent 3: "在 test/ 目录搜索测试中使用的数据库连接"

三个 SubAgent 并行执行，各自返回结果
主 Agent 汇总所有发现并报告给用户

示例二：并行测试执行

Example 2: Parallel Test Execution

场景：同时运行多个测试套件。

json

// SubAgent 1
{
  "prompt": "运行 src/api 的单元测试并报告失败的用例",
  "subagent_type": "general-purpose",
  "run_in_background": true
}

// SubAgent 2
{
  "prompt": "运行 src/services 的集成测试并报告失败的用例",
  "subagent_type": "general-purpose",
  "run_in_background": true,
  "isolation": "worktree"
}

示例三：探索 + 修复工作流

Example 3: Explore + Fix Workflow

步骤 1：启动 explore SubAgent
  → "分析 src/auth/login.ts 中的安全漏洞"
  → 返回：发现 3 个问题（SQL 注入、XSS、CSRF）

步骤 2：基于分析结果，启动 general-purpose SubAgent
  → "修复 src/auth/login.ts 中的以下安全问题：
      1. 第 45 行的 SQL 注入风险
      2. 第 78 行的 XSS 漏洞
      3. 缺少 CSRF token 验证"
  → 执行修复并返回修改摘要

/agents 命令

The /agents Command

在 Claude Code 交互界面中，可以使用 /agents 命令查看当前会话中所有活跃的 SubAgent。

> /agents

活跃代理列表：
┌────┬──────────┬────────────┬──────────┬──────────┐
│ ID │ 类型      │ 状态       │ 模式     │ 运行时间  │
├────┼──────────┼────────────┼──────────┼──────────┤
│ 1  │ explore  │ 运行中     │ 前台     │ 12s      │
│ 2  │ general  │ 运行中     │ 后台     │ 45s      │
│ 3  │ plan     │ 已完成     │ 前台     │ 8s       │
└────┴──────────┴────────────┴──────────┴──────────┘

最佳实践

Best Practices

何时使用 SubAgent

When to Use SubAgent

适合使用 SubAgent 的场景：

任务可并行化：多个独立的搜索、分析或修改任务
上下文空间不足：主 Agent 上下文快满时，用 SubAgent 分担
长时间运行的任务：测试执行、大规模重构
需要专业化处理：探索用 explore，规划用 plan

不适合使用 SubAgent 的场景：

简单的单步操作：直接用工具更快
强依赖上下文的操作：SubAgent 无法访问主 Agent 的完整对话历史
需要频繁交互的任务：SubAgent 不能与用户直接对话

编写有效的 SubAgent Prompt

Writing Effective SubAgent Prompts

推荐做法：
- 明确任务目标和预期输出格式
- 提供必要的上下文信息（文件路径、模块名称等）
- 指定结果的详细程度

避免做法：
- 过于模糊的指令
- 假设 SubAgent 知道对话历史
- 在一个 prompt 中包含过多不相关的任务

SubAgent 数量控制

Controlling SubAgent Count

并发数量	推荐场景	注意事项
1-2	一般任务	资源消耗低
3-5	中型项目分析	注意文件锁冲突
5+	大型代码库扫描	建议全部使用只读类型

错误处理

Error Handling

SubAgent 执行失败时，主 Agent 会收到错误信息。建议的处理策略：

重试：使用更明确的 prompt 重新启动 SubAgent
降级：SubAgent 失败后，主 Agent 自行完成任务
拆分：将失败的任务拆分为更小的子任务

SubAgent 返回错误 → 主 Agent 分析原因
                   ├→ 权限问题 → 调整工具集或隔离模式
                   ├→ 超时 → 拆分为更小的任务
                   └→ 逻辑错误 → 优化 prompt 后重试

总结

Summary

SubAgent 是 Claude Code 实现复杂任务自动化的核心机制。通过合理选择 SubAgent 类型、执行模式和隔离策略，可以显著提升大型项目中的开发效率。关键要点：

选择正确的 SubAgent 类型匹配任务需求
只读任务优先使用 explore 或 plan 类型
并行写入时务必启用 worktree 隔离
编写清晰、具体的 prompt 指令
善用后台执行提升整体效率

SubAgent 子代理 ​

核心概念 ​

为什么需要 SubAgent？ ​

SubAgent 与普通工具调用的区别 ​

Agent 工具调用方式 ​

完整参数示例 ​

参数说明表 ​

SubAgent 类型 ​

general-purpose 通用代理 ​

Explore 探索代理 ​

Plan 规划代理 ​

类型对比表 ​

启动参数详解 ​

prompt 任务提示 ​

run_in_background 后台执行 ​

isolation 隔离模式 ​

隔离模式：Worktree ​

工作原理 ​

使用场景 ​

注意事项 ​

前台 vs 后台执行 ​

前台执行（默认） ​

后台执行 ​

执行模式选择指南 ​

上下文隔离与共享 ​

上下文隔离 ​

信息共享方式 ​

SubAgent 之间的通信 ​

协调模式 ​

使用示例 ​

示例一：并行代码搜索 ​

示例二：并行测试执行 ​

示例三：探索 + 修复工作流 ​

/agents 命令 ​

最佳实践 ​

何时使用 SubAgent ​

编写有效的 SubAgent Prompt ​

SubAgent 数量控制 ​

错误处理 ​

总结 ​

SubAgent 子代理

核心概念

为什么需要 SubAgent？

SubAgent 与普通工具调用的区别

Agent 工具调用方式

完整参数示例

参数说明表

SubAgent 类型

general-purpose 通用代理

Explore 探索代理

Plan 规划代理

类型对比表

启动参数详解

prompt 任务提示

run_in_background 后台执行

isolation 隔离模式

隔离模式：Worktree

工作原理

使用场景

注意事项

前台 vs 后台执行

前台执行（默认）

后台执行

执行模式选择指南

上下文隔离与共享

上下文隔离

信息共享方式

SubAgent 之间的通信

协调模式

使用示例

示例一：并行代码搜索

示例二：并行测试执行

示例三：探索 + 修复工作流

/agents 命令

最佳实践

何时使用 SubAgent

编写有效的 SubAgent Prompt

SubAgent 数量控制

错误处理

总结