Claude Code多Agent协作指南：Subagent与Agent Team实战详解 ​

从"单兵作战"到"团队协作"的质变：一个人只能串行一件一件做，多开几个Agent就能并行同时搞。Subagent隔离探索过程，Agent Team并行协作通信，选对方式效率翻倍。

你有没有遇到过这种时刻：

让Claude探索代码库找一个bug，它吭哧吭哧分析了半天，读了几十个文件，主对话里全是它的分析过程。等它终于找到问题，你想继续聊，却发现上下文里全是刚才的探索痕迹，重要的信息被挤到后面去了。

或者你要做代码审查，想让Claude同时检查安全、性能和测试覆盖。但它只能一件一件来，安全审完审性能，性能审完审测试，本来三分钟能搞完的事，硬生生拖成半小时。

这时候你需要的是多开几个Claude，各自独立干活。

两种协作方式对比 ​

• Subagent适合：主Agent委派任务，隔离复杂探索，保持主对话清爽
• Agent Team适合：teammates并行协作，互相讨论，节省时间

⚠️ 注意：Agent Team目前是Beta实验性功能，默认关闭，需要手动开启。

Subagent：独立上下文，不污染主对话 ​

为什么要用 ​

不用Subagent的时候：

你：分析一下这个bug
Claude：开始分析...
[读取文件A]
[读取文件B]
[分析数据流]
[推理可能原因]
[输出3000字分析过程]
你：找到问题了，现在修复吧
Claude：[回复很慢，因为上下文里全是刚才的分析]

主对话被探索过程塞满，后续操作都变慢。

用Subagent之后：

你：派debugger subagent分析这个bug
Subagent：[在独立上下文里分析]
Subagent返回：找到原因，是第X行空指针
你：修复它
Claude：[上下文干净，快速响应]

探索过程留在Subagent的独立上下文里，主对话保持干净。

怎么用 ​

Subagent可以放在两个位置：

• .claude/agents/：项目级，只在当前仓库生效
• ~/.claude/agents/：用户级，在所有项目里都能用

手动加完文件后，重启会话，或者用/agents立即加载。

下面是项目级写法，在.claude/agents/下创建markdown文件：

---
name: debugger
description: Bug分析专家
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是调试专家。

分析bug，找出根本原因，给出修复方案。

然后用自然语言调用：

派debugger subagent分析这个NPE

Claude会开一个独立上下文运行这个subagent，只把结果带回来。

内置的Subagent ​

记住：只要是需要大量探索的任务，就应该用Subagent，保持主对话干净。

Agent Team：多个独立上下文并行跑（Beta） ​

⚠️ 实验性功能：Agent Team目前处于Beta阶段，默认关闭，可能存在稳定性问题。

为什么要用 ​

不用Agent Team：

你：审查PR，检查安全
Claude：[检查安全，5分钟]
你：再检查性能
Claude：[检查性能，5分钟]
你：再检查测试覆盖
Claude：[检查测试覆盖，5分钟]
总共：15分钟

用Agent Team：

你：创建agent team，三个队友分别检查安全、性能、测试覆盖
三个teammate同时开始
总共：5分钟

三个独立上下文并行跑，teammates之间还能互相讨论，省时间。

但它不是没有代价。Agent Team的协调开销和token成本都明显高于单会话，顺序任务、同一文件反复编辑、依赖关系特别强的工作，通常还是单会话或Subagent更合适。

如何开启（必须） ​

Agent Team默认关闭，必须手动启用：

方式一：环境变量

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

方式二：settings.json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

检查是否开启：

claude --version  # 需要 v2.1.32 或更高版本

创建和使用 ​

然后用自然语言创建团队：

创建agent team，三个队友：
- 安全审查员
- 性能审查员
- 测试审查员

一起审查PR #142

Claude会：

1. 开三个独立上下文（三个Claude实例）
2. 给它们分配任务
3. 让它们并行工作

