team-composition-patterns

Team Composition Patterns 是一套关于如何组建多智能体团队的最佳实践指南，面向 Claude Code 的 Agent Teams 功能，覆盖团队规模选择、智能体类型选择以及显示模式配置。

用途与适用时机

当需要决定为某项任务生成多少队友、在预设团队配置之间做选择、为每个角色挑选合适的 agent 类型（subagent_type）、配置队友显示模式（tmux、iTerm2、in-process），或为非标准工作流构建自定义团队组合时，可使用该技能。

团队规模启发式

简单：1-2 个，适用于单维度审查、孤立缺陷、小功能。
中等：2-3 个，适用于多文件改动、2-3 个关注点、中等功能。
复杂：3-4 个，适用于横切关注点、大型功能、深度调试。
非常复杂：4-5 个，适用于全栈功能、全面审查、系统性问题。

经验法则：从能覆盖所有必需维度的最小团队开始。增加队友会提升协调开销。

令牌成本

一个团队的令牌消耗是单个 Claude 的 3-10 倍（计划模式工作流通常约 7 倍）。每个队友在独立上下文窗口中运行并独立消耗令牌。成本驱动因素包括：队友数量（线性）、每个队友的令牌预算（在探索深度上线性）、无监督探索的时长（方差最大来源）。

低成本团队配方：Opus 主导 + Sonnet 队友，2-3 个队友，限定范围的生成提示，对以摘要为主要工作的角色使用 Haiku。成本杀手包括：无边界范围、无文件归属（导致返工）、无任务依赖（在不稳定基础上返工）、无 TaskCompleted 质量门（在破损代码上返工）。

硬性限制（截至 2026-05）

由 harness 强制执行，无法通过提示工程绕过：每个 lead 只能管理一个团队；不允许嵌套团队；不允许嵌套子智能体；lead 在团队生命周期内固定，不可提升或转移领导权；权限在生成时设置，不支持按队友设置；in-process 队友不支持会话恢复（/resume 与 /rewind 不恢复它们）；广播功能已移除，需按名称逐个发送消息。

预设团队组合

Review Team：3 名审查者，优先使用 specialized senior-review:security-auditor + senior-review:code-auditor + 与 diff 匹配的第三个维度；仅在无专用 agent 适配该维度时回退到 agent-teams:team-reviewer。适用于代码改动需要多维度质量评估。
Debug Team：3 名调查者，3x team-debugger，3 个竞争假设。适用于 bug 有多个可能根因。
Feature Team：3 个（1 lead + 2 implementer）。适用于功能可分解为并行工作流。
Fullstack Team：4 个（1 lead + 3 implementer：前端、后端、测试）。适用于跨前后端与测试层的功能。
Research Team：3 名研究者，3x research:deep-researcher（或通用回退），单事实查询用 research:quick-searcher。适用于理解代码库、调研库、比较方案或并行收集信息。
Security Team：4 名审查者，优先 senior-review:security-auditor（OWASP/认证/密钥）、platform-engineering:platform-reviewer（客户端加固）、senior-review:distributed-flow-auditor（跨服务认证流）、codebase-cleanup:deps-audit 或 senior-review:cleanup-auditor（依赖/供应链）。适用于覆盖多攻击面的安全审计。
Migration Team：4 个（1 lead + 2 implementer + 1 reviewer）。适用于需要并行工作并验证正确性的大型代码库迁移。
Deep Search Team：2-4 个（取决于深度级别），2-3x research:deep-researcher + 可选领域专家（自动选择）。适用于需要跨代码库、网络与领域专业知识系统覆盖的复杂问题。
Docs Team：3 个（explorer + writer + verifier）：1x codebase-mapper:codebase-explorer + 1x codebase-mapper:documentation-engineer + 1x senior-review:code-auditor。适用于基于代码分析创建或大改项目文档。
App Analysis Team：3 个（mapper + researcher + designer）：1x app-analyzer:app-analyzer + 1x research:deep-researcher + 1x frontend:frontend-design。适用于竞品应用分析、导航映射、设计系统提取。
Tauri Team：4 个（1 lead + 3 专家）：1x team-lead + 1x tauri-development:rust-engineer + 1x frontend:frontend-engineer + 1x tauri-development:tauri-desktop。适用于构建或优化 Tauri v2 桌面/移动应用。
UI Studio Team：3+3（设计波 + 打磨波，顺序生成）。设计波：1x frontend:frontend-design（方向）+ 1x frontend:frontend-layout（布局）+ 1x frontend:frontend-design（UX）；打磨波：1x frontend:frontend-design（打磨）+ 1x react-development:react-performance-optimizer（性能）+ 1x senior-review:code-auditor（审查）。适用于从零构建新 UI 或重大改版。

智能体类型选择

使用 Agent 工具生成队友时，根据所需工具选择 subagent_type：

general-purpose：全部工具（Read、Write、Edit、Bash 等），用于实现、调试及任何需要修改文件的任务。
Explore：只读工具（Read、Grep、Glob），用于研究、代码探索、分析。
Plan：只读工具，用于架构规划、任务分解。
agent-teams:team-reviewer：Read/Write/搜索/Bash 加上 TaskList/TaskGet/TaskUpdate/SendMessage，用于带结构化发现的代码审查。
agent-teams:team-debugger：同样的工具集，用于假设驱动调查。
agent-teams:team-implementer：Read/Write/Edit/搜索/Bash 加上团队工具，用于在文件归属边界内构建功能。
agent-teams:team-lead：Read/搜索/Bash 加上 Agent Teams 协调工具（Agent、TeamCreate、TeamDelete、TaskCreate/List/Get/Update、SendMessage），用于团队编排与协调。

关键区别：只读 agent（Explore、Plan）不能修改文件，切勿向其分配实现任务。

显示模式配置

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

{
  "teammateMode": "tmux"
}

"tmux"：分屏窗格（自动检测 tmux 或 iTerm2 的 it2 CLI），适用于开发工作流、监控多个 agent。
"in-process"：所有队友在主终端中，Shift+Down 循环切换，适用于简单任务、CI/CD 环境、任何无 tmux 的终端。
"auto"（默认）：若已在 tmux 中则分屏，否则 in-process，适用于大多数用户。

注意："iterm2" 不是独立设置项。分屏模式优先使用 tmux，并自动回退到 iTerm2 的 it2 CLI。VS Code 集成终端、Windows Terminal 和 Ghostty 不支持分屏，始终使用 in-process 模式。

自定义团队准则

每个团队都需要协调者（指定 team-lead 或由用户直接协调）；角色与 agent 类型匹配；避免重复角色；预先定义边界（每个队友需要明确的文件或职责归属）；保持小规模（2-4 个队友是理想区间，5+ 需要显著协调开销）。

故障排查

队友以 Explore 生成但需要写文件：将 subagent_type 改为 general-purpose 或合适的专用 agent 类型。
团队过大导致协调变慢：合并角色，让一个 agent 覆盖两个维度。
tmux 模式不显示窗格：确保 tmux 已安装且会话已运行；in-process 模式无需 tmux。
两名审查者标记相同问题：重新定义各自关注领域（正确性/逻辑、安全、性能/可伸缩性）。
队友未收到任务：确认 lead 使用 Agent 工具生成队友并在提示中传递完整上下文；队友从空白开始，没有先前对话历史。

技能介绍