⚠️ 源单薄性声明 本条目素材以 Anthropic 官方 doc 为主（
sub-agents.md+agent-sdk/subagents.md共 736 行）+ Boris 散点提及。没有独立第三方使用报告、没有社群失败案例。 已讲清楚：subagent 是什么、怎么定义、什么时候用 还没听到：真实项目里 subagent 把事情变复杂/变简单的对比案例 本条目视为”官方视角的 subagent 说明书”，社群用起来后再补”实战避坑”段。
一句话
Subagent = 独立 context window 的 Claude 实例，主 session 派给它一个任务，它自己干完把摘要交回来。
不是”多个 Claude 在聊天”，也不是新模型——就是一个”能被主 session 调用的带独立 context 的 worker”。
为什么会有这东西
来源：agent-sdk/subagents.md 和 context-window 相关 doc。
核心动因是 context 预算管理（参见 Context Window 与上下文管理）。场景：
你让 Claude “去把整个 repo 里所有用到
useState的地方找出来并分析”。它 grep + 读 20 个文件 = 往主 session 塞进去几万 token 的代码，后面你继续问别的它已经开始忘前面的事了。
Subagent 的解法：让一个 subagent 去干这个 grep + 读文件的脏活，它自己烧自己的 context，最后只把”分析结论摘要”回传主 session。主 session 一直保持干净。
Boris 在 pragmatic 访谈里把这个讲得更狠（Context Window 与上下文管理 条目里已引）：subagent 首先是 context 隔离器，其次才是功能划分。
怎么定义一个 subagent
来源：sub-agents.md 的 frontmatter 字段表。
Subagent 就是一个 md 文件，放在 .claude/agents/（项目级）或 ~/.claude/agents/（用户级）：
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling
Provide specific line references and suggested fixes.支持的 frontmatter 字段（sub-agents.md）
| 字段 | 作用 |
|---|---|
name | 必填。subagent 标识 |
description | 必填。Claude 靠这个字段决定何时调用这个 subagent。写清楚”什么情况下用” |
tools | 可给 subagent 的工具列表（默认全部）。锁死工具 = 限制 subagent 的破坏半径 |
model | sonnet/opus/haiku/全名。可以为批量 subagent 选便宜模型省钱 |
skills | 预加载 skill 列表——subagent 不继承主 session 的 skill |
permissionMode | 为这个 subagent 单独覆盖权限模式 |
isolation | worktree → 在独立 git worktree 里跑（不污染主仓库） |
autoMemory | true → 开持久记忆，存 ~/.claude/agents/memory/<name>/ |
三条核心好处（官方列，有用）
agent-sdk/subagents.md 明确列的 4 个 benefit，合并成 3 条：
1. Context 隔离（最核心）
research-assistant 可以读 20 个文件——这 20 个文件的全部 token 不进入主 session。主 session 只收到它的最终总结。
2. 并发
多个 subagent 可以同时跑：style-checker + security-scanner + test-coverage 三个 subagent 并行评审，从几分钟变几秒。
3. 工具限制（安全边界）
doc-reviewer 只给 Read 和 Grep——它能分析但物理上不可能修改文档。比”告诉 Claude 别改”靠谱。
什么时候该用 subagent
官方 doc 的建议合起来就一句话：
主任务会被一堆不相关的中间产物塞满 context 时——把这堆中间产物塞进 subagent。
具体场景：
- 读大量文件的分析任务（code review, 找用法, 统计）
- 重复性任务（10 个文件各自检查一遍）
- 需要不同模型/工具权限的任务（主 session Opus 做设计，subagent Haiku 批量处理）
- 保护主 session context 预算
什么时候不该用
官方没明说但能从 agent-teams 对比推断：
- 顺序依赖的任务——subagent 并发没意义
- 需要几个 worker 互相讨论的任务——subagent 不能相互通信（那是 Agent Teams 是啥 的事）
- 简单任务——spawn subagent 本身有开销，小事不值得
内建的三个 subagent
sub-agents.md 列：
| 名字 | 用途 |
|---|---|
general-purpose | 默认——大多数委托场景 |
Explore | 只读——代码库探索 |
Plan | 规划分析，不改文件 |
不用自己定义，直接可用。
Subagent vs. Agent Teams（重要）
agent-teams.md 明确区分：
| Subagent | Agent Team | |
|---|---|---|
| context | 独立，只回摘要给主 | 独立，成员间可通信 |
| communication | 只向主 session 报告 | teammate 互相发消息 |
| coordination | 主 session 管 | 共享任务列表，自协调 |
| 最合适 | 结果即可的聚焦任务 | 需要讨论和协作的复杂任务 |
| token 成本 | 低（结果被摘要回主 context） | 高（每个 teammate 是独立 Claude 实例） |
见 Agent Teams 是啥。大多数时候你要的是 subagent，不是 agent team。
陈彬视角
社群里目前还没人真的深度用 subagent（2026-04 这个时点）。这条目先以”看懂官方意思”为目标。
一个实操提醒：subagent 不是越多越好。起手只在两个场景试：
- 分析任务（我要读一堆东西然后得结论）
- 评审任务（我要并行跑几个专业视角）
业务逻辑类任务先不要 subagent 化——主 session 自己管得更清楚，也更容易调试。
关联
- 前置：什么是 MD-based System · Agent vs Skill vs Workflow
- 紧邻：Context Window 与上下文管理（subagent 的存在理由）
- 对比：Agent Teams 是啥（多 agent 讨论时用 team，不用 subagent）
needs_sources（明确待补）
- 社群好朋友的真实 subagent 使用案例（目前只有 Boris 和 Anthropic 自己）
- subagent 把事情搞复杂的反面案例
- 非 Anthropic 视角的批评/建议