agents 中 Agent Teams 的团队组成模式：团队规模启发式、预置团队、代理类型选择与展示模式配置

本文围绕 agents 仓库 agent-teams 插件中的 team-composition-patterns 技能，系统讲解如何为 Claude Code Agent Teams 功能设计最优的多代理团队：从"这个任务该派几个人"的规模启发式，到 7 种预置团队（评审、调试、特性、全栈、研究、安全、迁移）的成员配置，再到 subagent_type 选择矩阵与展示模式配置。读完后你应能独立为一个具体任务选定团队规模、代理类型组合与显示方式，并按规范完成自定义团队搭建与常见故障排查。

适用场景：什么时候需要团队组成决策

该技能（SKILL.md）面向以下五类决策场景：

• 决定为一个任务生成（spawn）多少个队友（teammate）；
• 在预置团队配置之间做选择（review / debug / feature / fullstack / research / security / migration）；
• 为每个角色挑选正确的代理类型（subagent_type），确保每个代理拥有其职责所需的工具；
• 配置队友展示模式（tmux、iTerm2、in-process），适配 CI 或本地开发环境；
• 为迁移、安全审计等非标准工作流构建自定义团队组成。

技能描述中明确其触发条件也包括：当你在纠结"派几个代理、评审团队还是特性团队还是调试团队、每个角色该用什么 subagent_type"这类问题时，即应使用本技能。

团队规模启发式（Team Sizing Heuristics）

技能给出了一张"复杂度 → 团队规模"的映射表，这是所有组成决策的起点：

复杂度	团队规模	适用场景
Simple（简单）	1-2	单维度评审、孤立 bug、小特性
Moderate（中等）	2-3	多文件改动、2-3 个关注点、中型特性
Complex（复杂）	3-4	跨切面关注点、大特性、深度调试
Very Complex（极复杂）	4-5	全栈特性、全面评审、系统性问题

经验法则（Rule of thumb）：从能覆盖所有必需维度的最小团队开始。每多一个队友都会增加协调开销（coordination overhead）——这一点在 team-lead 代理定义的行为特质中也被强化为"maintains a bias toward smaller teams with clearer ownership"（偏向更小、归属更清晰的团队）。

七种预置团队组成

技能正文给出了 7 种预置团队的规模与成员构成，插件的 preset-teams.md 参考文档进一步提供了每种预置的成员命名表、任务模板（Task Template）与变体参数。以下逐一展开。

Review 评审团队

• 规模：3 名评审员
• 代理：3x team-reviewer
• 默认维度：security（安全）、performance（性能）、architecture（架构）
• 使用时机：代码变更需要多维度质量评估
• 对应命令：/team-spawn review

成员与关注点分配（见 preset-teams.md）：

成员名	维度	关注点
security-reviewer	Security	输入校验、认证、注入、密钥、CVE
performance-reviewer	Performance	查询效率、内存、缓存、异步模式
architecture-reviewer	Architecture	SOLID、耦合度、设计模式、错误处理

任务模板要求输出结构化发现：file:line、severity、evidence、fix。常见变体：安全聚焦 --reviewers security,testing（2 人）、全面评审 --reviewers security,performance,architecture,testing,accessibility（5 人）、前端评审 --reviewers architecture,testing,accessibility（3 人）。

从源码结构看，team-reviewer 代理定义声明了 tools: Read, Glob, Grep, Bash, TaskList, TaskGet, TaskUpdate, SendMessage，且内置了 Security / Performance / Architecture / Testing / Accessibility 五个维度的完整检查清单——这意味着评审员被刻意设计为"只读 + 团队协作工具"，不能修改文件，从而从工具层面杜绝了评审越权改动代码。

Debug 调试团队

• 规模：3 名调查员
• 代理：3x team-debugger
• 默认假设：3 个相互竞争（competing）的根因假设
• 使用时机：bug 存在多个 plausible 的根因
• 对应命令：/team-spawn debug，可用 --hypotheses N 调整假设数量

每个调查员只负责验证一个假设。team-debugger 代理定义规定了七步调查协议：理解假设 → 定义证实/证伪/模糊的证据标准 → 收集一手证据 → 收集旁证 → 测试假设 → 评估置信度（High >80% / Medium 50-80% / Low <50%）→ 报告结论。其"证据标准"要求所有论断必须附 file:line 引用，并且要如实报告削弱假设的反面证据、将"证伪的假设"也视为有价值的发现——这正是"竞争假设"模式能收敛出真根因的机制。

