1. 核心概念与定位
Agent Teams 是 Claude Code 的一项实验性功能，旨在协调多个独立的 Claude Code 实例作为一个团队协同工作。
- 核心理念：将“并行探索”和“多视角辩论”引入开发流程，适用于需要讨论、协作和独立运作的复杂任务。
- 关键区别：与 Subagents（子代理）不同，Agent Teams 中的每个成员都是完全独立的会话，拥有自己的上下文窗口，并能直接相互通信。
2. Agent Teams vs. Subagents 对比分析
| 维度 | Subagents (子代理) | Agent Teams (智能体团队) |
|---|---|---|
| 上下文 (Context) | 拥有独立窗口，但结果仅汇总返回给调用者 | 完全独立的上下文窗口，不继承主会话历史 |
| 通信机制 | 单向：仅向主代理报告结果 | 双向/多向：队友之间可直接发送消息、辩论 |
| 协调方式 | 主代理全权管理所有工作流 | 自我协调：基于共享任务列表，队友可自主认领 |
| 适用场景 | 专注任务、顺序任务、强依赖关系任务 | 复杂协作、多视角调研、并行代码审查、竞争性假设验证 |
| Token 成本 | 较低：仅汇总结果回主上下文 | 较高：每个队友都是一个完整的 Claude 实例，消耗独立 Token |
3. 系统架构组件
Agent Team 由四个核心部分组成：
-
Team Lead (负责人)
- 主 Claude Code 会话。
- 职责：创建团队、生成队友、分解任务、分配工作、综合结果。
- 委派模式：可限制负责人仅使用协调工具（生成、发消息、关闭队友），防止其亲自写代码，专注于编排。
-
Teammates (队友)
- 独立的 Claude Code 实例。
- 职责：处理具体分配的任务，拥有完整的项目上下文（CLAUDE.md, MCP servers等）。
-
Task List (共享任务列表)
- 团队工作的中枢。
- 状态：
待处理(Pending)、进行中(In Progress)、已完成(Done)。 - 依赖管理：支持任务依赖，未解决依赖的任务无法被认领。
- 防竞态：使用文件锁定机制防止多人同时认领同一任务。
-
Mailbox (邮箱/消息系统)
- 代理间通信的基础设施。
- 支持
message(点对点) 和broadcast(广播，慎用，成本高)。 - 自动通知：队友空闲或完成时自动通知负责人。
4. 关键工作流程与机制
🚀 启动与配置
-
启用方式：设置环境变量
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1或在settings.json中配置。 -
触发方式：
- 用户明确请求（例如：“创建一个团队，包含UX、架构和反方角色”）。
- Claude 主动建议（当检测到任务适合并行处理时）。
-
显示模式：
- In-process (默认) ：在主终端内运行，通过
Shift+Up/Down切换视角。 - Split panes (分屏) ：需
tmux或iTerm2，每个队友独立窗格，直观展示并行工作流。
- In-process (默认) ：在主终端内运行，通过
🔄 任务管理与执行
-
任务创建：负责人分解工作并创建任务。
-
任务认领：
- 指派：负责人显式分配。
- 自认领：队友完成后自动领取下一个“未分配且无依赖阻塞”的任务。
-
计划审批 (Plan Approval) ：
- 针对高风险任务（如重构认证模块），可要求队友先输出计划。
- 负责人根据预设标准（如“必须包含测试覆盖”）批准或拒绝，队友需修订直至通过。
-
通信协作：队友可直接互相质疑（如科学辩论模式），共同收敛到最佳方案。
🛑 结束与清理
-
关闭队友：负责人发送关闭指令，队友优雅退出（可拒绝并解释原因）。
-
清理团队：执行
Clean up the team，删除本地共享资源（~/.claude/teams/,~/.claude/tasks/）。
5. 本地存储结构
团队状态持久化在本地文件系统中：
- 团队配置：
~/.claude/teams/{team-name}/config.json(包含成员列表、ID等) - 任务列表：
~/.claude/tasks/{team-name}/
6. 典型应用场景 (Use Cases)
A. 并行代码审查 (Parallel Code Review)
- 场景：对同一个 PR 进行多维度审查。
- 配置：生成3个队友，分别关注 安全性、性能影响、测试覆盖。
- 优势：避免单一视角遗漏，同时完成多方面检查。
B. 竞争性假设调查 (Competing Hypotheses)
- 场景：调试复杂Bug，根本原因不明。
- 配置：生成5个队友，每个持有一个不同的故障假设。
- 机制：要求队友互相辩论、试图证伪对方的理论。
- 优势：避免“锚定效应”，快速收敛到真实原因。
C. 多角色产品设计
- 场景：设计新 CLI 工具。
- 配置：UX 专家、技术架构师、反方角色 (Devil's Advocate)。
- 产出：综合多方观点的设计方案。
7. 最佳实践与注意事项
✅ 推荐做法
- 任务粒度适中：任务太小导致协调开销大，太大则容易偏离方向。建议分解为自包含的单元（如单个函数、测试文件）。
- 提供充足上下文：在生成提示中明确角色职责和关注点（如“专注于JWT令牌处理”）。
- 从非编码任务开始：先尝试代码审查、调研类任务，熟悉协作流程。
- 监控与引导：定期检查进度，防止队友在错误方向上浪费 Token。
- 避免文件冲突：确保不同队友操作不同的文件集。
⚠️ 局限性与风险 (实验性功能)
- 成本高昂：Token 消耗随队友数量线性增长。
- 会话恢复限制：In-process 模式下，
/resume可能无法恢复队友会话。 - 状态滞后：任务状态更新可能延迟，导致依赖任务阻塞。
- 环境依赖：分屏模式依赖
tmux或iTerm2，在 VS Code 集成终端或 Windows Terminal 中不支持。 - 嵌套限制：队友不能再生成自己的团队（无嵌套团队）。
- 负责人固定：团队创建后，负责人不可变更。
💡 个人思考/行动点：
- IDE 集成展望：目前的 Tmux 分屏虽然强大，但在 GUI 体验上仍有提升空间。未来基于 Electron 的 IDE（如 VS Code 插件）若能原生支持 Agent Teams 的多窗格可视化交互，将极大降低使用门槛。
- 成本控制策略：在提示词中明确“仅在必要时广播”，并利用“计划审批”机制防止队友盲目执行高成本操作。
- 自动化 Review：利用“计划审批”功能，将团队的 Review 标准固化到 Prompt 中（如“无测试不合并”），实现自动化质量门禁。
