Claude Code Agent Teams（团队协作）完全指南

一、概述

Claude Code 的 Agent Teams 是一项强大的多代理协作功能，它允许开发者创建多个子代理组成团队，协同完成复杂的开发任务。与传统的单代理模式不同，Team 模式引入了分工协作的理念——每个子代理负责整体任务的不同子集，通过 TaskList 机制协调各自的进度，并通过 SendMessage 实现代理间的直接沟通。

Team 模式的核心价值在于将大型复杂任务拆解为多个相对独立的小任务，由不同的代理并行处理。这种架构天然适合大型代码库的重构、多模块并行开发、代码审查流水线等场景。每个团队成员都有自己的上下文空间，可以专注于自己的任务领域，避免了单代理模式下上下文窗口被混合信息快速填满的问题。

在实际使用中，Team 模式下有一个"团队领导"角色，通常由创建团队的代理（即当前的 Claude Code 会话）充当。领导负责任务的创建与分配、进度的跟踪以及最终成果的整合。其他团队成员各司其职，完成被分配的任务，并通过 TaskList 和 SendMessage 与领导及同事保持同步。

与单 Agent 模式相比，Team 模式更适合复杂、需要多角色协作的项目。单 Agent 模式简单直接，适合独立完成的中小型任务；而 Team 模式虽然有一定的管理和通信开销，但应对大型项目时效率和并行度都有显著提升。开发者需要根据任务规模做出合理的选择。

二、Team 的创建与管理

Team 的创建是使用 Agent Teams 功能的第一步。通过 TeamCreate 工具，开发者可以创建一个新的团队，指定团队名称和描述信息。创建成功后系统会在本地生成团队配置文件，团队的名称会参与后续的任务路由和消息分发。

团队的配置文件存储在 ~/.claude/teams/{team-name}/config.json 路径下。这个文件记录了团队的基本信息，包括团队名称、描述以及可选的成员配置。团队成员之间通过这个 config 文件互相发现彼此的存在——当一个代理以某个 team_name 启动时，它会读取该团队的配置文件，从而了解团队中有哪些成员以及各自的身份。

任务列表数据则存储在 ~/.claude/tasks/{team-name}/ 目录中。每个团队拥有自己独立的任务列表存储空间，这意味着不同团队的任务完全隔离，不会相互干扰。这也是为什么团队名称需要具有唯一性的原因之一。

当团队不再需要时，应使用 TeamDelete 工具进行清理。TeamDelete 会删除团队配置文件及其对应的任务列表目录，释放存储空间。这是一个良好的资源管理习惯，特别在多次实验和测试场景中尤为重要。

团队配置管理

团队配置文件采用 JSON 格式，存储在本地文件系统中。这样可以保证配置的持久性——即使当前会话结束，下次启动时仍然可以通过相同的 team_name 访问已有的团队。团队成员在启动时通过指定 team_name 参数自动加入团队，无需手动编辑配置文件。

三、任务管理（TaskList）

TaskList 是 Agent Teams 的核心协调机制。它提供了一套完整的任务生命周期管理工具，涵盖任务的创建、查看、更新和依赖管理。所有团队成员通过 TaskList 了解当前任务的整体进展、各自的职责以及需要完成的工作。

TaskCreate — 创建任务

使用 TaskCreate 可以创建新的任务，描述任务的内容和目标。创建时需要指定所属的团队名称、任务标题和详细描述。描述应当清晰明确，包含具体的验收标准，这样团队成员才能准确理解任务的要求并正确地完成它。

TaskList — 查看任务

TaskList 用于查看所有任务及其当前状态。任务状态包括 pending（待处理）、in_progress（进行中）和 completed（已完成）。通过 TaskList，团队领导和成员可以一目了然地了解项目全景——哪些任务已经完成，哪些正在处理，哪些还处于等待状态。

TaskUpdate — 更新任务

TaskUpdate 用于更新任务的状态和所有者。其中最关键的参数是 owner，它指定了由哪个代理负责执行该任务。当代理认领任务时，它会通过 TaskUpdate 将任务状态从 pending 更新为 in_progress，并将 owner 设置为自己。任务完成后，再将状态更新为 completed。如果某个任务因为前置任务尚未完成而无法开始，也可以通过 TaskUpdate 设置阻塞依赖关系。

任务依赖管理

在实际项目中，任务之间往往存在依赖关系。例如，"编写单元测试"任务必须等待"实现核心功能"任务完成后才能开始。TaskList 支持通过阻塞任务关系来管理这种依赖。当某个任务标记了阻塞依赖后，系统会阻止该任务被错误地提前执行，直到依赖的任务完成为止。

四、团队工作流程

标准的 Agent Teams 协作流程遵循一个清晰的八步工作流。从创建团队开始，到最终清理资源结束，每个步骤都有其特定的目的和操作方式。掌握这套流程是高效使用 Agent Teams 的基础。

