16 May 2026

claude code subagent学习

什么是 subagent？

subagent是主 agent 可以调用的独立 ai 实例。与 skill 不同，subagent 拥有独立的对话上下文、独立的工具访问权限，甚至可以运行在不同的隔离环境中。subagent 就像是主 agent 的”助手”或”专家顾问”，可以独立处理复杂任务并返回结果。

何时使用 subagent

适用场景

1. 隔离上下文需求
   • 需要独立对话历史
   • 不想污染主对话的上下文
   • 并行处理多个独立任务
2. 工具隔离
   • 需要不同的工具权限
   • 需要在隔离环境中执行操作
3. 复杂任务分解
   • 主任务可以分解为多个独立的子任务
   • 需要不同专业领域的专家协作
4. 上下文窗口管理
   • 主对话上下文接近窗口上限
   • 需要保存子任务的完整历史

不适用场景

• 简单、快速的任务（直接用工具或 skill 更高效）
• 需要与主对话紧密协作的任务
• 对执行速度要求极高的场景

如何创建好的 subagent

1. 清晰的任务描述

subagent 需要一个明确且独立的任务描述。这个描述应该包含：

# 伪代码示例
agent_description = """
分析这个代码库中的性能瓶颈。具体任务：
1. 扫描所有 python 文件
2. 识别常见的性能反模式
3. 提供优化建议
4. 生成报告
"""

关键原则：

• 任务边界清晰
• 输入输出明确
• 避免需要与主 agent 频繁通信

2. 合适的 agent 类型选择

根据任务性质选择正确的 agent 类型：

# 探索代码库结构
Agent(
    subagent_type="Explore",
    prompt="找出所有 API 端点",
    description="探索 API 端点"
)

# 架构设计
Agent(
    subagent_type="Plan",
    prompt="设计一个新的认证系统",
    description="设计认证系统架构"
)

3. 预期结果处理

subagent 完成后，主 agent 需要正确处理结果：

# 获取结果并整合
result = Agent(
    prompt="分析 X 模块的依赖关系"
)
# 将结果简洁地报告给用户
# 不要直接堆砌子 agent 的完整输出

4. 并行执行

对于独立的任务，可以并行启动多个 subagent：

# 并行探索多个区域
Agent(
    prompt="分析前端代码",
    description="分析前端",
    run_in_background=True
)
Agent(
    prompt="分析后端代码",
    description="分析后端",
    run_in_background=True
)

subagent 的最佳实践

1. 避免过度使用

subagent 的调用有开销（启动时间、上下文传递）。只有当其带来的价值超过这个开销时才使用。

2. 保持任务独立性

subagent 应该能够独立完成任务，不应该频繁需要与主 agent 交互。

3. 提供足够的上下文

虽然 subagent 有独立上下文，但启动时应该提供足够的初始信息，避免它需要反复询问。

4. 使用适当的超时

为长时间运行的 subagent 设置合理的超时时间。

skill vs subagent 核心对比

架构层面的区别

LEo at 00:00