任务模板（来自 preset-teams.md）：

Subject: Investigate hypothesis: {hypothesis summary}
Description:
  Hypothesis: {full hypothesis statement}
  Scope: {files/module/project}
  Evidence criteria:
    Confirming: {what would confirm}
    Falsifying: {what would falsify}
  Report format: confidence level, evidence with file:line, causal chain

Feature 特性团队

• 规模：3（1 名 lead + 2 名 implementer）
• 代理：1x team-lead + 2x team-implementer
• 使用时机：特性可以分解为并行工作流
• 对应命令：/team-spawn feature

成员名	角色	职责
feature-lead	team-lead	分解、协调、集成
implementer-1	team-implementer	工作流 1（分配的文件）
implementer-2	team-implementer	工作流 2（分配的文件）

任务模板要求明确"Owned files（拥有的文件清单）、Requirements、Interface contract（共享类型/API）、Acceptance criteria、Blocked by（依赖任务 ID）"。

Fullstack 全栈团队

• 规模：4（1 名 lead + 3 名 implementer）
• 代理：1x team-lead + 1x 前端 team-implementer + 1x 后端 team-implementer + 1x 测试 team-implementer
• 使用时机：特性横跨前端、后端与测试层
• 对应命令：/team-spawn fullstack

成员名	角色	层
fullstack-lead	team-lead	协调、集成
frontend-dev	team-implementer	UI 组件、客户端逻辑
backend-dev	team-implementer	API 端点、业务逻辑
test-dev	team-implementer	单元、集成、e2e 测试

其依赖模式为：frontend-dev 与 backend-dev 并行，test-dev 被两者共同阻塞（blocked by both）——体现了"先并行实现、后汇聚测试"的依赖图设计。

Research 研究团队

• 规模：3 名研究员
• 代理：3x general-purpose
• 默认分工：每人分配不同的研究问题、模块或主题
• 能力：代码库搜索（Grep、Glob、Read）+ 网络搜索（WebSearch、WebFetch）
• 使用时机：需要并行地理解代码库、研究库、对比方案，或同时从代码与网络来源收集信息
• 对应命令：/team-spawn research

preset-teams.md给出的研究团队示例分工很有代表性：

Researcher 1 (codebase): "How does our current auth system work? Trace the flow from login to token validation."
Researcher 2 (web): "Search for comparisons between NextAuth, Clerk, and Auth0 for Next.js apps. Focus on pricing, DX, and migration effort."
Researcher 3 (docs): "Look up the latest NextAuth.js v5 API docs. How does it handle JWT and session management?"

变体包括：仅代码库（3 人探索不同模块）、纯网络调研、以及推荐的"混合式"（1 代码库 + 1 文档 + 1 网络）。

Security 安全团队

• 规模：4 名评审员
• 代理：4x team-reviewer
• 默认维度：OWASP/漏洞、认证/访问控制、依赖/供应链、密钥/配置
• 使用时机：覆盖多个攻击面的综合安全审计
• 对应命令：/team-spawn security

成员名	维度	关注点
vuln-reviewer	OWASP/Vulns	注入、XSS、CSRF、反序列化、SSRF
auth-reviewer	Auth/Access	认证、授权、会话管理
deps-reviewer	Dependencies	CVE、供应链、过期包、许可证风险
config-reviewer	Secrets/Config	硬编码密钥、环境变量、调试端点、CORS

任务模板要求输出 file:line、类 CVSS 严重度、证据与修复建议，并对照 OWASP Top 10 与 CWE。变体：快速扫描 --reviewers owasp,secrets（2 人）、默认全量 4 维度、CI/CD 聚焦（增加第 5 名评审员覆盖流水线与部署配置）。

Migration 迁移团队

• 规模：4（1 名 lead + 2 名 implementer + 1 名 reviewer）
• 代理：1x team-lead + 2x team-implementer + 1x team-reviewer
• 使用时机：需要并行推进且要正确性验证的大型代码库迁移（框架升级、语言移植、API 版本升级）
• 对应命令：/team-spawn migration

依赖模式为：migration-lead（制定计划）→ migrator-1 / migrator-2（并行迁移流）→ migration-verify（验证迁移正确性与模式一致性）。典型用例包括：框架升级（React class → hooks、Vue 2 → Vue 3）、语言迁移（JavaScript → TypeScript、Python 2 → 3）、API 版本升级、数据库/ORM 变更、构建系统更换（Webpack → Vite）。

