Claude Code Agent 团队

编排多个 Claude Code Agent 协同处理复杂任务。各 Agent 通过共享任务列表协调工作，可直接相互通信，并在各自独立的作用域内并行执行。

适用场景

✅ 适用于并行且相互独立的工作：

• 多维度代码审查（安全、性能、测试并行开展）
• 基于竞争性假设的调试（同时验证多种理论）
• 全栈功能开发（前端、后端、测试由不同专家分工完成）
• 架构决策（通过对抗式辩论产出更严谨的 ADR）
• 跨领域问题排查（跨系统进行性能瓶颈分析）
• 数据并行任务（资产分类、批量重构）

❌ 不适用于以下情况：

• 具有强依赖关系的串行任务
• 同一文件的编辑（存在冲突风险）
• 简单任务（协调开销大于并行收益）
• 学习或探索类任务（单个具备完整上下文的 Agent 效果更佳）

经验法则：使用团队模式会使 token 成本增加 3–4 倍。仅当并行化带来的收益显著超过协调开销时，才应启用该模式。

快速开始

1. 启用功能

环境变量：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

或配置文件（~/.claude/settings.json）：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

2. 验证配置

./scripts/validate-setup.sh

检查项包括：环境变量是否已设置、claude CLI 是否可用、tmux 是否已安装（可选）。

3. 选择模板

每个模板均包含：适用条件、团队结构、可直接复制粘贴的启动提示（spawn prompt）、预期输出结果。

4. 启动团队

claude --pty
# 将模板中的 spawn prompt 粘贴至此

可通过 ./scripts/team-monitor.sh（在单独终端中运行）或 Claude Code 内按 Ctrl+T 实时监控团队状态。

核心原则

1. 明确的文件边界 — 每位团队成员负责不同的文件或目录（避免编辑冲突）
2. 启用 delegate 模式 — 主导者（lead）负责协调，成员（teammate）负责实施（需在 spawn prompt 中明确说明）
3. 合理划分任务粒度 — 每位成员分配 5–6 个自包含的子任务
4. 等待任务完成后再整合 — 主导者不得在成员尚未完成当前任务时提前合并结果
5. 优先开展调研 — 先启动研究员角色建立共识，再启动构建者角色推进实施

成本管理

Agent 团队相比单会话模式，token 消耗量提升3–4 倍；每位成员均拥有独立的上下文窗口。

优化建议：

• 混合使用模型 — 主导者使用 Opus（侧重战略），成员使用 Sonnet（侧重战术），可节省约 40% 成本
• 减少广播消息 — 仅在必要时使用点对点通信（广播消息将复制至所有成员）
• 合理控制团队规模 — 通常 3 名成员为最优配置；仅在高度并行任务中考虑启用 6 名及以上成员

详见 references/cost-management.md 获取完整优化策略。

故障排查

成员未成功启动？

• 确认已正确设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• 设置环境变量后，请重启 Claude Code

出现文件冲突？

• 在 spawn prompt 中明确定义文件边界（推荐以目录级所有权方式声明）

主导者自行编码而非协调？

• 在 spawn prompt 中添加：“Use delegate mode: coordinate but don't implement”
• 或按 Shift+Tab 切换至 delegate 模式

完整问题清单请参阅 references/troubleshooting.md。

自动化脚本

监控进度：

./scripts/team-monitor.sh

清理资源（优雅关闭）：

./scripts/team-cleanup.sh

显示模式

进程内模式（默认）— 所有成员共用主终端

• Shift+Up/Down — 切换当前选中的成员
• Ctrl+T — 切换任务列表显示/隐藏
• Escape — 中断当前成员执行

分屏模式（需安装 tmux 或 iTerm2）— 每位成员独占一个终端窗格

• 在 ~/.claude/settings.json 中设置 teammateMode: "tmux"

参考资料

• templates/ — 6 个即用型 spawn prompt 模板，含详细使用指引
• scripts/ — 自动化辅助脚本（验证、监控、清理）
• references/best-practices.md — 团队使用时机、任务粒度设计、文件边界定义等最佳实践
• references/cost-management.md — Token 消耗优化策略
• references/troubleshooting.md — 常见问题与解决方案
• examples/ — 真实场景示例（PR 审查、缺陷排查、功能开发全流程）

对比说明

参与贡献

发现实用的新模式？欢迎提交 PR，内容需包含：

1. 新模板或示例
2. 适用场景说明 + 团队结构设计
3. spawn prompt 示例 + 预期输出结果

致谢

本项目融合了 Claude Code 官方文档、ClaudeFast 模式以及 OpenClaw 社区的实践经验。

代码仓库： https://github.com/matthew-a-gordon/claude-code-teams
许可证： MIT