Back to Details

claude-code-agent-teams

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude Code Agent Teams

Claude Code Agent Teams

Agent teams coordinate multiple Claude Code sessions working together. One session acts as the team lead, spawning teammates that work independently in their own context windows and communicate directly with each other through a shared task list and mailbox messaging system.
Agent teams are experimental and disabled by default. Enable with 
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
. See Setup and Configuration for details.
Agent团队可协调多个Claude Code会话协同工作。其中一个会话充当团队负责人，生成队友，这些队友在各自的上下文窗口中独立工作，并通过共享任务列表和邮箱消息系统直接相互通信。
Agent团队属于实验性功能，默认处于禁用状态。可通过设置
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
启用。详情请参阅设置与配置。

When to Use Agent Teams

何时使用Agent团队

Agent teams add coordination overhead and consume significantly more tokens than a single session. Use them when parallel exploration adds real value:
  • Research and review — teammates investigate different aspects simultaneously, share and challenge findings
  • New modules or features — teammates each own a separate piece without stepping on each other
  • Debugging with competing hypotheses — teammates test different theories in parallel, converge on answers faster
  • Cross-layer coordination — changes spanning frontend, backend, and tests, each owned by a different teammate
Avoid agent teams for sequential tasks, same-file edits, work with many dependencies, or tasks a single session handles efficiently. For focused workers that only report results back, use subagents instead.
Agent团队会增加协调开销，且消耗的token远多于单个会话。仅当并行探索能带来实际价值时使用：
  • 研究与评审——队友同时调查不同方面，分享并质疑发现
  • 新模块或功能开发——队友各自负责独立部分，互不干扰
  • 多假设调试——队友并行测试不同理论，更快收敛到答案
  • 跨层协调——涉及前端、后端和测试的变更，各部分由不同队友负责
对于顺序任务、单文件编辑、存在大量依赖的工作，或单个会话可高效处理的任务，请勿使用Agent团队。若仅需要专注工作并返回结果的角色，请使用子agent。

Agent Teams vs Subagents

Agent团队 vs 子Agent

SubagentsAgent Teams
ContextOwn window; results return to callerOwn window; fully independent
CommunicationReport back to main agent onlyTeammates message each other directly
CoordinationMain agent manages all workShared task list with self-coordination
Best forFocused tasks where only the result mattersComplex work requiring discussion/collaboration
Token costLower: results summarized to main contextHigher: each teammate is a separate instance
子AgentAgent团队
上下文拥有独立窗口；结果返回给调用方拥有独立窗口；完全独立
通信方式仅向主Agent汇报队友之间直接相互通信
协调方式主Agent管理所有工作通过共享任务列表自主协调
适用场景仅关注结果的聚焦任务需要讨论/协作的复杂工作
Token成本较低：结果会汇总到主上下文较高：每个队友都是独立实例

Starting a Team

创建团队

Describe the task and team structure in natural language. Claude creates the team, spawns teammates, and coordinates work:
Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.
Claude can also propose a team if it determines a task benefits from parallel work. It always asks for confirmation first.
用自然语言描述任务和团队结构。Claude会创建团队、生成队友并协调工作：
Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.
若Claude判定任务可从并行工作中获益，也会主动提议创建团队，且总会先征得用户确认。

Core Concepts

核心概念

Architecture

架构

ComponentRole
Team leadMain session that creates the team, spawns teammates, coordinates work
TeammatesSeparate Claude Code instances working on assigned tasks
Task listShared work items teammates claim and complete, with dependency tracking
MailboxMessaging system for direct communication between agents
Teams and tasks are stored locally at 
~/.claude/teams/{team-name}/config.json
and 
~/.claude/tasks/{team-name}/
. See Architecture and Communication for internals.
组件角色
团队负责人创建团队、生成队友、协调工作的主会话
队友负责指定任务的独立Claude Code实例
任务列表队友可认领和完成的共享工作项，支持依赖追踪
邮箱用于Agent间直接通信的消息系统
团队和任务数据本地存储于
~/.claude/teams/{team-name}/config.json
和
~/.claude/tasks/{team-name}/
。内部实现详情请参阅架构与通信。

Display Modes

显示模式

  • In-process (default) — all teammates run inside the main terminal. Navigate with Shift+Up/Down. Works in any terminal.
  • Split panes — each teammate gets its own pane. Requires tmux or iTerm2. Click into any pane to interact directly.
