Claude Code 多智能体协作：Subagents 与 Agent Teams

Claude Code 提供两种多智能体并行工作机制：Subagents（子智能体）和 Agent Teams（智能体团队）。两者都能让多个 Claude 实例并行执行任务，但在通信模型、协调方式和适用场景上有本质区别。

核心对比：怎么选？

第一部分：Subagents（子智能体）

什么是 Subagent

每个 SubAgent 是完全独立的 Claude 副本。你通过 Markdown 文件（.md）定义它的==系统提示 + 工具配置==组合，Claude Code 在需要时自动调用或由你手动触发。

产品逻辑：SubAgent 处理结果→返回给 Claude Code→Claude Code 汇总后输出给你。注意 SubAgent 的输出对象不是你，而是 Claude Code。

组成（5 个核心字段）

每个 SubAgent 是一个 .md 文件，由 frontmatter 定义：

存储位置与优先级

新建 SubAgent

1. 在项目的 .claude/agents/ 目录下创建 .md 文件
2. Claude Code 自动检测并加载
3. 在对话中自然调用，或让 Claude 自行判断何时使用

典型场景

你："这个支付模块需要全面审查"

Claude Code 并行创建 5 个 Task：

1. 架构分析 SubAgent → 模块设计和接口审查
2. 安全审计 SubAgent → SQL 注入、XSS、CSRF 检查
3. 性能分析 SubAgent → 慢查询和瓶颈定位
4. 代码质量 SubAgent → 测试覆盖和规范检查

5. 数据库 SubAgent → 索引和查询优化建议

6. 30 分钟返回 5 份报告（串行需 2.5 小时）

7. 成本：5 倍 Token，节省 80% 时间
8. 本质是==时间换成本==的策略：Token 线性累加，但时间节省 50-80%

适用场景评级

第二部分：Agent Teams（智能体团队）

什么是 Agent Teams

Agent Teams 让多个 Claude Code 实例组成团队协同工作：

• 一个 Team Lead（主会话）负责协调、分配任务、综合结果
• 多个 Teammates（队友）各自独立工作，拥有各自的上下文窗口
• 队友之间可以直接通信，不需要经过 Lead 中转
• 你也可以直接与任意队友对话，给它额外指令

启用

在 settings.json 中添加：

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

或设置环境变量：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

最佳使用场景

架构

存储位置：
- 团队配置：~/.claude/teams/{team-name}/config.json（自动管理，不要手动编辑）
- 任务列表：~/.claude/tasks/{team-name}/

快速开始

用自然语言告诉 Claude 创建团队即可：

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.

Claude 会自动创建团队→生成队友→并行探索→综合发现→清理团队。

显示模式

默认 "auto"：已在 tmux 会话中→分屏，否则→in-process。

// ~/.claude.json 手动设置
{ "teammateMode": "in-process" }

# 单次会话指定
claude --teammate-mode in-process

团队控制

指定队友和模型

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

要求计划审批

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

流程：队友在只读 plan 模式工作→提交计划→Lead 批准或驳回→批准后开始实施。

直接与队友对话

• In-process：Shift+Down 切换 → 打字发消息 → Enter 查看会话 → Escape 中断 → Ctrl+T 任务列表
• Split-pane：点击窗格直接交互

任务分配

任务有三种状态（Pending → In Progress → Completed），支持依赖关系和文件锁。

关闭与清理

Ask the researcher teammate to shut down   # 关闭单个队友
Clean up the team                           # 清理整个团队

上下文与通信

队友加载项目上下文（CLAUDE.md、MCP、Skills），但不继承 Lead 对话历史。

复用 Subagent 定义

可以用已有的 Subagent 类型创建队友：

Spawn a teammate using the security-reviewer agent type to audit the auth module.

队友继承该定义的 tools 和 model，但 skills/mcpServers 字段不应用。团队协调工具（SendMessage、任务管理）始终可用。

权限

队友继承 Lead 权限设置，生成后可单独修改，但不能在生成时预设。

Hooks 质量门禁

已知限制

实战案例

Subagents：并行代码审查

"这个支付模块需要全面审查"

→ 并行 5 个 SubAgent（架构/安全/性能/质量/数据库），30 分钟返回 5 份报告。

Agent Teams：竞争假设调试

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 Teams 独有的高价值模式，SubAgents 无法实现（因为 SubAgent 之间不通信）。

Agent Teams：分角度 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.

每个评审者应用不同视角，Lead 综合发现。

