简介

Agent Teams 是 Claude Code 的实验性功能，允许编排多个 Claude Code 实例并行协作完成复杂任务。一个主会话（Team Lead）协调多个独立的 Teammate 实例，通过共享任务列表和消息机制实现分工合作。

实验性功能

需要 Claude Code v2.1.32+，需手动启用。

启用与配置

启用 Agent Teams

方式一：环境变量

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

方式二：settings.json

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

显示模式配置

在 ~/.claude.json 中配置：

{
  "teammateMode": "auto"  // "auto" | "tmux" | "in-process"
}

或通过 CLI 参数：

claude --teammate-mode in-process

模式	说明
auto（默认）	在 tmux 会话内自动使用 split panes，否则使用 in-process
in-process	所有 teammates 在同一终端窗口，通过快捷键切换
tmux	自动检测 tmux 或 iTerm2，每个 teammate 独立面板

核心架构

┌─────────────────────────────────────────────┐
│                 Team Lead                    │
│          （主会话，协调全局）                   │
├─────────┬─────────┬─────────┬───────────────┤
│         │         │         │               │
│  Task   │ Mailbox │ Spawn   │   Delegate    │
│  List   │  通信   │ 管理     │    Mode       │
│         │         │         │               │
├─────┬───┴────┬────┴───┬─────┴───────────────┤
│     ▼        ▼        ▼                     │
│ Teammate A  Teammate B  Teammate C          │
│ (独立上下文) (独立上下文) (独立上下文)          │
│ (独立工作区) (独立工作区) (独立工作区)          │
└─────────────────────────────────────────────┘

组件	职责
Team Lead	创建任务、分配工作、审批计划、协调进度、汇总结果
Teammates	独立 Claude Code 实例，各有独立上下文窗口，自行认领和执行任务
Task List	共享任务列表，支持依赖关系，存储在 ~/.claude/tasks/{team-name}/
Mailbox	实例间直接通信机制，支持一对一和广播

关键细节：

• 团队配置存储在 ~/.claude/teams/{team-name}/config.json
• Teammates 加载相同的项目上下文（CLAUDE.md、MCP、Skills），但不继承 Lead 的对话历史
• Lead 在团队生命周期内固定，不可转移

使用方式

创建团队

用自然语言告诉 Claude 创建团队：

> 创建一个团队，分配 3 个 teammates 并行重构这三个模块：
> - auth 模块
> - payment 模块
> - notification 模块

> Create an agent team to review PR #142. Spawn three reviewers:
> - One focused on security implications
> - One checking performance impact
> - One validating test coverage

快捷键（In-process 模式）

快捷键	操作
Shift+Down	切换到下一个 teammate（循环）
Enter	查看当前 teammate 完整会话
Escape	中断当前 teammate 的执行
Ctrl+T	切换显示共享任务列表
Shift+Tab	切换权限模式（包括 Delegate Mode）

生命周期管理

> 让 researcher teammate 停止工作          # 请求单个 teammate 关闭
> 等待所有 teammates 完成任务再继续         # 阻止 Lead 自己动手
> 清理团队                                # 移除团队资源（需先关闭所有 teammates）

任务管理

任务状态

任务有三种状态：pending → in_progress → completed

七个核心工具

工具	说明
TeamCreate	初始化团队命名空间，创建磁盘上的协调基础设施
TaskCreate	创建任务（JSON 文件），description 就是 teammate 看到的提示词
TaskUpdate	认领任务、更新状态、标记完成
TaskList	查询所有任务及当前状态
Task	生成（spawn）一个 teammate 加入团队
SendMessage	实例间直接通信
TeamDelete	删除团队配置和任务文件

依赖管理

任务可以声明依赖关系，形成 DAG（有向无环图）：

• 有未完成依赖的任务不能被认领
• 依赖任务完成后，下游任务自动解锁
• 任务按依赖链分"波次"执行

任务分配策略

• Lead 指派：明确告诉 Lead 哪个任务给哪个 teammate
• 自行认领：teammate 完成当前任务后，自动从任务列表中认领下一个未分配、未阻塞的任务
• 认领使用文件锁防止竞争条件

推荐规模

每个 teammate 分配 5-6 个任务保持高效。15 个独立任务配 3 个 teammates 是个好起点。

消息通信

消息类型

类型	说明
message	发送给指定 teammate
broadcast	发送给所有 teammates（慎用，token 成本线性增长）
shutdown_request	请求 teammate 关闭
shutdown_response	teammate 对关闭请求的回复
plan_approval_response	Lead 对计划审批请求的回复

通信模式

• Lead 可以给任意 teammate 发消息
• Teammate 可以给 Lead 发消息
• Teammate 之间可以直接通信，无需 Lead 中转
• 消息自动投递，无需轮询

SendMessage({
  "type": "message",
  "recipient": "backend-dev",
  "content": "API 类型定义已更新在 /types/api.ts，可以开始前端集成了",
  "summary": "API types ready"
})

Plan Approval 模式

对复杂或高风险任务，可要求 teammates 先提交计划再执行：

工作流程：

1. 生成 teammate 时指定需要计划审批：

   > 生成一个 architect teammate 重构认证模块，要求先提交计划审批

2. Teammate 进入只读计划模式 — 可以分析代码但不能修改文件

3. 计划完成后，teammate 向 Lead 发送计划审批请求

4. Lead 审核后：

   • 通过 → teammate 退出计划模式，开始实施
   • 驳回并附反馈 → teammate 保持计划模式，修改后重新提交

引导 Lead 的审批标准：

> 只审批包含测试覆盖的计划
> 拒绝修改数据库 schema 但没有 migration 的计划

