Claude 多智能体架构全解析

很多人一看到复杂任务，第一反应就是「上多智能体」。

问题的根本不是「要不要用多智能体」，而是「这个任务到底需要什么样的协作方式」。

Claude 给了我们两套完全不同的多智能体方案：Subagents 和 Agent Teams。它们看起来很像，但底层设计哲学完全不同。用错了，不仅解决不了问题，还会让系统变得更复杂、更难维护。

Sub-Agents：通过隔离实现并行性

Subagent 是一个运行在独立上下文窗口中的 Claude 实例。

每个子智能体都拥有自己的系统提示词（定义它的专长）、特定的工具集（它能访问什么）、干净的、隔离的上下文窗口和一个明确的任务

核心机制：只返回结果，不返回过程

当 Subagent 完成任务后，只会将最终结果会返回给父 Agent，不会返回中间过程，而且这个结果是压缩后的。

这意味着 Subagent 的核心价值不只是并行，而是压缩。

你把大量的探索过程压缩成一个干净的信号，不会污染父 Agent 的上下文。

关键约束：子Agent不能嵌套，不能互相通信

Subagent 有一个硬性约束：不能生成其他子智能体，也不能相互通信

每个结果都必须流回父 Agent。父 Agent 是唯一的协调者。

这个约束特性让系统变得可预测——你总能知道信息流向何处，以及决策在何处制定。

适用场景

Subagent 适合的场景：

独立的研究流：比如同时搜索 5 个不同主题
代码库探索：让一个 subagent 专门找安全漏洞，另一个专门找性能问题
并行查询：需要快速覆盖多个方向，父 Agent 只需要汇总结果

一句话总结：如果你只需要结果，不需要过程，用 Subagent。

Agent Teams：持久 + 通信，核心是「持续协作」

Agent Team 是完全不同的模型。

Subagent 是短期存在的工人，完成任务就消失。而 Agent Team 是长期运行的实例，它们会持续存在、直接互相通信、通过共享状态来协调。

打个比方：Subagent 像是雇佣承包商完成独立任务；Agent Team 像是组建一个团队，大家在一个房间里一起工作。

三个核心组件

一个 Agent Team 包含三个部分：

Team Lead：协调工作、分配任务、综合结果
Teammates：独立的 Agent 实例，各自有自己的上下文窗口，并行工作
Shared Task List：追踪待办、进行中、已完成的任务，以及任务之间的依赖关系

任务依赖：自动协调

看一个典型的生命周期：

Claude (Team Lead):
└── spawnTeam("auth-feature")
    Phase 1 - Planning:
    └── spawn("architect", prompt="设计 OAuth 流程")

    Phase 2 - Implementation (并行):
    └── spawn("backend-dev", prompt="实现 OAuth 控制器")
    └── spawn("frontend-dev", prompt="构建登录 UI 组件")
    └── spawn("test-writer", prompt="写集成测试", blockedBy=["backend-dev"])

注意 blockedBy 字段。这就是共享任务列表在起作用：测试编写者会等到后端 Agent 完成后才开始，Lead 不需要手动管理这个顺序。

直接通信：Peer-to-Peer

Agent Team 最大的不同是直接通信。

Teammates 可以直接给彼此发消息、分享发现、暴露阻塞点、协商解决方案——不需要所有东西都经过 Lead。

你还可以直接和单个 teammate 交互，不必每次都通过 Lead。

适用场景

Agent Team 适合需要持续协作的任务：

需要协商的场景：前端 Agent 发现 API 结构需要改，后端 Agent 可以立即调整
中途发现会改变其他线程：一个线程的发现会影响另一个线程该做什么
复杂的多阶段项目：需要长期上下文积累

一句话总结：如果 Agent 之间需要持续协调和共享发现，用 Agent Team。

核心区别：一次性任务 vs 持续协作

