Claude Code 教程丨一个人干不过来时，怎么让 Claude 分身协作

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

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

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

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

前面我们已经把“怎么自动往下跑”这件事解决了，但当任务开始拆成多个维度，瓶颈就会从“要不要继续”变成“能不能同时推进”。

Claude Code 提供了两种方式：

• • Subagent：主 Agent 派出去的助手，独立上下文干活，只向主 Agent 汇报，多个 Subagent 之间无法通信
• • Agent Team：开多个独立上下文并行跑， teammates 之间可以直接互相通信（Beta 功能，需要手动开启）

这是从”单兵作战”到”团队协作”的质变。一个人只能 sequentially 一件一件做，多开几个就能 parallel 同时搞。

一句话说清楚

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. 1. 开三个独立上下文（三个 Claude 实例）
2. 2. 给它们分配任务
3. 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 的价值：独立上下文，不污染主对话。