teammates之间可以直接通信 ​

这是Agent Team和Subagent的关键区别：

• Subagent：只能向主Agent汇报，多个Subagent之间无法通信
• Agent Team：消息可以在teammates之间直接流转，Team lead主要负责协调和汇总

示例：

安全审查员：发现SQL注入风险
性能审查员：我检查了这个查询，确实有N+1问题
测试审查员：这两个问题都需要测试覆盖

teammates自己就能协调，不需要你在中间传话。

两种显示模式 ​

Agent Team的默认显示模式是auto：

• 如果已经跑在tmux或支持的iTerm2环境里，会优先走分屏
• 其他情况会落到in-process

In-process：

• 所有teammate在你的终端里
• 按Shift+Down切换查看
• 任何终端都能用

Split-pane（需要tmux或iTerm2）：

• 每个teammate有自己的窗格
• 同时看到所有人的输出

iTerm2这条路还需要it2 CLI，并在设置里启用Python API。

如果想强制固定成某一种模式，在settings.json里覆盖：

{
  "teammateMode": "in-process"
}

控制团队 ​

分配任务：

让安全审查员检查认证模块
让性能审查员检查数据库查询

直接与teammate对话：

• In-process：按Shift+Down切过去
• Split-pane：点击窗格

查看任务列表： 按Ctrl+T

结束团队：

先让队友停下来：

Ask the researcher teammate to shut down

再让Team lead清理团队资源：

Clean up the team

清理要让Team lead来做，不要让某个teammate直接清。

什么时候用哪个 ​

先记两个判断标准：

• 只要结果，不需要互相讨论 → 优先用Subagent
• 需要多个角色并行推进，还要共享任务和互相沟通 → 再用Agent Team

一句话总结：

• 保持主对话干净 → 用Subagent
• 并行执行省时间 → 用Agent Team

实战：完整的并行工作流 ​

场景：做一个登录功能，需要前端、后端、测试同时开工

Step 1：并行设计（Agent Team） ​

创建agent team，三个队友：
- frontend：设计登录页面
- backend：设计API
- tester：设计测试用例

三个独立上下文并行跑，同时出方案。

Step 2：并行实现（Subagent） ​

派frontend-impl subagent实现前端
派backend-impl subagent实现后端

两个独立上下文同时写代码，互不干扰。

Step 3：并行验证（Agent Team） ​

创建agent team：
- security-reviewer：安全审查
- test-runner：运行测试

同时验证，省时间。

Step 4：整合 ​

这一步不能只靠一句"整合完成"带过去。更稳的做法是让Team lead按固定格式收口：

请汇总三个队友的结果，按这个格式输出：
1. 每个队友分别产出了什么
2. 哪些地方有冲突
3. 最终采用哪套方案，为什么
4. 接下来由谁继续实现

这样并行跑出来的东西，最后才会真正收成一个可以继续往下做的结果。

小结 ​

核心区别：

核心转变 ​

以前是你和Claude一对一。

现在是你是项目经理，Claude可以分身成一支团队。

• Subagent = 主Agent委派，独立上下文，只汇报结果
• Agent Team = 多个teammates并行，互相通信，一起协作

但也别硬上。顺序任务、同一文件来回改、依赖链特别长的工作，通常不值得拉一个Team。

动手试试 ​

创建一个简单的代码审查subagent。这里用的是用户级路径，建好后所有项目都能用：

mkdir -p ~/.claude/agents
cat > ~/.claude/agents/code-reviewer.md << 'EOF'
---
name: code-reviewer
description: 代码审查专家
tools: Read, Grep, Glob, Bash
---

你是代码审查员。

检查代码，输出：严重问题 / 警告 / 建议。
EOF

然后在Claude Code中：

派code-reviewer检查当前改动

你会发现：主对话保持干净，只有审查结论，没有满屏的分析过程。

这就是Subagent的价值：独立上下文，不污染主对话。