最佳实践总览

通用原则

1. 从研究评审类任务入手——先感受并行价值，再尝试并行开发
2. 避免文件冲突——确保每个并行工作者负责不同的文件集
3. 持续监控和引导——无人看管太久会增加浪费风险

Subagents 专属

1. 明确任务边界和产出——SubAgent 无状态，一次性交付
2. 只用于独立任务——有依赖关系的任务不要拆分到 SubAgent

Agent Teams 专属

1. 给队友足够上下文——队友不继承 Lead 对话历史，spawn 时提供具体细节
2. 起步 3-5 人——平衡并行度和协调开销，3 个聚焦优于 5 个分散
3. 每人 5-6 个任务——保持高效又不过度切换
4. 合理划分任务粒度——太小协调开销大，太大浪费风险高
5. 让 Lead 等待队友——如果 Lead 自己开始做任务，明确告诉它等待

故障排查（Agent Teams）

第三部分：Git Worktree 并行开发

来源：Claude Code 并行开发完全指南

当需要在同一个项目里同时处理多个不兼容的改动时，Git Worktree 比 Agent Teams 更底层、更稳定——它提供的是分支级别的文件系统硬隔离。

适用场景

• 同时做 Feature A 和 Refactor B，两者改动重叠，不能在同一分支串行
• 保持当前工作目录干净的同时并行处理紧急 Bugfix
• 多人协作避免合并冲突

基础命令

# 查看当前所有 Worktree
git worktree list

# 创建新 Worktree（同时创建新分支）
git worktree add ../feature-auth -b feature/auth
git worktree add ../bugfix-urgent -b bugfix/urgent

# 在新目录里启动 Claude Code
cd ../feature-auth
claude

# 工作完成后合并回主分支
git checkout main
git merge feature/auth
git worktree remove ../feature-auth
git branch -d feature/auth

实战：结合 Claude Code 并行开发

# 场景：同时处理新功能 + 重构

# 1. 主分支继续开发新功能
cd ~/projects/myapp
claude

# 2. 创建 Worktree 做重构（隔离）
git worktree add ../refactor-db -b refactor/db
cd ../refactor-db
claude
# 新会话里专门做数据库重构，不影响主分支

# 3. 两边并行做完，合并
git checkout main
git merge refactor/db
git worktree remove ../refactor-db

Git Worktree vs Agent Teams 怎么选

• 用 Git Worktree：改动会相互冲突、需要硬隔离、多人协作场景
• 用 Agent Teams：需要快速并行探索、多个角色同时讨论方案

第四部分：工作流编排

前面三种方案解决的是"怎么并行"，工作流编排解决的是"多个工作单元怎么有序配合"。

Plan 模式：动手前的任务分解

Claude Code 内置 /plan 命令，是一个任务规划工具——把"想清楚做什么"和"动手做"分开。

/plan
# Claude 分析项目结构和任务需求
# 输出分步骤计划，等待确认后才执行

在工作流中嵌入 Plan 模式

architect（Agent Team）：用 /plan 分析 src/modules 的依赖关系，给出重构优先级。

architect 的 plan 确认后，分配给 frontend-dev 和 backend-dev 各自执行。

backend-dev：
/plan
根据 architect 的分析结果，设计 database schema 迁移方案。

每个 Agent 动手前都有一次"想清楚"的环节，减少返工。

Multi-Agent 协作工作流模板

阶段一：任务分解（Plan 模式）
├─ 主会话：定义项目范围和目标
├─ /plan：拆解为具体模块
└─ 输出：完整的任务分解清单

阶段二：角色分配（Agent Teams）
├─ architect：架构设计和方案评审
├─ frontend-dev：前端实现
└─ backend-dev：后端实现

阶段三：并行执行
├─ 各 Agent 独立工作
├─ 通过共享上下文通信
└─ architect 协调冲突

阶段四：整合与 Review（Subagents）
├─ code-reviewer：全面代码审查
├─ test-writer：生成测试用例
└─ architect：最终架构评审

阶段五：合并（Git Worktree）
├─ 合并各分支到 main
└─ 运行集成测试

把工作流固化到 CLAUDE.md

将团队配置和工作流模板写入项目的 CLAUDE.md，Claude Code 启动时自动加载，新成员 clone 即可复用：

# 项目 AI 团队配置

