13 · Subagent 与多 Agent 协作

📚 系列导航：上一篇 12 MCP 给 Claude 接上了外部工具。这一篇换个思路——不是给它加工具，而是把活儿外包出去：Subagent 和 Agent Teams。

01 Subagent 是什么

Subagent 是 Claude 临时雇来的一个专项助手——它在自己的上下文窗口里干活，干完只把结论交回主线，过程中翻的一堆资料不占你的桌面。

官方原话：每个 subagent 在自己的 context window 中运行，具有自定义系统提示、特定的工具访问权限和独立的权限。

维度	主对话（你）	子代理（外包小弟）
上下文	你和 Claude 一路聊下来的全部历史	一片空白，只收到一句「任务交代」，看不到你们之前聊了啥
系统提示（人设）	Claude Code 的默认设定	你给它写的专属人设
工具/权限	你授权过的所有工具	可以单独砍掉

NOTE

子代理最核心的价值：隔离上下文。跑测试会刷出几百上千行输出，但你真正要的就一句结果。让子代理在自己房间里扛，只把结论交回来，主对话台面始终干净。

02 什么时候该用 Subagent

对比项	直接在主对话干	硬拆给子代理
启动开销	没有，张嘴就干	子代理从白纸起步，得先花时间摸清状况
来回沟通	你一句它一句，随时改	交代不清就得返工，子代理看不到之前的对话
花费	一份 token	多开一个上下文 = 多烧 token

WARNING

反共识的坑：不是越多越该拆。 一句话能说清、改动就在眼前的活，绝不外包。拆得多≠专业，过度拆分只会又慢又贵又把台面堆回去。

该用子代理的场景：

跑测试/翻日志/查文档——产出大量中间垃圾，但你要的只是一句结论
专精某类任务——把「以资深审查员视角挑刺」固化成一个 code-reviewer，以后一句话唤起
几件互不相干的活并行——开三个子代理分别探索三个模块，最后汇总

03 建一个子代理

方式一：`/agents` 交互式（推荐）

text

/agents

弹出管理界面。切到 Library → Create new agent → Personal。选 Generate with Claude，用大白话描述你要什么样的助手。它会通过问答自动生成 name、description 和人设。

TIP

记得主动砍工具。审查员只该读不该写，就只勾 Read-only tools。不砍它就继承主对话的全部权限。

方式二：手写配置文件

子代理就是一个 Markdown 文件，YAML 头管配置，下面是人设：

markdown

---
name: code-reviewer
description: 只读的代码点评员，审查代码时主动使用。当用户说「帮我看看改动」时触发。
tools: Read, Grep, Glob
model: sonnet
---
你是一个资深代码审查员，只挑刺不改代码。按可读性、命名、潜在 bug 三类列出问题，按严重程度排序。

字段	必填	说明
`name`	是	唯一标识，小写字母加连字符
`description`	是	告诉 Claude 什么任务该派给它——这是自动委派的唯一依据，写得越精准越准
`tools`	否	省略 = 继承主对话全部工具；想限权就在这列允许清单
`model`	否	`sonnet`/`opus`/`haiku`/`inherit`（默认，跟主对话同款）
`permissionMode`	否	权限模式：`default`/`acceptEdits`/`auto`/`dontAsk`/`plan`

存放位置：

~/.claude/agents/ → 你的所有项目都能用（全局）
.claude/agents/ → 仅当前项目，进 git 团队共享

WARNING

手改文件后必须重启会话才生效。通过 /agents 界面建的不用重启。

04 触发 Subagent

自动委派： Claude 拿你的话去比对每个子代理的 description，觉得对得上就自动派活。

直接点名：

text

用 code-reviewer 子代理看看我最近的改动

text

@agent-code-reviewer 看看这次认证相关的改动

NOTE

自然语言是「Claude 通常委托」；@ 点名是「保证用它」，不把选择权留给 Claude。新建的子代理建议先用 @ 点名验证。

05 Agent Teams：多会话协作

Subagent 是在一个会话里外包专项助手。Agent Teams 是多个对等的、完整的 Claude Code 会话协作——队友之间能直接发消息，你也能绕过 leader 直接跟某个队友聊。

