Claude Code Agent Teams：多智能体协同团队完全指南

本页目录12

要点速览

Agent Teams 目前为实验性功能，须在 settings.json 中设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 才能启用
与 Subagents 的核心区别在于：队友之间可直接互发消息，并通过共享任务列表自主认领工作，而非只向主智能体汇报
显示模式分为 in-process（默认，任何终端可用）和 split-panes（需要 tmux 或 iTerm2），可通过 teammateMode 配置
建议从 3～5 人团队起步，每人分配 5～6 个任务；团队过大会导致协调开销超过并行收益
队友继承 Team Lead 的权限设置，但不继承其对话历史，关键背景须在 spawn 提示词中显式说明
当前已知限制：不支持 /resume 恢复队友、任务状态可能滞后、不支持嵌套团队、分屏模式不兼容 VS Code 集成终端

本文是对官方文档《Orchestrate teams of Claude Code sessions》的中文要点摘要，完整内容以原文为准：https://code.claude.com/docs/en/agent-teams

什么是 Agent Teams

Agent Teams 让多个 Claude Code 实例协同工作。其中一个会话担任团队负责人（Team Lead），负责创建任务、分配工作、汇总结果；其余会话作为队友（Teammate），各自拥有独立的上下文窗口，并可相互直接通信。

注意：该功能目前为实验性，默认关闭。需在 settings.json 的 env 字段中启用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS，或在 shell 中设置同名环境变量为 1。

选择原则：队友之间无需互相沟通时选 Subagents；任务需要跨角色讨论和验证时选 Agent Teams。

启用后，用自然语言描述任务和期望角色即可，无需额外建团命令（v2.1.178 起已移除旧版 TeamCreate / TeamDelete 工具）：

I'm designing a CLI tool. Spawn three teammates:
one on UX, one on technical architecture, one playing devil's advocate.

Claude 会自动填充共享任务列表、生成队友并在完成后汇总结果。Lead 终端底部的智能体面板显示所有队友状态，可用上下方向键选择、Enter 进入查看并直接发消息、Escape 中断其当前执行。

通过 teammateMode（写入 ~/.claude/settings.json）或启动时 --teammate-mode 标志设置：

in-process（默认）：所有队友在主终端内运行，方向键导航，适用于任何终端
auto：已在 tmux 会话中或使用 iTerm2 时自动开启分屏，否则降级为 in-process
tmux：强制分屏，自动判断使用 tmux 还是 iTerm2
iterm2（v2.1.186 起）：使用 iTerm2 原生分屏，需安装 it2 CLI 并在 iTerm2 偏好设置中启用 Python API

可要求队友先提交实施方案，Lead 审批通过后再执行变更：

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

Lead 可在 prompt 中设置审批标准，例如「只批准包含测试覆盖的方案」或「拒绝涉及数据库 schema 变更的方案」。

可在 spawn 时引用已定义的 subagent 类型（涵盖任一 subagent 作用域：项目级、用户级、插件级、CLI 定义级），队友将继承其 tools 白名单和 model 配置，系统提示词以附加方式合并而非替换。