## 默认团队
| 角色 | 职责 |
|------|------|
| architect | 架构设计和技术方案评审 |
| frontend-dev | 前端开发，React/TypeScript/Tailwind CSS |
| backend-dev | 后端开发，Node.js/Python + PostgreSQL |
| code-reviewer | 代码审查，安全和质量问题 |

## 工作流规范
1. 涉及多模块时，先用 /plan 拆解，确认后再执行
2. architect 评审通过的技术方案，才能分配给前端/后端
3. 所有代码合并前必须经过 code-reviewer 审查

Routines：定时自动执行

Routines 把"一次 prompt + 代码仓库 + 触发条件"打包成配置，在 Anthropic 云端运行，不需要电脑保持开机。

三种触发方式：

配置示例：

/claude routine create \
  --name "morning-review" \
  --prompt "审查昨晚到现在的所有 commits，重点关注：安全漏洞、性能问题、测试覆盖率" \
  --trigger "0 8 * * *" \
  --repo ./my-project

与 Agent Teams 配合——无人值守流水线：

Routines（定时 08:00）
  └─→ 触发 Agent Teams
        ├─ architect：代码审查
        ├─ backend-dev：Bug 修复
        └─ frontend-dev：依赖检查
  └─→ 审查结果自动发 PR comment 或邮件通知

常见坑

全局选型决策表

这四条路不矛盾，一个项目里往往组合着用：Subagents 定义角色，Agent Teams 处理并行部分，Git Worktree 做分支硬隔离，工作流编排把全局串起来。

开源 Agents 推荐

wshobson/agents

项目定位

这是目前最大的 Claude Code Agent 开源集合，目标是为软件开发提供细粒度自动化和多智能体编排。核心设计理念：

• 按需加载：安装 marketplace 后不会加载任何 agent，安装具体插件才加载对应能力
• 23 个领域覆盖：从架构设计到 SEO 优化，覆盖软件开发全生命周期
• 四级模型策略：根据任务复杂度分配 Opus/Sonnet/Haiku，兼顾质量和成本
• 可以支持agent teams

安装：

# 第一步：添加 marketplace（使所有 72 个插件可用，不加载任何 agent）
/plugin marketplace add wshobson/agents

# 第二步：安装具体插件（按需）
/plugin install agent-teams@claude-code-workflows
/plugin install backend-development@claude-code-workflows

多Agent vs 单Agent架构决策分析

核心论点

多Agent在现阶段很多时候是伪需求。 选择多Agent还是单Agent，关键在于两个判断标准：任务信息是否真的需要隔离？任务是否需要并发？

决策框架

两个关键判断维度

单Agent更优的场景（单任务）

• 流程中的信息需要每个Agent都感知到
• 多Agent的隔离会损失信息
• 只要模型注意力够准，单Agent会是一个任务更好的选择
• 不存在真正的并发需求（只是在"抢那一点并发时间"）

多Agent更优的场景（身份切换）

• 不同任务对应不同Agent，而不是一个任务跑多个Agent
• 本质是"身份切换"——每个Agent有独立的角色定位和上下文
• 例如：代码编写Agent、代码审查Agent、测试Agent分别处理不同阶段的任务

深层原因分析

信息损失问题

多Agent架构天然引入信息隔离边界。当一个任务的所有步骤都需要完整的上下文时，Agent间的通信开销和信息丢失会超过并行带来的收益。

模型注意力是关键约束

单Agent方案的瓶颈在于模型的注意力机制能否在长上下文中保持准确。随着模型能力提升（更长的有效上下文窗口、更准确的注意力），单Agent的适用范围会进一步扩大。

多Agent的真正价值

多Agent的价值不在于"多个Agent做同一件事"，而在于：
- 角色专业化：不同Agent有不同的系统提示、工具集、知识范围
- 任务路由：根据任务类型分配到合适的Agent
- 关注点分离：避免单Agent的角色混淆

与现有知识的关联

• 多智能体协作来源摘要中的Claude Code实现印证了这一分析：
• Subagents（子Agent）本质上是单任务分派，主Agent保持完整上下文
• Agent Teams中的辩论结构（竞争假设）是多Agent真正有价值的模式——不同"身份"提出不同观点
• Claude Code的实际设计也体现了"单Agent为主、多Agent为辅"的思路

实践建议

1. 默认从单Agent开始，除非有明确的并发或隔离需求
2. 多Agent架构应按任务类型划分Agent，而非按任务步骤划分
3. 评估多Agent方案时，优先考虑信息完整性而非架构美感
4. 关注模型注意力能力的发展——这是单Agent方案的天花板