Delegate Mode

按 Shift+Tab 切换到 Delegate Mode，限制 Lead 只能使用协调类工具：

• ✅ 生成 teammates、发消息、管理任务
• ❌ 不能直接编辑文件或运行命令

这迫使 Lead 专注协调而非亲自动手，适合复杂多人任务场景。

Quality Gate Hooks

通过 hooks 在任务生命周期中强制执行质量规则。在 settings.json 中配置：

{
  "hooks": {
    "TeammateIdle": [{ "type": "command", "command": "/path/to/script.sh" }],
    "TaskCreated": [{ "type": "command", "command": "/path/to/script.sh" }],
    "TaskCompleted": [{ "type": "command", "command": "/path/to/script.sh" }]
  }
}

TeammateIdle

Teammate 完成当前工作即将空闲时触发。

#!/bin/bash
# 确保构建产物存在才允许空闲
if [ ! -f "./dist/output.js" ]; then
  echo "构建产物缺失，请先运行构建" >&2
  exit 2  # exit 2 = 发送 stderr 作为反馈，让 teammate 继续工作
fi
exit 0

TaskCreated

通过 TaskCreate 创建任务时触发。

#!/bin/bash
# 强制任务标题包含工单号
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
  echo "任务标题必须以工单号开头，如 [TICKET-123]" >&2
  exit 2  # exit 2 = 阻止任务创建
fi
exit 0

TaskCompleted

任务被标记完成时触发。

#!/bin/bash
# 确保测试通过才允许完成任务
if ! npm test 2>&1; then
  echo "测试未通过，请修复后再标记完成" >&2
  exit 2  # exit 2 = 阻止标记完成
fi
exit 0

Hook 输入通过 stdin 以 JSON 格式传入，包含 session_id、teammate_name、team_name、task_id、task_subject、task_description 等字段。

与 Git Worktrees 配合

Agent Teams 和 Git Worktrees 是互补的：Worktrees 提供文件隔离，Agent Teams 提供任务协调。

内置 Worktree 支持

claude --worktree feature-auth    # 创建 .claude/worktrees/feature-auth/
claude --worktree bugfix-123      # 创建独立 worktree
claude --worktree                 # 自动生成随机名称

Subagent Worktree 隔离

在自定义 subagent 的 frontmatter 中添加 isolation: worktree，每个 subagent 获得独立 worktree，完成后自动清理。

推荐协作模式

1. 为每个功能分支创建 worktree
2. 在各 worktree 中启动独立 Claude Code 会话
3. 使用 Agent Teams 进行任务管理和消息通信
4. 功能完成后，创建一个新会话审查 PRs 并按最优顺序合并

注意事项

• 在 .gitignore 中添加 .claude/worktrees/
• 创建 .worktreeinclude 文件列出需要复制的 gitignored 文件（如 .env）
• 如果远程默认分支变更，运行 git remote set-head origin -a

适用场景

并行代码审查

创建一个团队审查 PR #142，生成三个审查者：
- 一个关注安全影响
- 一个检查性能影响
- 一个验证测试覆盖

竞争性假设调试

用户反馈应用在发送消息后退出。生成 5 个 teammates 调查不同假设，
让他们互相交流，尝试否定彼此的理论。

跨层功能开发

分别为前端、后端、测试分配 teammates，各自负责一层，通过消息同步依赖（如"API 类型定义已就绪"）。

QA 全面扫描

Lead 创建 5 个任务（核心页面响应、博客渲染、导航链接完整性、RSS/SEO、无障碍），5 个 teammates 并行执行，约 3 分钟完成，Lead 汇总为优先级报告。

多视角调研

我在设计一个追踪 TODO 注释的 CLI 工具，创建一个团队：
- 一个 teammate 负责 UX 设计
- 一个负责技术架构
- 一个扮演 Devil's Advocate（唱反调）

最佳实践

1. 给 teammates 充足上下文 — 它们不继承 Lead 对话历史，spawn 时要提供足够的任务描述
2. 合理控制团队规模 — 建议 3-5 个 teammates，token 成本线性增长
3. 合理拆分任务粒度 — 每 teammate 5-6 个任务；太小则协调开销过大，太大则浪费风险高
4. 避免文件冲突 — 拆分工作使每个 teammate 负责不同的文件集
5. 主动监控和引导 — 定期检查进度，及时纠正不理想的方向
6. 让 Lead 等待 — 告诉 Lead "等待 teammates 完成再继续"，防止它自己动手
7. 从低风险任务开始 — 先用于 PR 审查、调研等非编码任务，熟悉后再用于开发
8. 预配置权限 — 在生成 teammates 前配置好权限设置，减少交互摩擦
9. 善用 CLAUDE.md — 文档化模块边界、项目上下文、技术栈、验证命令
10. 先计划后并行 — 先用 /plan 制定方案，审核后再用团队执行

已知限制

• 不支持 /resume 和 /rewind 恢复 teammates
• 任务状态可能滞后（teammate 有时不标记任务完成）
• 关闭速度较慢（teammate 需完成当前请求后才停止）
• 每个会话只能有一个 team
• 不支持嵌套 teams
• Lead 固定，不可转移
• 所有 teammates 继承 Lead 的权限模式
• Split Panes 不支持 VS Code 集成终端、Windows Terminal、Ghostty
• Token 消耗约为单会话的 3-4x（3 个 teammates）

相关链接

• Agent Teams 官方文档
• Hooks 参考文档
• Git Worktrees 工作流
• Claude Code Swarms - Addy Osmani
• 30 Tips for Agent Teams

贡献者: Ra1n

上一页Harness 工程

下一页OpenAI