WARNING

实验性功能，需 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 开启。

维度	Subagent	Agent Teams
上下文	独立，结果回传	完全独立
谁协调	主代理统管	leader 协调+共享任务列表自我协调
队友之间	不通信	直接互发消息
你能否直接管	不能	能直接跟任意队友对话
成本	较低	较高，每个队友都是独立实例
最适合	只要结果不用讨论的专注任务	需要讨论、互相质疑的复杂协作

判断标准：这帮工人之间需不需要互相通气？ 不需要用 subagent（便宜），需要才上团队。

团队四个关键件

组件	角色
Team lead（负责人）	创建团队、生成队友、协调分活——定了就换不了
Teammates（队友）	各自领任务干活的独立 Claude Code 实例
Task list（任务列表）	共享工作清单：待处理/进行中/已完成，任务可设依赖
Mailbox（信箱）	代理之间互发消息的系统

用 `claude agents` 总控屏

bash

claude agents

把所有后台会话摊在一个屏幕上——一行一个会话，看颜色知状态：

状态	显示	含义
工作中	动画闪动	正在跑工具或生成回复
需要输入	黄色	需要你回答或批权限
已完成	绿色	干完了
失败	红色	报错了

操作：Space 窥视，Enter 钻进去，← 退出来。

指挥团队

text

帮我建一个 agent team 从不同角度探索这个问题：
一个负责 UX、一个负责技术架构、一个专门唱反调。

切队友：Shift+Down 在队友之间循环
要计划：生成一个架构师队友，在他改动任何东西之前必须先经过计划批准
指定模型：每个队友都用 Sonnet
清理：清理这个团队——永远走 leader，别让队友去清

06 什么时候该上团队

场景	拆不拆
前端/后端/测试三层并行改，互不依赖	✅ 拆
一个 bug 根因不明，用几个假设并行排查	✅ 拆
多人并行审 PR（安全/性能/测试各一人）	✅ 拆
一连串有先后依赖的步骤	❌ 别拆，串行活单会话更顺
几个队友要改同一个文件	❌ 别拆，互相覆盖
随手一个小任务	❌ 别拆

TIP

新手从「研究/审查」这类不写代码的活开始，团队规模 3-5 个起步。

07 动手：建一个最小子代理

bash

mkdir sub-demo && cd sub-demo && mkdir -p .claude/agents

.claude/agents/code-reviewer.md：

markdown

---
name: code-reviewer
description: 只读的代码点评员，审查代码时主动使用。
tools: Read, Grep, Glob
---
你是一个资深代码审查员，只挑刺不改代码。按可读性、命名、潜在 bug 三类列出问题。

bash

echo 'def f(a, b): return a / b' > calc.py
claude

text

@agent-code-reviewer 点评一下 calc.py

预期：子代理在独立上下文里读文件，返回点评结论（函数名不达意、缺除零处理），且不动你的文件。

08 小结

工具	适用场景	成本
Subagent	隔离上下文脏活、专精任务、简单并行	较低
Agent Teams	需要互相讨论的复杂协作	较高
直接对话	一句话能说清的简单改动	最低

NOTE

下一篇：14 自定义 Skill：把反复粘贴的步骤打包成可复用的工作流。

13 · Subagent 与多 Agent 协作 ​

01 Subagent 是什么 ​

02 什么时候该用 Subagent ​

03 建一个子代理 ​

方式一：/agents 交互式（推荐） ​

方式二：手写配置文件 ​

04 触发 Subagent ​

05 Agent Teams：多会话协作 ​

团队四个关键件 ​

用 claude agents 总控屏 ​

指挥团队 ​

06 什么时候该上团队 ​

07 动手：建一个最小子代理 ​

08 小结 ​

13 · Subagent 与多 Agent 协作

01 Subagent 是什么

02 什么时候该用 Subagent

03 建一个子代理

方式一：`/agents` 交互式（推荐）

方式二：手写配置文件

04 触发 Subagent

05 Agent Teams：多会话协作

团队四个关键件

用 `claude agents` 总控屏

指挥团队

06 什么时候该上团队

07 动手：建一个最小子代理

08 小结