1. 创建团队（TeamCreate）
   使用 TeamCreate 工具创建团队，指定团队名称和描述。这是所有后续操作的前提，团队创建后会生成对应的配置文件和任务存储目录。
2. 创建任务列表（TaskCreate）
   根据项目需求，将整体任务拆解为若干子任务，逐一使用 TaskCreate 创建。任务描述应当详细明确，包含具体的实现要求和验收标准。建议一次性地将所有任务都创建好，形成一个完整的任务清单。
3. 启动团队成员（Agent with team_name）
   启动新的子代理实例时，指定 team_name 参数，使其自动加入先前创建的团队。每个子代理启动后会自动读取团队配置和任务列表，了解团队的整体情况。
4. 分配任务（TaskUpdate with owner）
   团队领导通过 TaskUpdate 将任务分配给指定的团队成员，设置 owner 参数明确责任人。分配时应当考虑每个成员的专业领域和当前工作负载。
5. 成员认领任务并工作
   团队成员接收到任务分配后，将任务状态更新为 in_progress，然后开始具体的工作。工作期间成员可以通过 TaskList 查看进度，通过 SendMessage 与其他成员沟通。
6. 完成时标记任务
   任务完成后，成员将任务状态更新为 completed，并提供完成摘要说明做了什么、改了哪些文件、有无遗留问题。清晰的完成记录有助于团队领导和后续成员了解进展。
7. 通知团队领导
   关键任务完成后，通过 SendMessage 通知团队领导进行审查或整合。领导可以检查工作质量，决定是否需要调整后续任务或分配新的工作。
8. 清理团队资源（TeamDelete）
   所有任务完成后，使用 TeamDelete 清理团队配置和任务列表。这是良好的资源管理实践，避免残留的配置文件影响后续项目。

五、代理间通信

在团队协作中，代理间的通信是不可或缺的环节。Claude Code 提供了 SendMessage 工具来实现这一功能。通过 SendMessage，一个代理可以向指定的团队成员发送消息，接收方会在自己的会话中看到这条消息，并可以基于消息内容做出响应。

SendMessage 的设计思想是"命名寻址"——通过 name 参数指定接收方的代理名称。消息发送后会自动投递到接收方的消息队列中，并在接收方空闲时显示通知。这类似于异步消息通信模式，发送方不需要等待接收方立即响应，接收方可以在方便的时候处理消息。

通信协议方面，除了普通的文本消息外，SendMessage 还支持一些特殊类型的消息，如 shutdown_request（请求成员关闭）和 plan_approval_request（请求计划审批）。这些预定义的消息类型为特定场景提供了标准化的通信方式，避免了自由格式消息可能带来的歧义。

在 idle 通知中，系统会显示消息摘要，让空闲中的代理了解有哪些消息需要处理。这种机制确保了消息不会被遗漏，即使接收方当时正处于忙碌状态。同时，过多的代理间通信也会消耗上下文窗口，因此建议只在必要时进行通信，避免频繁的"闲聊"。

六、任务协调策略

高效的团队协作离不开合理的任务协调策略。在 Agent Teams 中，有多个关键策略可以提升团队的整体工作效率，确保任务按时高质量完成。

任务优先级排序

当团队中有多个任务并行时，合理的优先级排序至关重要。建议按照"关键路径法"进行排序——首先识别出哪些任务是整个项目的关键路径（即延误会导致整体延误的任务），然后将这些任务设为最高优先级，优先分配资源和人力。非关键路径上的任务可以安排在后面处理，或者分配给空闲的成员。

阻塞任务处理

当某个任务因为依赖关系而阻塞时，被阻塞的代理不应空闲等待。一种有效的策略是让被阻塞的代理先处理其他无依赖关系的任务，或者协助完成阻塞任务的前置工作。如果阻塞时间过长，团队领导应当介入，评估是否需要调整任务分配方案，甚至将部分前置工作分配给更多成员并行处理。

任务重新分配

在任务执行过程中，可能会出现某个成员进展缓慢或遇到无法解决的困难的情况。此时团队领导应及时介入，通过 TaskUpdate 将任务重新分配给其他更有经验的成员。重新分配时需要注意保存已有工作的成果，避免重复劳动。同时，对于频繁出现困难的成员，领导应当考虑是否分配给该成员的任务粒度太粗或难度太大。

空闲代理的任务领取

当某个成员完成了自己被分配的所有任务后，它应当主动查看 TaskList 中是否有其他 pending 状态的任务可以认领。这种"空闲认领"机制可以让团队的人力资源得到充分利用，避免某些成员忙不过来的同时其他成员处于闲置状态。空闲代理还可以主动联系领导请求分配新的工作。

进度跟踪和汇报