维度	Subagents	Agent Teams
生命周期	短期，任务完成就消失	长期，持续存在
通信方式	只和父 Agent 通信	Agent 之间可以直接通信
状态共享	无共享状态	共享任务列表和状态
协调方式	父 Agent 集中协调	分布式协调
适用场景	独立的并行任务、并行探索	需要持续协作的任务

最简单的判断方法：

Subagents：任务可以独立完成，只需要最终结果
Agent Teams：任务之间有依赖，中途需要协调

什么时候不该用多智能体？

很多团队花了数月搭建复杂的多智能体管道，最后发现：更好的单智能体提示词就能达到相同效果。

值得用多智能体的三种情况:

上下文保护：子任务产生的信息与主任务无关，用 Subagent 可以防止上下文膨胀
真正的并行化：独立的研究或搜索任务，需要同时覆盖多个方向
专业化：任务需要冲突的系统提示词，或者一个 Agent 工具太多导致性能下降

不该用的情况

Agent 频繁需要共享上下文：如果你发现 Agent 之间一直在交换信息，可能应该合并成一个 Agent
Agent 间依赖造成的开销比执行价值还大：协调成本超过了并行收益
任务足够简单：一个提示词写得好的 Agent 就能搞定

一个具体警告：多个 Agent 并行写代码会做出不兼容的假设。当代码合并时，这些隐式决策会以难以调试的方式冲突。写代码的 Subagent 应该回答问题和探索，而不是和主 Agent 同时写代码。

另一篇

Subagents：主线不断，分身干活

Subagents 是在当前会话里派出去的「分身」，每个分身有独立的上下文窗口，干完活只把结果摘要返回给主对话。主对话不会被那些大量输出塞满。

Claude Code 自带三个内置 Subagent：

Explore：只读权限，用 Haiku 模型。Claude 需要搜索代码库但不想改东西时自动调它，速度快、省钱
Plan：只读权限。你进入 plan mode 时，它负责在后台收集代码库信息，不会影响主线
General-purpose：全权限，处理需要同时探索和修改的复杂任务

这三个是自动触发的，不用手动指定。

自定义 Subagent

内置的不够用可以自己写。一个 Subagent 就是一个 Markdown 文件，放到对应目录里：

.claude/agents/：只在当前项目生效，可以提交到 git 和团队共享
~/.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 控制这个 Subagent 能用哪些工具。只想让它做只读研究，就限制成 Read, Grep, Glob，它就没法动你的代码。只写了 tools 字段，没列出的工具就用不了；什么都不写的话，继承主对话的全部工具。

model 控制用哪个模型。支持 sonnet、opus、haiku、inherit（跟主对话一样）。搜索扫描类任务用 Haiku 省钱，写代码或审查用 Sonnet。

permissionMode 控制权限模式。acceptEdits 让它自动接受文件编辑，dontAsk 让它遇到权限提示自动拒绝，bypassPermissions 跳过所有检查。

memory 给 Subagent 一个跨对话的记忆目录。设 user 存到 ~/.claude/agent-memory/，设 project 存到 .claude/agent-memory/，跑完一次它会自己往里面写东西，下次还能看到。

也可以通过 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

最有用的几个场景：

跑测试套件产生几千行输出——让 Subagent 去跑，只把失败的测试和报错摘要回来，主上下文省了一大截。

独立调查并行化——几个没有依赖关系的研究任务，同时派出去，比串行快多步骤流水线——代码审查 Subagent 找到问题，把结果传给优化 Subagent 去修：

什么时候不该用 Subagent

任务需要频繁来回调整、几个阶段共用大量上下文、改动集中在一两个文件、对响应速度敏感——这些情况直接在主对话里做更好，Subagent 启动要重新建上下文，有延迟。

Agent Teams：多个独立会话，互相通信

Agent Teams 是另一个层级的东西。不是在一个会话里派分身，而是启动多个完全独立的 Claude Code 实例，它们共享一个任务列表，可以互相发消息。

开启后，告诉 Claude 你要一个 Agent Team，描述清楚任务和团队结构，它会自动建队、派成员、分配任务：

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 Team 由三部分组成：

