Claude Code 三种 Agent 模式深度对比：普通 Subagent / Worktree Agent / Agent Team

用 Claude Code 写代码，你迟早会遇到一个问题：一个 agent 不够用了。

代码分析要跑，测试要跑，前后端要同时改 —— 你需要并行。Claude Code 提供了三种 Agent 并行模式，但文档里散落各处，很难一次看明白。

这篇文章把三种模式放在一起讲清楚：它们到底区别在哪，什么时候该用哪个。

---

先建立一个心智模型

想象你在一间办公室（主会话）里工作。你需要帮手。

• 普通 Subagent = 你叫了个同事过来，坐在你旁边，用你的电脑、你的文件。你们共享同一张桌子。
• Worktree Subagent = 你给同事配了一台独立电脑，复制了一份项目代码。他改他的，你改你的，互不干扰。
• Agent Team = 你组了一个项目组，每个人有自己的办公室，通过内部邮件系统沟通。

这三种模式的核心区别就是 文件隔离程度 和 通信方式。

---

模式一：普通 Subagent（默认）

工作方式

主会话通过 Agent 工具启动一个子任务。子 agent 与主会话 共享同一个工作目录，可以直接读写主仓库的所有文件。

主会话 (cwd: /my-project)
  └── Subagent A (cwd: /my-project)  ← 共享同一目录
  └── Subagent B (cwd: /my-project)  ← 共享同一目录

特点

• 无文件隔离：所有 agent 操作同一份文件
• 无 Git 隔离：改动直接落在当前分支的工作区
• 独立 context window：subagent 不继承主会话的对话历史，有自己的上下文空间
• 结果回传：subagent 完成后，结果摘要注入主会话的 context

风险

多个 subagent 并发修改同一文件时，后者会覆盖前者。这不是 merge conflict —— 是直接覆盖，没有任何警告。

适用场景

• 只读任务：代码分析、文件搜索、文档查询
• 串行的写任务：先让 agent A 改完，再让 agent B 接着改
• 修改不同文件的并行任务（前提是你能确保文件不重叠）

---

模式二：Worktree Subagent（isolation: "worktree"）

工作方式

启动时，Claude Code 自动调用 git worktree add，在 .claude/worktrees/<name>/ 下创建一个 独立的仓库副本，并切换到一个新分支。

主会话 (cwd: /my-project, branch: main)
  └── Worktree Agent A (cwd: /my-project/.claude/worktrees/frontend/, branch: worktree-frontend)
  └── Worktree Agent B (cwd: /my-project/.claude/worktrees/backend/, branch: worktree-backend)

特点

• 完全的文件隔离：每个 agent 有自己的文件副本，互不影响
• 独立的 Git 分支：改动提交在各自的分支上，不影响主分支
• 自动清理：如果 agent 没产生任何改动，worktree 自动删除；有改动则保留，返回路径和分支名供后续合并
• 并发安全：多个 worktree agent 可以同时修改同一个文件的不同版本，不会冲突

使用方式

在 Agent 工具调用时加上 isolation: "worktree" 参数：

{
  "description": "重构前端组件",
  "prompt": "重构 UserProfile 组件...",
  "subagent_type": "general-purpose",
  "isolation": "worktree"
}

适用场景

• 并行修改多个模块：前端、后端、测试各用一个 worktree agent 同时推进
• 探索性实现：尝试两种不同方案，最后合并最好的那个
• 安全的大重构：在隔离环境里大改，确认没问题再合并回来

---

模式三：Agent Team（实验性）

工作方式

每个 teammate 是一个 完全独立的 Claude Code 实例（独立进程），通过 mailbox 消息系统和共享 task list 进行协调。

Team Lead（主会话）
  ├── Teammate: Security Reviewer  ← 独立 Claude Code 实例
  ├── Teammate: Performance Analyst ← 独立 Claude Code 实例
  └── Teammate: Test Writer         ← 独立 Claude Code 实例
       ↕ mailbox 互相通信
       ↕ 共享 task list

特点

• 完全独立的 context：teammate 的对话历史不回传主会话，对主会话 context 零占用
• 横向通信：teammate 之间可以 直接互发消息，不需要通过主 agent 中转
• 自主协调：通过共享 task list 认领任务，不完全依赖主 agent 分配
• 无自动文件隔离：默认共享工作目录，需手动约定各 teammate 负责不同文件

启用方式

需要在 settings.json 中手动开启实验性功能：

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

适用场景

• 多角色并行 review：安全、性能、测试覆盖率各一个 teammate 同时审查 PR
• 竞争性假设验证：多个 teammate 各持不同 debug 假设，互相挑战
• 长时间运行的复杂任务：需要多个 AI 持续协作，而不是一次性返回结果

---

全维度对比

隔离与安全

上下文（Context Window）

这是很多人忽略的关键差异：

为什么这很重要？

主会话的 context window 是有限资源。当你让 subagent 去扫描 20 个文件、跑 10 次搜索时，所有这些中间过程都在 subagent 自己的 context 里消化，只有最终的精简摘要才回到主会话。这是 subagent 的一个 隐藏价值 —— 它像一个过滤器，保护主会话的 context 不被中间噪音污染。

而 Agent Team 更进一步：teammate 的结果 完全不回传，只通过 mailbox 按需通信，对主会话 context 零压力。

通信与协调

执行速度

三种模式的 LLM 推理速度完全相同。 它们调用的是同一个模型。

真正影响总体执行时间的不是模式本身，而是：

1. 模型选择：这是最大的速度杠杆。model: "haiku" 推理速度比 opus 快 5-10 倍，适合简单搜索/分析任务。
2. 并行度：在一条消息里同时发多个 Agent tool call，它们真正并发执行。
3. max_turns 控制：限制 agent 的最大轮数，防止无意义的反复尝试。
4. run_in_background: true：让 agent 在后台运行，主会话继续处理其他事情。
5. 冲突导致的返工：Worktree agent 在并发写场景下 总体可能更快，不是因为单次推理快，而是因为避免了文件冲突导致的重做。

---

选择决策树

你需要并行执行多个任务吗？
├── 不需要 → 普通 Subagent
└── 需要
    ├── 任务之间会修改同一个文件吗？
    │   ├── 不会 → 普通 Subagent（并行启动多个）
    │   └── 会 → Worktree Subagent
    └── 任务之间需要互相讨论/挑战吗？
        ├── 不需要 → Worktree Subagent
        └── 需要 → Agent Team（实验性）

简单记忆：

• 读多写少 → 普通 Subagent
• 并发写代码 → Worktree Subagent
• 多角色协作 → Agent Team

---

实战建议

1. 用 model 参数做"分层调度"

不是所有任务都需要最强的模型。搜索和分析用 haiku（快且便宜），代码编写用 sonnet（平衡），复杂架构决策用 opus（最强推理）。

2. 善用 run_in_background

当 agent 任务不阻塞你的下一步时，让它后台跑。主会话可以继续做别的事，完成后会自动通知。

3. Worktree Agent 的合并策略

Worktree agent 完成后会返回分支名。你可以：

• git merge 合并回主分支
• git cherry-pick 挑选部分改动
• 直接丢弃（不满意的探索性尝试）

4. 保护主会话 Context

把"脏活"（大量文件扫描、日志分析、依赖树遍历）交给 subagent 做。它们在自己的 context 里消化噪音，只把结论给你。这能显著延长主会话的有效寿命。

---

总结

核心思路：根据任务的冲突风险和协作需求选模式，根据任务的复杂度选模型。 模式决定隔离程度，模型决定执行速度。两者正交，组合使用效果最好。