Claude Code 多 Agent 协作：Subagents 和 Agent Teams 怎么选

Wed, 22 Apr 2026 21:35:52 +0800

Claude Code 里和多 Agent 协作相关的能力，最容易混淆的就是 Subagents 和 Agent Teams。它们看起来都像“多开几个 Agent 一起做事”，但定位并不一样。简单说，前者更适合把独立任务分出去做，后者更适合让多个 Agent 围绕同一件事持续协作、互相验证。

如果你之前用过 Skill，也可以先这样理解：

Skill 负责定义流程和规则
Subagent 或 Agent teammate 负责实际执行任务

所以问题不在于“哪个更高级”，而在于你要解决的是哪一类协作。

Subagents：把支线任务分出去

Subagents 更像是在当前会话里临时派出去的分身。每个分身都有自己的上下文窗口，做完之后只把结果摘要带回来，主对话不会被大量中间输出塞满。

这类能力的优势很直接：

主线对话更干净，不容易被测试日志、搜索结果或长输出污染
可以把相互独立的研究或执行任务并行化
适合“给我结果就行”的任务，不需要持续讨论

原文提到，Claude Code 内置了三类 Subagent：

Explore：只读、适合快速搜索代码库
Plan：只读、适合在 plan mode 下后台收集信息
General-purpose：可读可写，适合同时探索和修改的任务

自定义 Subagent

如果内置能力不够，可以自己定义一个 Subagent。方式也不复杂，本质上就是写一个 Markdown 文件：

.claude/agents/：只对当前项目生效
~/.claude/agents/：对所有项目生效

文件格式类似这样：

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:

1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:

- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:

- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

这里最关键的是 description。Claude 会根据这段描述判断什么时候应该调用这个 Subagent，所以写得越清楚，触发越准。

另外几个常见配置项也很实用：

tools：限制它能用哪些工具
model：决定使用 sonnet、opus、haiku 或 inherit
permissionMode：控制编辑权限和权限提示行为
memory：给 Subagent 配跨对话记忆目录

如果只是临时用一次，也可以直接通过 CLI 注入：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Subagents 适合什么场景

最适合 Subagents 的，通常是这些任务：

跑测试并返回失败摘要，而不是把几千行日志全塞回主会话
并行调查几个互不依赖的模块
把“检查问题”和“修问题”拆成两步流水线

例如：

`1`	`Research the authentication, database, and API modules in parallel using separate subagents`

`1`	`Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them`

但如果任务需要频繁来回修正、多个阶段共享大量上下文，或者改动高度集中在少数几个文件里，那么直接在主对话里做，往往比派 Subagent 更省事。

Agent Teams：多个独立会话一起协作

Agent Teams 是另一个层级的能力。它不是在一个会话里派出分身，而是启动多个彼此独立的 Claude Code 实例，让它们围绕共享任务列表协作，还可以互相发消息。

这意味着它更像一个真正的小团队，而不只是“分出去做个支线”。

原文提到，这项能力目前还是实验功能，需要先开启：

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

把它加到 settings.json 后，就可以让 Claude 按你的要求组织一个 team。比如：

1
2
3

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

Agent Teams 的组成

一个 Agent Team 主要由三部分组成：

Team lead：你当前正在使用的主会话，负责组队、分派和汇总
Teammates：多个独立的 Claude Code 实例
Task list 和 Mailbox：共享任务列表与消息通道

和 Subagents 最大的不同在于，teammates 之间可以直接沟通，不需要每次都经过 lead 中转。任务状态通常会在 pending、in progress、completed 之间流转，成员完成一个任务后，还可以继续认领下一个任务。

Agent Teams 适合什么场景

当任务需要多角度讨论、互相挑战结论、或者拆成多个模块并行推进时，Agent Teams 会更合适。

原文给了几个很典型的场景：

多人并行审查同一个 PR，但每个人关注不同维度
围绕同一个 bug 提出不同假设，并互相反驳
前端、后端、测试分别推进不同模块

比如并行代码审查：

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

再比如竞争假说式调试：

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

这类任务的共性是：不是只要一个结果，而是需要不同 Agent 之间不断交换判断、修正方向，最后再形成比较可靠的结论。

两者怎么选

如果要快速区分，可以直接记这条：

做完给结果，用 Subagents
需要讨论和相互验证，用 Agent Teams

再展开一点，区别主要在这几个维度：

通信方式：Subagents 主要把结果回传给主对话；Agent Teams 的成员之间可以直接通信
协调模式：Subagents 更依赖主会话统一调度；Agent Teams 有共享任务列表，成员可以自己认领任务
Token 成本：Subagents 更省；Agent Teams 成本更高，因为每个 teammate 都是独立实例
适合任务：Subagents 更适合独立、结果导向的任务；Agent Teams 更适合需要讨论、交叉验证的任务

使用时要注意什么

Agent Teams 虽然更强，但并不意味着任何任务都值得开 team。原文特别提醒了几个现实问题：

token 消耗明显更高
同时让多个 teammate 改同一个文件，很容易互相覆盖
teammate 太多会增加协调成本，收益未必继续增长

因此，比较稳妥的做法通常是：

3 到 5 个 teammate 作为起点
按模块或文件拆任务，避免写入冲突
如果 lead 过早接手了 teammate 的任务，要明确告诉它先等队友完成

另外，当前实验能力还有一些限制，例如：

不支持 /resume 和 /rewind 恢复 in-process teammates
任务状态偶尔会滞后，需要人工提醒更新
一个 lead 一次只能管理一个 team
teammate 不能再继续派子 team

简单结论

这两个能力并不是替代关系，而是分别解决两类协作问题。

如果你的需求是“把支线任务并行做掉，别污染主上下文”，优先用 Subagents。如果你的需求是“让几个 Agent 像一个小团队一样协作、讨论、交叉验证”，再考虑 Agent Teams。

先用一个真实场景试一次，通常很快就能体会到差别：一个强调上下文隔离和结果回收，另一个强调多视角协同和持续互动。

Subagent on KnightLi的博客