Default is 
"auto"
: split panes if already in tmux, in-process otherwise. Override with 
teammateMode
in settings or 
--teammate-mode
flag.
  • 进程内模式（默认）——所有队友在主终端内运行。使用Shift+Up/Down切换。适用于所有终端。
  • 分窗模式——每个队友拥有独立窗格。需要tmux或iTerm2支持。点击任意窗格即可直接交互。
默认模式为
"auto"
：若已在tmux环境中则使用分窗模式，否则使用进程内模式。可通过设置中的
teammateMode
或
--teammate-mode
标志覆盖默认设置。

Communication

通信机制

Teammates do not inherit the lead's conversation history. Each loads project context (CLAUDE.md, MCP servers, skills) plus the spawn prompt from the lead.
  • Direct messages — send to one specific teammate
  • Broadcast — send to all teammates (use sparingly, costs scale with team size)
  • Idle notifications — teammates automatically notify the lead when they finish
  • Shared task list — all agents see task status and claim available work
队友不会继承负责人的对话历史。每个队友会加载项目上下文（CLAUDE.md、MCP服务器、技能）以及负责人的生成提示。
  • 直接消息——发送给特定单个队友
  • 广播消息——发送给所有队友（请谨慎使用，成本随团队规模增加而上升）
  • 空闲通知——队友完成工作后会自动通知负责人
  • 共享任务列表——所有Agent均可查看任务状态并认领可用工作

Task Management

任务管理

Tasks have three states: pending, in progress, and completed. Tasks can depend on other tasks — a pending task with unresolved dependencies cannot be claimed until those complete.
  • The lead assigns tasks explicitly, or teammates self-claim the next unassigned, unblocked task
  • Task claiming uses file locking to prevent race conditions
  • When a task completes, blocked tasks unblock automatically
任务分为三种状态：待处理、进行中和已完成。任务可依赖其他任务——存在未解决依赖的待处理任务需等依赖完成后才能被认领。
  • 负责人可明确分配任务，或由队友自主认领下一个未分配、未被阻塞的任务
  • 任务认领采用文件锁机制，防止竞态条件
  • 任务完成后，被其阻塞的任务会自动解除阻塞

Lead Controls

负责人控制功能

Delegate Mode

委托模式

Restrict the lead to coordination-only tools (spawning, messaging, shutting down teammates, managing tasks) so it focuses on orchestration instead of implementing work itself. Toggle with Shift+Tab.
将负责人限制为仅使用协调类工具（生成队友、消息传递、关闭队友、管理任务），使其专注于编排而非直接执行工作。使用Shift+Tab切换。

Plan Approval

计划审批

Require teammates to plan before implementing. The teammate works in read-only plan mode until the lead approves:
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.
The lead approves or rejects with feedback autonomously. Influence judgment with criteria: "only approve plans that include test coverage" or "reject plans that modify the database schema."
要求队友在执行前先制定计划。在负责人批准前，队友将处于只读计划模式：
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.
负责人可自主批准或拒绝计划，并给出反馈。可通过设定标准影响判断："仅批准包含测试覆盖的计划"或"拒绝修改数据库架构的计划"。

Quality Gate Hooks

质量门钩子

Enforce rules with hooks:
  • TeammateIdle
     — runs when a teammate is about to go idle. Exit code 2 sends feedback and keeps the teammate working.
  • TaskCompleted
     — runs when a task is being marked complete. Exit code 2 prevents completion and sends feedback.
通过钩子强制执行规则：
  • TeammateIdle
    ——当队友即将进入空闲状态时触发。返回退出码2会发送反馈并让队友继续工作。
  • TaskCompleted
    ——当任务即将被标记为完成时触发。返回退出码2会阻止任务完成并发送反馈。

Interacting with Teammates

与队友交互

  • In-process: Shift+Up/Down to select, type to message. Enter to view session, Escape to interrupt. Ctrl+T toggles task list.
  • Split panes: click into any pane to interact directly.
  • 进程内模式：使用Shift+Up/Down选择队友，输入内容发送消息。按Enter查看会话，按Escape中断。按Ctrl+T切换任务列表显示。
  • 分窗模式：点击任意窗格即可直接交互。

Shutting Down

关闭团队

Ask the lead to shut down specific teammates (they can approve or reject). Then ask the lead to clean up the team. Always clean up through the lead — teammates should not run cleanup.
请求负责人关闭特定队友（负责人可批准或拒绝）。然后请求负责人清理团队。请始终通过负责人进行清理——队友不应执行清理操作。