团队领导应当定期通过 TaskList 查看整体进度，了解各个任务的完成情况。对于进度明显落后的任务，领导需要分析原因并采取相应措施——可能是任务拆分不合理、资源不足或者遇到了技术难题。领导还可以通过 SendMessage 要求成员汇报最新进展，以便及时调整计划。

七、实际应用案例

以下是 Agent Teams 在四种典型场景中的实际应用案例，展示了如何将这套工具和流程应用到真实开发项目中。

案例1：大型重构项目

在一个大型单体应用向微服务架构迁移的项目中，团队由 4 个代理组成：一个"架构分析代理"负责代码分析和依赖梳理，三个"重构执行代理"分别负责不同模块的重构工作。架构分析代理首先分析整个代码库，梳理模块间的依赖关系，创建 migration 任务列表。然后三个执行代理并行工作，每个负责 3-4 个模块的迁移。执行代理之间通过 SendMessage 通报进度和需要协调的边界问题。最终架构分析代理负责验证重构后的代码一致性。这种模式比单代理逐个模块处理快了约 3 倍。

案例2：多模块开发

在一个典型的 Web 应用开发中，可以分配前端代理、后端代理和数据库代理三个角色。前端代理负责 React 组件和页面开发，后端代理负责 API 和业务逻辑，数据库代理负责 Schema 设计和查询优化。三个代理通过 TaskList 协调进度——后端 API 完成后再通知前端开始集成，数据库 Schema 变更时通知后端更新查询。这种角色分工让每个代理专注于自己的领域，避免了上下文切换的损耗。

案例3：代码审查流水线

在协作开发流程中，可以设置三个代理组成审查流水线：编码代理负责实现功能，审查代理负责 Code Review，测试代理负责编写和运行测试。编码代理完成任务后，通过 SendMessage 通知审查代理开始审查。审查通过后，测试代理接手进行自动化测试。如果某一环节发现问题，消息会回传给上游代理进行修正。这种流水线模式确保了每段代码在合入主分支前都经过了审查和测试双重验证。

案例4：文档生成

在 API 文档生成场景中，分析代理负责扫描代码库提取 API 定义和参数说明，文档代理负责将提取的信息组织成结构化的 Markdown 文档，校对代理负责检查文档的完整性和格式一致性。三个代理依次工作，前一个代理的输出是后一个代理的输入。分析代理产生的 JSON 格式 API 定义作为中间产物，文档代理基于此生成文档，校对代理最后检查并修正格式问题。

八、注意事项

虽然 Agent Teams 功能强大，但在实际使用中需要注意以下几个方面，以避免常见的问题和陷阱。

上下文消耗

每个团队成员都独立消耗 token 和上下文窗口。这意味着团队的总 token 消耗会随着成员数量的增加而线性增长。在规划团队规模时，需要权衡并行效率提升和 token 成本增加之间的关系。一般来说，3-5 个成员的团队在大多数场景下能够取得较好的性价比。超过 10 个成员的团队往往通信和协调成本会超过并行带来的收益。

任务粒度

任务拆分的粒度直接影响团队的工作效率。任务粒度过细会导致大量的管理开销——创建任务、更新状态、分配 owner 的时间可能超过了实际工作时间。任务粒度过粗则会导致责任不清，一个任务可能包含多个需要不同专业知识的工作，不利于分配给专门的成员。推荐的粒度是每个任务可在 30 分钟到 2 小时内完成。

通信效率

过多的代理间通信会降低整体效率。每次 SendMessage 都会消耗双方的上下文窗口，并且打断正在工作中的代理。建议仅在必要时进行通信——如任务完成通知、需要协调的问题、进度汇报。常规的状态变更通过 TaskList 即可表达，无需额外发送消息。对于大型项目的协调，可以设定固定的"汇报时间"而非实时更新。

资源管理

控制团队成员数量是资源管理的关键。每个新增成员都会增加系统负担和上下文消耗。在启动新成员前，先思考：这个任务真的需要独立的代理吗？是否可以由现有成员完成？是否存在更简单的替代方案？同时，注意监控每个成员的上下文使用情况，避免某些成员的上下文窗口被过度占用。

清理资源

团队工作完成后，务必调用 TeamDelete 清理团队配置和任务列表。残留的配置文件会导致下次启动时找不到对应的团队而报错，或者更糟糕地——意外地加入了一个旧的、不相关的团队。在开发测试环境中，建议每次实验都使用新的团队名称，并在实验结束后立即清理。

错误处理

当某个团队成员在执行任务时失败（如遇到无法解决的错误或拒绝执行），团队领导需要及时介入。首先了解失败的原因——是任务描述不清晰、缺少必要的权限还是技术难度过高。然后根据原因采取相应措施：重新描述任务、授予权限、将任务分配给其他成员或拆分为更小的步骤。在极端情况下，可以关闭失败的成员并启动一个新的成员接替其工作。

附：单 Agent 与 Team 模式对比