代理类型选择（Agent Type Selection）

生成队友时使用 Agent 工具，需根据"队友需要什么工具"来选择 subagent_type。技能正文的类型对照表如下：

代理类型	可用工具	适用用途
general-purpose	全部工具（Read、Write、Edit、Bash 等）	实现、调试、任何需要改文件的任务
Explore	只读工具（Read、Grep、Glob）	研究、代码探索、分析
Plan	只读工具	架构规划、任务分解
agent-teams:team-reviewer	读/搜索/Bash + TaskList/TaskGet/TaskUpdate/SendMessage	带结构化发现的代码评审
agent-teams:team-debugger	读/搜索/Bash + TaskList/TaskGet/TaskUpdate/SendMessage	假设驱动的调查
agent-teams:team-implementer	读/写/编辑/搜索/Bash + TaskList/TaskGet/TaskUpdate/SendMessage	在文件归属边界内构建特性
agent-teams:team-lead	读/搜索/Bash + Agent Teams 协调工具	团队编排与协调

关键区分：只读代理（Explore、Plan）不能修改文件。绝不把实现类任务分配给只读代理。

插件参考文档 agent-type-selection.md 提供了决策矩阵与更细粒度的能力对照表：

Does the teammate need a specialized Agent Teams role?
├── YES → Which role?
│         ├── Team coordination → agent-teams:team-lead
│         ├── Feature building → agent-teams:team-implementer
│         ├── Code review → agent-teams:team-reviewer
│         └── Bug investigation → agent-teams:team-debugger
└── NO → Does it need to modify files?
          ├── YES → general-purpose
          └── NO → Does it need deep codebase exploration?
                    ├── YES → Explore
                    └── NO → Plan (for architecture/design tasks)

能力对照（Can Read / Can Write / Can Edit / Can Bash / Team Tools）：

代理类型	可读	可写	可编辑	可 Bash	团队工具	特化用途
general-purpose	Yes	Yes	Yes	Yes	No	通用
Explore	Yes	No	No	No	No	搜索/探索
Plan	Yes	No	No	No	No	架构
agent-teams:team-lead	Yes	No	No	Yes	Yes	团队编排
agent-teams:team-reviewer	Yes	No	No	Yes	Yes	代码评审
agent-teams:team-debugger	Yes	No	No	Yes	Yes	bug 调查
agent-teams:team-implementer	Yes	Yes	Yes	Yes	Yes	特性构建

常见选型错误及纠正：

错误	失败原因	正确选择
用 Explore 做实现	不能写/编辑文件	general-purpose 或 team-implementer
用 Plan 做编码任务	不能写/编辑文件	general-purpose 或 team-implementer
用 general-purpose 做评审	没有评审结构/检查清单	team-reviewer
用 team-implementer 做研究	有工具但聚焦点不对	Explore 或 Plan

从源码结构看，四个专用代理的定义文件印证了"工具即权限边界"的设计：team-implementer 是唯一在专用代理中拥有 Write、Edit 工具的；team-lead 额外持有 Agent、TeamCreate、TeamDelete、TaskCreate 等协调工具并负责"Spawn → Assign → Monitor → Collect → Synthesize → Shutdown → Cleanup"的完整团队生命周期；而 team-reviewer 与 team-debugger 均只有只读工具加团队消息工具，与能力对照表完全一致。此外，各代理定义文件的 front matter 还声明了 model（team-lead 为 fable，其余三个为 opus）与 color（蓝/绿/红/黄）字段，用于在 tmux 等多窗格环境中区分队友。

展示模式配置（Display Mode）

在 ~/.claude/settings.json 中配置 teammateMode：

{
  "teammateMode": "tmux"
}

模式	行为	最适合
"tmux"	每个队友一个 tmux 窗格	开发工作流、监控多个代理
"iterm2"	每个队友一个 iTerm2 标签页	偏好 iTerm2 的 macOS 用户
"in-process"	所有队友在同一进程中	简单任务、CI/CD 环境

agent-teams 插件 README 补充了两点适用前提：iTerm2 模式仅适用于 macOS；in-process 是默认模式，且在没有 tmux 的 CI 或脚本化环境中是唯一可靠选择。各预置团队在参考文档中均标注"Display Mode: tmux recommended"，即推荐开发场景使用 tmux 以便实时观察多个队友的并行输出。

自定义团队的五条准则

为迁移、安全审计等非标准工作流构建自定义团队时，技能给出五条准则：