Task Decomposition

任务分解

The key to effective agent teams is decomposing tasks into independent work streams. See Task Decomposition Patterns for detailed examples.
Core principles:
  1. Maximize independence — zero dependencies between teammates is ideal
  2. Minimize write conflicts — each teammate owns distinct files or directories
  3. Prefer read-heavy work — analysis, review, and research parallelize cleanly
  4. Right-size tasks — 5-6 tasks per teammate keeps everyone productive; too small wastes overhead, too large creates bottlenecks
Anti-patterns to avoid:
  • Sequential chains where step 2 depends on step 1's output
  • Multiple teammates editing the same file
  • Micro-tasks not worth the spawn overhead
  • Prompts that assume shared conversation context (teammates start fresh)
高效使用Agent团队的关键是将任务拆分为独立工作流。不同任务类型的详细分解模式请参阅任务分解模式。
核心原则：
  1. 最大化独立性——队友间完全无依赖为最佳状态
  2. 最小化写入冲突——每个队友负责不同的文件或目录
  3. 优先选择读密集型工作——分析、评审和研究类工作可完美并行
  4. 合理规划任务规模——每个队友负责5-6个任务可保持高效；任务过小会浪费开销，过大则会造成瓶颈
需避免的反模式：
  • 步骤2依赖步骤1输出的顺序链
  • 多个队友编辑同一文件
  • 开销大于价值的微任务
  • 假设队友共享对话上下文的提示（队友会从全新状态开始）

Best Practices

最佳实践

  • Give teammates enough context in spawn prompts — they load CLAUDE.md but not the lead's conversation
  • Specify teammate count and models explicitly when needed: 
    "Create a team with 4 teammates. Use Sonnet for each."
  • Tell the lead to wait for teammates before proceeding if it starts implementing itself
  • Start with research and review tasks to learn the coordination model before attempting parallel implementation
  • Avoid file conflicts by ensuring each teammate owns different files
  • Monitor and steer — check progress, redirect failing approaches, synthesize findings as they arrive
  • Pre-approve common operations in permission settings to reduce interruption from teammate permission prompts
  • 在生成提示中为队友提供足够上下文——他们会加载CLAUDE.md，但不会加载负责人的对话历史
  • 必要时明确指定队友数量和模型：
    "Create a team with 4 teammates. Use Sonnet for each."
  • 若负责人开始自行执行工作，告知其等待队友完成后再继续
  • 先从研究和评审任务入手，熟悉协调模式后再尝试并行开发
  • 通过确保每个队友负责不同文件来避免文件冲突
  • 监控并引导——检查进度、调整失败的方案、汇总已有的发现
  • 在权限设置中预先批准常见操作，减少队友权限提示带来的干扰

Quick Reference

快速参考

ActionHow
Enable featureSet 
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
to 
1
in env or settings.json
Start a teamDescribe task and team structure in natural language
Navigate teammatesShift+Up / Shift+Down (in-process) or click pane (split)
Toggle task listCtrl+T
Delegate modeShift+Tab
View teammate sessionEnter (in-process mode)
Interrupt teammateEscape (in-process mode)
Specify modelsInclude in prompt: 
"Use Sonnet for each teammate"
操作方式
启用功能在环境变量或settings.json中设置
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
为
1
创建团队用自然语言描述任务和团队结构
切换队友Shift+Up / Shift+Down（进程内模式）或点击窗格（分窗模式）
切换任务列表显示Ctrl+T
切换委托模式Shift+Tab
查看队友会话Enter（进程内模式）
中断队友Escape（进程内模式）
指定模型在提示中说明：
"Use Sonnet for each teammate"

Reference Documentation

参考文档

  • Setup and Configuration — enabling, display modes, permissions, settings
  • Architecture and Communication — internals, messaging, task lifecycle, token usage
  • Task Decomposition Patterns — detailed patterns for different task types
  • Use Case Examples — end-to-end workflows with prompts
  • Troubleshooting — common issues, limitations, diagnostics
Official documentation: https://code.claude.com/docs/en/agent-teams
  • 设置与配置 — 启用方式、显示模式、权限、设置
  • 架构与通信 — 内部实现、消息传递、任务生命周期、Token使用
  • 任务分解模式 — 不同任务类型的详细分解模式
  • 用例示例 — 带提示的端到端工作流
  • 故障排除 — 常见问题、限制、诊断方法
官方文档：https://code.claude.com/docs/en/agent-teams