Claude Code Agent Teams 怎么开与场景
说明如何开启 Claude Code Agent Teams、与 subagent 的差异、共享任务列表用法及官方已知限制。
Claude Code Agent Teams 怎么开：先在 settings.json 或环境里设 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，再用自然语言让 lead 拉起可互发消息的队友；日常聚焦任务仍优先 subagent。
Agent Teams 与 subagent 差在哪
官方文档把两者都标成可并行的手段，分界线在通信拓扑。Subagent 跑在同一会话里，各自有上下文窗口，但结果只回报给主 agent，彼此不能直接对话。Agent Teams 里每个 teammate 是独立 Claude Code 实例，有自己的上下文，还能互相发消息；你也可以不经 lead，直接点进某个队友的 transcript 下指令。
协调方式也不同。Subagent 由主 agent 派活、收结果。Teams 有共享任务列表，队友可以认领未阻塞任务，形成自协调。官方对比表还写明：Teams 的 token 成本更高，因为每个队友都是完整实例；适合需要讨论、对质、多方交叉检查的复杂活。只想快速查资料、跑一次验证、要一份摘要回来，subagent 更合适。嵌套深度与防 runaway 另见 Claude Code 嵌套子代理深度怎么配。
文档还提醒：agent panel 里出现 worker 不等于已经组成团队。Claude 有时会改用 subagent；若你明确要团队，需要再要求一次「agent team」。版本侧，页面标注内容对应 v2.1.178 及之后：开了实验开关后，spawn teammate 不再需要单独的 TeamCreate 步骤；旧的 TeamCreate / TeamDelete 工具已移除，team_name 相关字段在 hook 载荷里也标为废弃。
用环境变量打开实验开关
Agent Teams 默认关闭。未设置开关时，会话开始不会建团队、不会写团队目录，Claude 也不会 spawn 或提议队友。开启方式是把 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 设为 1，可写在 shell 环境，也可放进用户或项目的 settings.json：
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
打开后再用自然语言描述任务和想要的队友角色即可。官方示例是设计一个扫描 TODO 的 CLI：分别拉 UX、技术架构、唱反调三个视角。Lead 会填充共享任务列表、spawn 队友、汇总结论。显示模式默认 in-process（同一终端的 agent panel）；若要分屏，需在 ~/.claude/settings.json 设 teammateMode，或会话级传 --teammate-mode（该 flag 标为实验性，且不一定出现在 claude --help）。分屏依赖 tmux，或带 it2 CLI 的 iTerm2；VS Code 内置终端、Windows Terminal、Ghostty 不支持 split panes。
国内网络下 CLI 升级与文档同步有时滞后，若本地版本号低于文档提到的行为变更点（例如 idle 行隐藏策略、mailbox 校验），界面表现可能不一致，需要自行验证当前安装版本的 changelog。
Lead 与 teammate 怎么分工
团队形成于第一个 teammate 被 spawn 时，主会话固定为 lead，生命周期内不能把领导权转给队友，也不能嵌套再开子团队。Lead 负责拆任务、指派或催进度、综合结果；队友各自执行，idle 时会通知 lead。你可以用自然语言要求「等队友做完再继续」，避免 lead 抢活自己实现。
队友不继承 lead 的对话历史，但会加载项目级上下文（如 CLAUDE.md、MCP、skills），并收到 spawn 时的提示词。模型方面，队友默认不继承 lead 的 /model 选择；可在 /config 里设 Default teammate model，或在 spawn 指令里写明用 Sonnet 等。Effort 级别会继承；分屏模式下从 v2.1.186 起才稳定传递。权限初始与 lead 相同：lead 若带 --dangerously-skip-permissions，队友一并继承。Spawn 时不能按人设不同权限模式，spawn 后再改单个队友可以。权限弹窗出现在 lead 会话，需你在 lead 侧批准；队友之间用 SendMessage 互发的「已批准」声明，在 auto mode 下会被当成不可信输入。
需要更稳的角色复用时，可按 subagent 定义名 spawn，例如「用 security-reviewer 类型拉一个队友审 auth」。该定义的 tools allowlist 与 model 会生效，正文追加进队友 system prompt；但文档写明：作为 teammate 时，定义里的 skills 与 mcpServers frontmatter 不会应用，队友仍从项目/用户设置加载 skills 与 MCP。跨模型并行派工的另一种套路见 Claude Code 委托 Codex/Gemini 并行。
共享任务列表怎么跑起来
任务有 pending、in progress、completed 三态，还可声明依赖：依赖未完成时不能认领。Lead 可显式指派，也可让队友做完后自己认领下一个未阻塞任务；认领用文件锁避免抢同一条。任务目录落在本地 ~/.claude/tasks/{team-name}/，团队名由会话派生为 session- 加 session ID 前八位。会话结束会清掉 ~/.claude/teams/{team-name}/ 配置目录，任务列表目录会保留，供后续 resume 场景对照，且不会上传。
邮箱是队友互聊的通道：每个 agent 的 mailbox 是 ~/.claude/teams/{team-name}/inboxes/{agent-name}.json。读邮箱时会校验格式，非法条目报错并剔除，合法消息照常投递。文档建议给队友起可引用的名字，方便你后来说「让 researcher 关掉」。优雅关闭时向指定队友发 shutdown 请求，对方可同意退出或拒绝并说明原因。质量闸门可用 hooks：TeammateIdle、TaskCreated、TaskCompleted 在退出码 2 时可驳回并回馈，适合卡住「假完成」或不合格收工。
若你更习惯把计划写进文件再驱动执行，可对照 用文件做 Agent 规划：Teams 的共享任务列表解决的是运行时认领，文件规划解决的是跨会话意图沉淀，两者可叠加但不要混成一套配置。
官方写明的已知限制
文档 Limitations 节是决策前必读，摘几条影响最大的。/resume 与 /rewind 不会恢复 in-process 队友；恢复后 lead 可能仍试图给已不存在的队友发消息，此时应让它重新 spawn。任务状态可能滞后：队友做完却没标 completed，会堵住依赖任务，需要你核对实物进度后手动改状态或让 lead 催一下。关闭可能偏慢，因为队友要先结束当前请求或工具调用。
结构约束同样硬：每个会话只有一个团队，不能跨会话共享；队友不能再 spawn 队友；in-process 队友自己的 subagent 只能前台跑，请求后台 subagent 会报错。Lead 固定；权限模式不能在 spawn 瞬间按人定制。分屏依赖 tmux/iTerm2，前面已述。另外，任务协调与关停行为仍标为实验特性整体的一部分，升级小版本时细节会变，读文档时留意页面标注的版本号。
什么任务值得开团队
官方点名的强场景是：并行调研与审查、新人接手的独立模块/功能、带竞争假说的排障、跨前后端与测试的分层改动。共同前提是队友能相对独立推进；串行步骤多、同文件抢改、依赖链很长时，单会话或 subagent 更有效。Token 随队友数量近似线性上涨，文档建议多数工作流从 3–5 个队友起步，并给每人大约 5–6 条体量适中的任务，避免过碎（协调成本吃掉收益）或过大（长时间无检查点）。
实操上可先用「只读」类任务练手：PR 分视角审查、库选型调研、多假说对质。实现类任务务必按文件所有权切开，避免两人改同一文件互相覆盖。Lead 开始自己写代码时，明确要求它等待队友。若只是要几个聚焦工人回报结果，继续用 subagent，不必为了「看起来像团队」去开实验开关。