1. 每个团队都需要协调者 — 指定一个 team-lead，或由用户直接协调；
2. 角色与代理类型匹配 — 有专用代理（reviewer、debugger、implementer）时优先使用；
3. 避免重复角色 — 两个代理做同一件事是资源浪费；
4. 预先定义边界 — 每个队友需要明确的文件或职责归属；
5. 保持小规模 — 2-4 个队友是最佳区间；5 个以上会引入显著的协调开销。

这些准则在 team-lead 代理定义中有更细的执行规则可对照：每文件唯一属主、任务描述中显式列出归属文件、跨属主边界先定义接口契约、共享文件由 lead 统一顺序修改。

实操串联：从 /team-spawn 到团队落地

上述组成决策最终通过 /team-spawn 命令落地。该命令的完整流程（见 team-spawn.md）可验证本文各节内容如何被实际消费：

1. Pre-flight 检查：确认环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 已设置，否则停止执行——这是 Agent Teams 功能作为实验特性（experimental feature flag）的硬性前提；
2. 参数解析：第一个位置参数为预置名（review/debug/feature/fullstack/research/security/migration）或 custom；--name 指定团队名；--members N 覆盖默认成员数；--delegate 在生成后进入委派模式；
3. 团队创建：先用 TeamCreate 工具以 team_name 与 description 建队，再对每个成员调用 Agent 工具，传入 team_name、唯一且描述性的 name（如 fullstack-lead、security-reviewer）、subagent_type（如 agent-teams:team-reviewer 或研究用途的 general-purpose）以及包含角色指令的 prompt；
4. 注意事项：不要使用 team-lead 这类角色名作为生成成员名（可能被团队创建过程保留），应使用唯一成员名，并以 Agent 返回或 ~/.claude/teams/{team-name}/config.json 中记录的实际名字称呼队友；
5. 初始设置：用 TaskCreate 为每个队友创建占位任务，并展示团队摘要（团队名、成员与角色、展示模式）。

典型调用示例（来自 agent-teams README 的 Quick Start）：

/team-spawn review
/team-spawn debug "API returns 500 on POST /users with valid payload" --hypotheses 3
/team-spawn feature "Add user authentication with OAuth2" --team-size 3 --plan-first
/team-spawn research --name codebase-research
/team-spawn security
/team-spawn migration --name react-hooks-migration
/team-spawn custom --name my-team --members 4

生成后可用 /team-status 监控进度、/team-delegate 分派任务并做负载均衡（--rebalance）、/team-shutdown 优雅关闭并清理资源。

故障排查（Troubleshooting）

技能正文列出五个高频问题及其处置方式，均可从上文组成原则中找到成因：

队友被生成为 Explore 但需要写文件。 Explore 与 Plan 是只读代理。把 subagent_type 改为 general-purpose 或合适的专用类型。绝不把实现任务分配给只读代理。

团队规模膨胀、协调拖慢一切。 每个新增队友都增加通信开销。应合并角色：能否让一个代理覆盖两个维度？一个 4 人团队做 6 个独立任务，通常不如 3 个代理各覆盖 2 个任务。

tmux 模式看不到窗格。 确保 tmux 已安装且已有运行中的会话再生成队友。in-process 模式不依赖 tmux，适合 CI 或脚本化环境。

两个评审员在标记相同的问题。 评审维度重叠了。重新划分每个评审员的聚焦域：一个看正确性/逻辑、一个看安全、一个看性能/可扩展性。重叠覆盖浪费 token 并产生重复发现。

team-lead 生成了队友，但队友没有收到任务。 确认 lead 是通过 Agent 工具生成队友并在 prompt 中传入了完整上下文。队友以全新的会话启动，没有任何历史对话——它们需要全部相关信息都包含在初始 prompt 中。

小结与相关技能

team-composition-patterns 技能回答了多代理编排中的第一个核心问题："团队该由谁组成"。组成确定之后，仓库中还有两个直接衔接的技能可继续使用：

• parallel-feature-development — 团队组成确定后，如何分解工作流并一次性分配文件归属；
• team-communication-protocols — 为已组建团队建立消息规范与关闭（shutdown）流程。

配合 task-coordination-strategies、multi-reviewer-patterns、parallel-debugging 等技能，agent-teams 插件构成了一套"组队 → 分派 → 监控 → 收尾"的完整多代理工作流，本文所述的规模启发式、预置组成、类型选择矩阵与展示模式配置即为这套工作流的组队起点。