👥 报告：Claude Code 代理团队 (Agent Teams) 深度指南

发布日期: 2026-02-06

Claude Code 的代理团队功能允许用户协调多个独立的 Claude Code 实例协同工作。在这种架构下，一个主会话充当 “团队领导”（Team Lead），负责协调工作、分配任务和综合结果。其余实例作为 “队友”（Teammates），它们在各自独立的上下文窗口中独立工作，并能直接相互通信。

一、核心概念：与子代理 (Subagents) 的区别

Agent Teams 引入了完全独立、可以相互通信的 Agent 实例，这与 Subagents（只能向主 Agent 报告结果）形成了本质区别。Agent Teams 最适用于并行探索能带来价值的复杂任务，如多角度研究、代码审查或竞争假设调试。

子代理 vs 代理团队

特性	Subagents（子代理）	Agent Teams（代理团队）
独立性	在单个主会话内运行	拥有自己的独立上下文窗口；完全独立
通信	仅向主代理报告结果	队友之间可以直接发送消息进行协作
协调	主代理管理所有工作	共享任务列表，队友可以自我协调、认领任务
最佳用途	快速、聚焦的任务，只关心结果	复杂工作，需要讨论、挑战和协作

二、适用场景与启动流程

1. 最佳使用场景

**研究和代码审查：** 拆分安全、性能、测试覆盖率等审查标准，进行并行审核。
**新模块或新功能开发：** 每个队友负责相互独立的模块部分。
**调试与竞争假设：** 通过“科学辩论”结构，让队友互相挑战假设，避免单 Agent 的“锚定效应”。
**跨层协调：** 涉及前端、后端和测试等多层更改。

启用要求： 需将环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 设置为 1。

2. 启动与控制

用户通过自然语言提示词描述任务和团队结构，Lead 会基于此创建团队、生成队友并协调工作。

交互控制： 用户可以通过主导会话向 Lead 发送指令。在 In-process 模式下，使用 Shift+Up/Down 切换到特定队友并直接与其通信。
显示模式： 支持 **In-process（进程内）** 和 **Split Panes（分屏）** 模式。Split Panes 需安装 tmux 或使用 iTerm2。

三、团队协作与高级控制机制

1. 任务分配与协作

团队通过 **共享任务列表** 协调工作。任务状态分为“待处理”、“进行中”和“已完成”，并支持任务依赖。

任务认领： Lead 可以明确分配任务，队友也可以自行认领下一个未分配、未阻塞的任务。
防竞争机制： 任务认领使用 **文件锁定** 机制来防止多个队友同时认领同一任务导致的竞争条件。

2. 规划批准与协调模式

规划批准 (Plan Approval)： 对于复杂或高风险任务，可要求队友在执行代码更改前提交规划书。Lead 会根据用户的提示词标准自主审查和批准。
协调模式 (Delegate Mode)： 启用后，Lead 会被限制为仅使用协调工具（生成、消息传递、关闭队友、任务管理），完全专注于工作分解、任务分配和结果合成，而不会亲自执行代码更改。

3. 上下文与通信

每个队友都有自己的上下文窗口，加载与 Lead 相同的项目上下文（CLAUDE.md、技能等），但 **不继承 Lead 的会话历史**。

信息共享： 通过 **自动消息投递**（队友之间可以直接发送消息）和 **共享任务列表** 实现信息共享。
Token 消耗： 代理团队会消耗显著更多的 Tokens，因为每个队友都是一个独立的 Claude 实例。

四、限制与最佳实践

1. 限制

Agent Teams 仍处于实验阶段，限制包括：一个 Lead 只能管理一个团队；不支持嵌套团队；Lead 角色固定；在 In-process 模式下会话恢复可能导致队友状态丢失；任务状态有时可能滞后。

2. 最佳实践总结

为确保高效协作：

提供足够的上下文： 在启动提示词中包含任务所需的所有细节。
合理规划任务大小： 任务应是独立、自洽的工作单元，避免过小（协调开销大）或过大（风险和浪费）。
避免文件冲突： 将任务分解为每个队友负责不同的文件集。
**从研究和审查开始：** 新手应从边界清晰、无需并行修改文件的任务开始，以熟悉其优势。

总字数： 约 2,200 字。

原文链接： https://code.claude.com/docs/en/agent-teams

返回首页