agent-teams

Agent Teams

协调多个 Claude Code 会话同时处理同一个代码库。

启用

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude  # starts as team lead

第一个会话会成为团队负责人。同一仓库中的后续会话会作为队友加入。

架构

Team Lead (coordinates, delegates, reviews)
  ├── Teammate 1 (owns task A, messages lead + peers)
  ├── Teammate 2 (owns task B, messages lead + peers)
  └── Teammate 3 (owns task C, messages lead + peers)
      │
      └── Shared: task list + mailbox + file locks

**与子 Agent 的主要区别：**队友是完整的 Claude Code 会话。他们拥有自己的上下文窗口，可以使用所有工具，还能直接互相发送消息——而不只是向父级汇报。

团队规模

团队规模	最适合
2	一人构建，一人审查
3-5	跨层并行开发功能（API、UI、测试）
> 5	协调开销超过并行工作的收益

3-5 名队友是高效的规模。超过这个数量，负责人花在协调上的时间会比团队节省的时间更多。

**任务粒度：**每名队友安排 5-6 个任务。更少会导致资源未充分利用；更多则会造成过度的上下文切换。

显示模式

进程内导航：

• Shift+Down — 在队友之间轮换（循环切换）
• 查看每名队友当前的任务和输出

分屏（推荐用于超过 2 名队友的情况）：

• tmux：为每名队友执行一次 tmux split-window -h
• iTerm2：使用 Cmd+D 进行垂直分屏
• 每个窗格运行自己的 claude 会话

任务管理

任务按以下状态流转：

pending → in-progress → completed
              │
              └── blocked (waiting on dependency)

任务拆分

将工作拆分为满足以下条件的单元：

• 涉及的文件互不重叠
• 可以独立验证
• 有明确的完成标准

良好的拆分方式：

Task 1: Add rate limiting middleware (src/middleware/rate-limit.ts)
Task 2: Add rate limit tests (tests/rate-limit.test.ts)
Task 3: Update API docs for rate limit headers (docs/api.md)
Task 4: Add Redis config for rate limit store (src/config/redis.ts)

不良的拆分方式：

Task 1: Implement rate limiting
Task 2: Fix rate limiting bugs
Task 3: Improve rate limiting

依赖关系

任务可以声明依赖关系：

Task 3 (API docs) → depends on Task 1 (middleware)
Task 2 (tests) → depends on Task 1 (middleware)
Task 4 (Redis config) → no dependencies

队友会自动接手没有阻塞项的任务。

文件锁定认领

队友在编辑前认领文件，以避免冲突：

1. 队友检查文件是否已锁定
2. 如果未锁定，则认领文件（基于文件锁）
3. 编辑文件
4. 任务完成后释放锁

如果两名队友需要同一个文件，一人等待，或由负责人重新分配。

计划审批

队友在实施前制定计划：

1. 队友接收任务
2. 编写简要计划（要修改的文件、实施方案）
3. 负责人审查计划
4. 负责人批准或调整方向
5. 队友实施

这样可以避免因误解需求而造成无用功。

委派模式

Shift+Tab 可为负责人切换委派模式：

• 负责人只负责协调，不直接编辑代码
• 所有实施工作都委派给队友
• 负责人审查并批准计划，管理任务流转

Hook 事件

Hook	触发时机
TeammateIdle	队友完成任务且没有待处理工作时
TaskCreated	向共享列表添加新任务时
TaskCompleted	队友将任务标记为完成时

使用这些事件可触发通知、自动分配下一个任务，或在所有任务完成时运行集成测试。

何时使用团队或其他方案

场景	使用
对互不重叠的文件进行并行处理	Agent 团队
快速后台探索	子 Agent
在隔离的功能分支中工作	Worktree（claude -w）
针对同一问题尝试不同方案	Worktree（比较结果）
跨层修改（API + UI + 测试）	Agent 团队
一次性委派	使用 isolation: worktree 的子 Agent
大规模迁移（20+ 个文件）	/batch 命令

反模式

• 队友超过 5 名——协调开销会占据主导
• 任务共享可变状态或同一文件
• 跳过计划审批——会导致返工
• 负责人亲自实施而非协调（使用委派模式）
• 未设置依赖关系——队友会在相互关联的任务上抢先行动

会话示例

Lead: "We need rate limiting. Breaking into 4 tasks."

  Task 1: middleware implementation → Teammate 1
  Task 2: Redis config → Teammate 2 (no deps)
  Task 3: tests → Teammate 1 (after Task 1)
  Task 4: API docs → Teammate 2 (after Task 1)

Teammate 1 plans → Lead approves → implements Task 1
Teammate 2 plans → Lead approves → implements Task 2
Task 1 completes → unblocks Tasks 3 and 4
Teammate 1 picks up Task 3, Teammate 2 picks up Task 4
All complete → Lead runs integration tests → commits

文档

https://code.claude.com/docs/agent-teams