Claude Code 的 Agent Teams 功能是一个强大的多代理协作系统能够协调多个 Claude Code 实例并行工作。这个实验性功能特别适合需要多角度分析、并行探索的复杂任务场景。1. 核心能力速览能力项说明项目类型Claude Code 多代理协作系统开源团队Anthropic 开发的 Claude 开发者平台主要功能多代理并行工作、任务分配、团队协作推荐硬件标准开发环境无特殊硬件要求显存占用每个队友独立占用需按实际模型版本测试支持平台macOS、Linux、Windows部分功能限制启动方式命令行启动环境变量配置API 支持通过命令行和配置文件进行控制批量任务支持共享任务列表和批量处理适合场景代码审查、问题调查、多模块开发2. 适用场景与使用边界Agent Teams 最适合需要并行探索且能增加真实价值的任务场景。最强的应用场景包括研究和审查工作多个队友可以同时调查问题的不同方面并分享发现新模块或功能开发时队友可以各自负责独立部分而不会相互干扰使用竞争假设进行调试时队友能并行测试不同理论以快速收敛到答案跨层协调任务中可以分配不同队友负责前端、后端和测试等不同层面。需要注意的是Agent Teams 会增加协调开销使用的令牌数量明显多于单个会话。当队友可以独立运作时效果最好而对于顺序任务、同一文件编辑或有许多依赖关系的工作单个会话或 subagents 可能更有效。该功能目前仍处于实验性阶段存在一些已知限制如会话恢复、任务协调和关闭行为等方面的问题。3. 环境准备与前置条件在使用 Agent Teams 功能前需要确保开发环境满足基本要求。操作系统方面macOS 和 Linux 提供最完整的支持Windows 系统在使用分割窗格模式时可能存在限制。需要安装最新版本的 Claude Code建议使用 v2.1.178 或更高版本以获得完整功能支持。对于显示模式的选择如果计划使用分割窗格模式需要提前安装相关依赖。tmux 是跨平台的选择可以通过系统包管理器安装如果使用 macOS 且偏好 iTerm2需要安装 it2 CLI 并在 iTerm2 设置中启用 Python API。基础内存建议 8GB 以上磁盘空间需要预留足够的空间用于存储团队配置和任务列表。端口占用方面Claude Code 默认使用标准终端会话不需要额外端口配置。但需要注意 tmux 会话的管理避免出现孤立的会话进程。权限设置也需要提前规划因为队友的权限请求会冒泡到负责人会话预批准常见操作可以减少中断。4. 安装部署与启动方式Agent Teams 功能默认是禁用的需要通过环境变量显式启用。配置方式有两种通过环境变量设置或通过 settings.json 配置文件设置。环境变量配置方式# 临时启用当前会话有效 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS1 # 永久启用添加到 shell 配置文件 echo export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS1 ~/.bashrc # 或对于 zsh 用户 echo export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS1 ~/.zshrc配置文件设置方式在~/.claude/settings.json中添加以下配置{ env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 } }显示模式配置Agent Teams 支持两种显示模式可以根据需要配置{ teammateMode: auto }或者通过命令行参数指定claude --teammate-mode auto可用的显示模式选项包括in-process所有队友在主终端内运行默认auto自动检测终端环境选择最佳模式tmux强制使用 tmux 分割窗格iterm2强制使用 iTerm2 原生分割窗格5. 功能测试与效果验证5.1 基础团队创建测试启动第一个 Agent Team 的测试流程相对简单。启用功能后直接用自然语言描述任务和需要的队友即可。一个有效的测试示例如下Im designing a CLI tool that helps developers track TODO comments across their codebase. Spawn three teammates to explore this from different angles: one on UX, one on technical architecture, one playing devils advocate.这个示例效果很好的原因是三个角色相互独立可以在不相互等待的情况下探索问题。Claude 会根据提示自动填充共享任务列表为每个角度生成队友让他们并行探索问题并在完成后综合发现。5.2 显示模式验证In-process 模式测试启动后在负责人的终端提示输入下方会出现 agent 面板列出所有队友。使用上下箭头键可以选择队友按 Enter 键打开所选队友的记录并直接发送消息按 Escape 键中断当前轮次。从 v2.1.199 开始当任何队友或子 agent 仍在工作时空闲队友的行会保留在面板中。分割窗格模式测试如果配置了分割窗格模式每个队友会获得独立的窗格。可以同时看到每个人的输出并点击窗格直接交互。需要验证 tmux 或 iTerm2 是否正确安装和配置。5.3 任务分配与协调测试测试任务分配功能时可以观察共享任务列表的工作机制。任务有三种状态待处理、进行中和已完成。测试依赖关系管理创建具有依赖关系的任务验证系统是否能正确阻止依赖任务在被依赖任务完成前被认领。任务认领机制测试包括负责人显式分配和队友自我认领两种方式。可以观察文件锁定机制如何防止多个队友同时认领同一任务时的竞态条件。6. 接口 API 与批量任务6.1 团队配置管理Agent Teams 的配置和任务数据存储在本地文件系统中。团队配置路径为~/.claude/teams/{team-name}/config.json任务列表路径为~/.claude/tasks/{team-name}/。团队名称由会话派生格式为 session- 加上会话 ID 的前八个字符。团队配置包含 members 数组记录每个队友的名称、代理 ID 和代理类型。队友可以读取这个文件来发现其他团队成员。需要注意的是团队配置保存的是运行时状态不应手动编辑因为更改会在下一次状态更新时被覆盖。6.2 Subagent 定义集成Agent Teams 支持与 subagent 定义集成这允许定义可重用的队友角色。使用方法是在要求 Claude 生成队友时按名称引用已有的 subagent 类型Spawn a teammate using the security-reviewer agent type to audit the auth module.队友会遵守该定义的 tools 允许列表和 model 设置定义的主体会被附加到队友的系统提示作为额外指示。Team coordination tools 如 SendMessage 和任务管理工具始终对队友可用即使 tools 限制其他工具。6.3 Hooks 机制用于质量控制Agent Teams 提供了 hooks 机制来强制执行质量规则# TeammateIdle队友空闲时运行以代码2退出可发送反馈保持队友工作 # TaskCreated任务创建时运行以代码2退出可阻止创建并发送反馈 # TaskCompleted任务完成时运行以代码2退出可阻止完成并发送反馈这些 hooks 可以用于实现自动化的质量门控确保团队工作符合预定标准。7. 资源占用与性能观察7.1 令牌使用分析Agent Teams 的令牌使用量明显高于单个会话因为每个队友都有自己的 context window令牌消耗随活跃队友数量线性增加。对于研究、审查和新功能工作额外的令牌成本通常是值得的但对于日常任务单个会话可能更具成本效益。性能观察要点包括监控每个队友的上下文窗口使用情况避免不必要的令牌浪费。建议根据任务复杂度合理选择团队规模3-5 个队友通常能平衡并行工作和协调开销。7.2 内存和进程管理每个队友作为独立的 Claude Code 实例运行会占用相应的系统资源。需要监控整体内存使用情况特别是在运行多个复杂任务时。In-process 模式相对节省资源而分割窗格模式会创建额外的终端进程。团队会话结束时系统会自动清理共享目录但需要留意可能出现的孤立 tmux 会话。定期检查并清理不再需要的会话可以保持系统整洁。8. 常见问题与排查方法问题现象可能原因排查方式解决方案队友未出现功能未启用或任务复杂度不足检查环境变量设置确保 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS1分割窗格失败tmux 或 it2 CLI 未安装验证 which tmux 或 it2 命令安装缺失的依赖权限提示过多队友权限请求冒泡到负责人检查权限设置预批准常见操作队友停止工作遇到错误后未恢复查看队友输出直接发送指令或生成替代队友任务状态滞后队友未正确标记任务完成检查任务实际完成情况手动更新任务状态tmux 会话残留会话未完全清理执行 tmux ls使用 tmux kill-session 清理8.1 显示模式相关问题分割窗格模式在某些环境下可能遇到兼容性问题。VS Code 的集成终端、Windows Terminal 或 Ghostty 不支持分割窗格模式。如果遇到显示问题可以回退到 in-process 模式进行测试。8.2 会话恢复限制In-process 队友不支持会话恢复/resume 和 /rewind 命令不会恢复 in-process 队友。恢复会话后负责人可能会尝试向不再存在的队友发送消息。如果发生这种情况需要告诉负责人生成新的队友。9. 最佳实践与使用建议9.1 团队规模与任务分配对于大多数工作流建议从 3-5 个队友开始这个规模能较好地平衡并行工作和协调管理。每个队友分配 5-6 个任务可以保持生产力而不会导致过度的上下文切换。如果工作包含 15 个独立任务3 个队友是一个合理的起点。任务大小需要适当调整太小的任务会导致协调开销超过收益太大的任务则可能让队友长时间工作而不进行检查增加浪费努力的风险。理想的任务应该是自包含的单位能产生清晰的可交付成果如函数、测试文件或审查报告。9.2 上下文管理与通信给队友提供足够的上下文信息至关重要。虽然队友会自动加载项目上下文包括 CLAUDE.md、MCP servers 和 skills但他们不继承负责人的对话历史。在生成提示中应包含特定于任务的详细信息明确每个队友的职责范围和关注点。通信方面可以利用自动消息传递机制队友发送的消息会自动传递给收件人负责人不需要轮询更新。共享任务列表让所有代理都能看到任务状态并认领可用工作。按名称向特定队友发送消息可以实现精准沟通。9.3 监控与指导策略即使配置了自动化团队协作仍然需要适当的监控和指导。定期检查队友的进度及时重定向不起作用的方法在发现重要信息时进行综合总结。让团队完全无人值守运行太长时间会增加浪费努力的风险。对于复杂或有风险的任务可以要求队友在实施前进行规划批准。队友会在只读计划模式下工作直到负责人批准他们的方法。这为关键任务提供了额外的质量保证层。10. 实际应用案例深度分析10.1 并行代码审查实战并行代码审查是 Agent Teams 的典型应用场景。传统的单个审查者往往一次只关注一种类型的问题而使用 Agent Teams 可以将审查标准分解为独立的领域。例如可以同时生成三个队友分别关注安全影响、性能影响和测试覆盖率的审查。提示词示例Spawn three teammates to review PR #142: - One focused on security implications - One checking performance impact - One validating test coverage Have them each review and report findings.每个审查者从同一个 PR 工作但应用不同的专业过滤器。负责人在所有审查完成后综合三个角度的发现形成全面的审查报告。这种方法相比顺序审查能显著提高效率且避免了单一视角的局限性。10.2 竞争假设调查模式当系统问题的根本原因不明确时单个代理往往找到一个看似合理的解释后就停止深入调查。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 others theories, like a scientific debate. Update the findings doc with whatever consensus emerges.这种辩论结构是关键机制能克服顺序调查中的锚定效应。有多个独立的调查者积极尝试相互反驳时最终存活下来的理论更有可能是实际的根本原因。这种方法在复杂系统调试中特别有效。10.3 跨层协调开发对于涉及多个技术层面的功能开发Agent Teams 能有效协调不同专业背景的队友并行工作。例如一个涉及前端界面、后端逻辑和测试验证的功能需求可以分配不同的队友负责相应层面。这种模式下每个队友专注于自己擅长的领域通过共享任务列表和消息系统保持同步。负责人负责整体的进度协调和最终的结果整合确保各个部分能无缝衔接。这种方法特别适合中等复杂度的全栈功能开发Agent Teams 功能为复杂开发任务提供了强大的并行处理能力通过合理的团队配置和任务管理可以显著提高开发效率和质量。虽然目前仍处于实验阶段但其展现出的协作模式为未来的 AI 辅助开发指明了有前景的方向。