Back to Details

agent-teams

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Teams

Agent Teams

Coordinate multiple Claude Code sessions working on the same codebase simultaneously.
协调多个同时在同一 codebase 上工作的 Claude Code 会话。

Enable

启用

bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude  # starts as team lead
The first session becomes the team lead. Subsequent sessions in the same repo join as teammates.
bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude  # starts as team lead
第一个会话成为 team lead。同一 repo 中的后续会话会作为 teammate 加入。

Architecture

架构

text
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
Key difference from subagents: Teammates are full Claude Code sessions. They have their own context window, can use all tools, and message each other directly — not just report back to a parent.
text
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
与 subagent 的关键区别： teammate 是完整的 Claude Code 会话。它们拥有自己的 context window，可以使用所有工具，并且能够直接相互通信，而不只是向父级会话汇报。

Team Sizing

团队规模

Team SizeBest For
2One builds, one reviews
3-5Parallel features across layers (API, UI, tests)
> 5Coordination overhead outweighs parallelism
3-5 teammates is the productive range. Beyond that, the lead spends more time coordinating than the team saves.
Task granularity: Aim for 5-6 tasks per teammate. Fewer means underutilization; more means excessive context switching.
团队规模最适用场景
2一人构建，一人审查
3-5跨层并行开发功能（API、UI、测试）
> 5协调开销超过并行带来的收益
3-5 名 teammate 是高效区间。超过此数量，lead 花在协调上的时间会超过团队节省的时间。
任务粒度： 目标是每名 teammate 负责 5-6 项任务。任务太少意味着利用率不足；任务太多则会造成过多 context switching。

Display Modes

显示模式

In-process navigation:
  • Shift+Down
    — cycle through teammates (wraps around)
  • See each teammate's current task and output
Split-pane (recommended for >2 teammates):
  • tmux: 
    tmux split-window -h
    per teammate
  • iTerm2: Cmd+D for vertical split
  • Each pane runs its own 
    claude
    session
进程内导航：
  • Shift+Down
    — 循环切换 teammate（循环回到列表开头）
  • 查看每名 teammate 当前的任务和输出
分屏（建议在 teammate 超过 2 名时使用）：
  • tmux：每名 teammate 执行 
    tmux split-window -h
  • iTerm2：按 Cmd+D 进行垂直分屏
  • 每个窗格运行自己的 
    claude
    会话

Task Management

任务管理

Tasks flow through states:
text
pending → in-progress → completed
              │
              └── blocked (waiting on dependency)
任务通过以下状态流转：
text
pending → in-progress → completed
              │
              └── blocked (waiting on dependency)

Task Decomposition

任务拆分

Break work into units that:
  • Touch non-overlapping files
  • Can be verified independently
  • Have clear done criteria
Good decomposition:
text
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)
Bad decomposition:
text
Task 1: Implement rate limiting
Task 2: Fix rate limiting bugs
Task 3: Improve rate limiting
将工作拆分为满足以下条件的单元：
  • 修改互不重叠的文件
  • 可以独立验证
  • 具有清晰的完成标准
良好的拆分方式：
text
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)
不良的拆分方式：
text
Task 1: Implement rate limiting
Task 2: Fix rate limiting bugs
Task 3: Improve rate limiting

Dependencies

依赖关系

Tasks can declare dependencies:
text
Task 3 (API docs) → depends on Task 1 (middleware)
Task 2 (tests) → depends on Task 1 (middleware)
Task 4 (Redis config) → no dependencies
Teammates pick up unblocked tasks automatically.
任务可以声明依赖关系：
text
Task 3 (API docs) → depends on Task 1 (middleware)
Task 2 (tests) → depends on Task 1 (middleware)
Task 4 (Redis config) → no dependencies
teammate 会自动领取未阻塞的任务。

File-Lock Claiming

文件锁认领

Teammates claim files before editing to prevent conflicts:
  1. Teammate checks if file is locked
  2. If free, claims it (file-lock-based)
  3. Edits the file
  4. Releases lock on task completion
If two teammates need the same file, one waits or the lead reassigns.
teammate 在编辑前认领文件以防止冲突：
  1. teammate 检查文件是否已锁定
  2. 如果未锁定，则认领该文件（基于文件锁）
  3. 编辑文件
  4. 任务完成后释放锁
如果两名 teammate 需要处理同一文件，其中一名会等待，或由 lead 重新分配任务。

Plan Approval

计划审批

Teammates plan before implementing:
  1. Teammate receives task
  2. Writes a brief plan (files to change, approach)
  3. Lead reviews plan
  4. Lead approves or redirects
  5. Teammate implements
This prevents wasted work from misunderstood requirements.
teammate 在实现之前先制定计划：
  1. teammate 接收任务
  2. 编写简要计划（要修改的文件、实现方法）
  3. lead 审查计划
  4. lead 批准或调整方向
  5. teammate 实施
这可以避免因误解需求而浪费工作。

Delegate Mode

Delegate 模式

Shift+Tab
toggles delegate mode for the lead:
  • Lead coordinates only — no direct code edits
  • All implementation delegated to teammates
  • Lead reviews, approves plans, manages task flow
Shift+Tab
为 lead 切换 delegate mode：
  • lead 只负责协调——不直接修改代码
  • 所有实现工作都委派给 teammate
  • lead 审查、批准计划并管理任务流转

Hook Events

Hook 事件

HookFires When
TeammateIdleA teammate finishes its task and has no pending work
TaskCreatedNew task added to the shared list
TaskCompletedA teammate marks a task done
Use these to trigger notifications, auto-assign next tasks, or run integration tests when all tasks complete.
Hook触发时机
TeammateIdleteammate 完成其任务且没有待处理工作
TaskCreated新任务被添加到共享列表
TaskCompletedteammate 将任务标记为已完成
可以使用这些事件触发通知、自动分配下一项任务，或在所有任务完成后运行集成测试。

When to Use Teams vs Alternatives

何时使用 teams 与替代方案

ScenarioUse
Parallel work on non-overlapping filesAgent teams
Quick background explorationSubagent
Isolated feature branch workWorktree (
claude -w
)
Competing approaches to same problemWorktrees (compare results)
Cross-layer changes (API + UI + tests)Agent teams
One-off delegationSubagent with 
isolation: worktree
Large-scale migration (20+ files)
/batch
command
场景使用
对互不重叠的文件并行工作Agent teams
快速的后台探索Subagent
隔离的功能分支工作Worktree (
claude -w
)
针对同一问题的竞争性方案Worktrees（比较结果）
跨层更改（API + UI + 测试）Agent teams
一次性委派带 
isolation: worktree
的 Subagent
大规模迁移（20+ 个文件）
/batch
命令

Anti-Patterns

反模式

  • More than 5 teammates — coordination overhead dominates
  • Tasks that share mutable state or the same files
  • Skipping plan approval — leads to rework
  • Lead doing implementation instead of coordinating (use delegate mode)
  • Not setting dependencies — teammates race on coupled tasks
  • 超过 5 名 teammate——协调开销占主导
  • 任务共享可变状态或涉及相同文件
  • 跳过计划审批——会导致返工
  • lead 亲自实现而不是负责协调（应使用 delegate mode）
  • 未设置依赖关系——teammate 会在存在耦合的任务上相互竞争

Example Session

会话示例

text
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
text
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

Docs

文档

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