Team lead：你在用的那个主会话，负责建队、分派任务、汇总结果
Teammates：独立的 Claude Code 实例，各自有独立上下文窗口
Task list：共享的任务列表，存在 ~/.claude/tasks/{team-name}/ 里
Mailbox：代理之间互相发消息的通道

Teammates 之间可以直接通信，不用经过 lead。一个 teammate 发消息，对方自动收到，不需要 lead 中转。任务有三个状态：pending、in progress、completed。Teammate 完成一个任务后，会自动去认领下一个没人做的任务。

怎么操作

默认是 in-process 模式：所有 teammates 跑在你的主终端里，用 Shift+Down 在 lead 和各个 teammate 之间切换，切过去直接打字就是给那个 teammate 发消息。

如果你用 tmux 或 iTerm2，可以开 split-pane 模式，每个 teammate 有自己的独立窗格，同时看到所有人的输出。设置方法：

{
    "teammateMode": "tmux"
}

任务分配有两种方式：你告诉 lead 把哪个任务给哪个 teammate，或者 teammates 自己认领。认领时用文件锁防止多人同时抢一个任务。

你也可以直接跟某个 teammate 说话，不用经过 lead。比如你看到某个 teammate 方向跑偏了，直接 Shift+Down 切过去，告诉它调整方向。

适合 Agent Teams 的场景

并行代码审查——三个 reviewer 同时看同一个 PR，各自盯不同维度：

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.

竞争假说调试——排查根因最怕一个 agent 找到一个合理解释就停了。多个 agent 互相挑战各自的理论，能活下来的才是真根因：

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.

跨模块并行开发——前端、后端、测试各一个 teammate，各自负责不同文件，不会互相覆盖。

注意事项

Agent Teams 的 token 消耗比 Subagents 高很多，每个 teammate 是独立的 Claude 实例。3-5 个 teammate 是比较合理的起点，每人 5-6 个任务最合适，太多了协调成本上升、效果不一定好。

避免让两个 teammate 同时编辑同一个文件，会互相覆盖。拆分任务时按文件或模块分。

Lead 有时会等不住，自己去做 teammate 的任务。如果发现这个情况，直接告诉它「等你的 teammates 做完再动」。

当前已知限制：

不支持 /resume 和 /rewind 恢复 in-process teammates
任务状态有时会滞后，teammate 做完了但没标 completed，卡住了就手动告诉 lead 更新状态
一个 lead 只能管一个 team，做完一个再开下一个
Teammate 不能再派子 team

Sub-Agents：通过隔离实现并行性​

核心机制：只返回结果，不返回过程​

关键约束：子Agent不能嵌套，不能互相通信​

适用场景​

Agent Teams：持久 + 通信，核心是「持续协作」​

三个核心组件​

任务依赖：自动协调​

直接通信：Peer-to-Peer​

适用场景​

核心区别：一次性任务 vs 持续协作​

最简单的判断方法：​

什么时候不该用多智能体？​

值得用多智能体的三种情况:​

不该用的情况​

另一篇

Subagents：主线不断，分身干活​

自定义 Subagent​

主要配置项​

什么时候用 Subagents​

什么时候不该用 Subagent​

Agent Teams：多个独立会话，互相通信​

架构​

怎么操作​

适合 Agent Teams 的场景​

注意事项​

Sub-Agents：通过隔离实现并行性

核心机制：只返回结果，不返回过程

关键约束：子Agent不能嵌套，不能互相通信

适用场景

Agent Teams：持久 + 通信，核心是「持续协作」

三个核心组件

任务依赖：自动协调

直接通信：Peer-to-Peer

适用场景

核心区别：一次性任务 vs 持续协作

最简单的判断方法：

什么时候不该用多智能体？

值得用多智能体的三种情况:

不该用的情况

Subagents：主线不断，分身干活

自定义 Subagent

主要配置项

什么时候用 Subagents

什么时候不该用 Subagent

Agent Teams：多个独立会话，互相通信

架构

怎么操作

适合 Agent Teams 的场景

注意事项