---
created: "2026-05-16"
type: resource
tags: [resource, claude-code, agent-teams, orchestration, multi-agent, tmux, subagents, official, workflow]
source: "https://code.claude.com/docs/en/agent-teams"
---

# Claude Code Agent Teams 官方多 Agent 编排

Anthropic 官方嘅多 Claude Code instance 编排方案。同 ECC 嘅 `/orchestrate` 第三方实现唔同，呢个系 **Claude Code v2.1.32+ 内置嘅实验功能**，允许多个完整 session 通过共享 task list + 直接消息传递协同工作。

> 相关笔记：[[Everything Claude Code 多服务编排详解]]、[[ECC 编排实战手册]]、[[dmux 多Agent并行编排]]、[[Autonomous Agent Harness 自主代理框架]]

---

## 0. 三层编排能力速查

Claude Code 嘅并行编排有三层，由轻到重：

| 层次 | 工具 | 适用 | 通信方式 |
|------|------|------|---------|
| **Subagents** | `Agent` tool（单消息多 call） | 任务独立、只要结果、低成本 | 仅向主 agent 报告 |
| **Worktrees** | `git worktree` + 多 terminal | 长任务、build/test 隔离 | 无（人工协调） |
| **Agent Teams** | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` | 需讨论、互相 challenge、跨层协调 | Teammates 之间直接 `SendMessage` |

**判断口诀**：
- 任务可切干净、只要结果 → Subagents
- 长 horizon、独立分支 → Worktrees
- 需要互相对话、对抗审查、你想中途介入某个 worker → **Agent Teams**

---

## 1. Subagents vs Agent Teams 关键对比

| 维度 | Subagents | Agent Teams |
|------|-----------|------------|
| Context | 独立窗口，结果汇报返主 agent | 独立窗口，**完全独立 session** |
| 通信 | 只能向主 agent 报告 | **Teammates 之间直接 message** |
| 协调 | 主 agent 集中调度 | **共享 task list，self-coordination** |
| Token 成本 | 较低（结果会被压缩回主 context） | **显著更高**（每个 teammate 都系完整 Claude 实例） |
| 你能否同 worker 直接对话 | ❌ | ✅ Shift+Down 切换 |
| 嵌套 | 主 agent 可派 subagent | ❌ Teammate 不能再开 team |

---

## 2. 启用方法

`~/.claude/settings.json`：
```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "auto"
}
```

`teammateMode` 三种值：
- `in-process`：所有 teammate 喺主 terminal，**Shift+Down** 切换，**Ctrl+T** 切 task list
- `tmux`：split-pane 模式，需要 tmux 或 iTerm2 + it2 CLI
- `auto`（默认）：喺 tmux 内就 split，否则 in-process

要求版本：`claude --version` ≥ v2.1.32。

---

## 3. tmux 集成操作要点

### 3.1 启动 / 重接

```bash
# 首次创建（iTerm2 集成）
tmux -CC new -s billo_team

# 重新接入（推荐用普通 attach，最稳）
tmux attach -t billo_team

# iTerm2 ControlMode 重接（要 iTerm2 + 已开 tmux integration）
tmux -CC attach -t billo_team

# 列出所有 session
tmux ls

# 杀掉旧 session
tmux kill-session -t billo_team
```

### 3.2 常见坑

- **`-CC` 看到 raw `%begin %end %output` 输出 = 集成未生效**
  原因：用紧 Terminal.app 而唔系 iTerm2，或 iTerm2 集成被关。
  解决：改用 `tmux attach -t <name>` 普通模式。

- **duplicate session 错误**
  Session 已存在，用 attach 而唔系 new。

- **Claude Code 喺边度起？**
  喺 tmux session 入面用 `claude` 启动主 session，呢个就系 team lead。Teammate 由 lead 自动 spawn 入新 pane。

### 3.3 tmux 常用快捷键（attach 后）

| 快捷键 | 作用 |
|--------|------|
| `Ctrl+b d` | detach 离开但保留 session |
| `Ctrl+b s` | 列出 session 切换 |
| `Ctrl+b c` | 开新 window |
| `Ctrl+b %` / `"` | 垂直 / 水平 split pane |

---

## 4. 架构

| 组件 | 角色 |
|------|------|
| **Team lead** | 创建团队嘅主 session，spawn teammate + 协调 |
| **Teammates** | 独立 Claude Code 实例，各有 context window |
| **Task list** | 共享任务清单（pending / in_progress / completed，支持依赖） |
| **Mailbox** | Teammates 之间嘅消息系统，自动投递 |

**状态文件**（**唔好手编辑**，每次状态变更覆盖）：
- `~/.claude/teams/{team-name}/config.json`
- `~/.claude/tasks/{team-name}/`

> ⚠️ **冇 project 级 teams 配置**。`.claude/teams/teams.json` 系普通文件，唔识别。

---

## 5. Subagent 定义作为可复用 Teammate 角色

呢个系 Agent Teams 嘅核心可复用性机制。

### 5.1 写法

`.claude/agents/dotnet-backend-implementer.md`（project 级，可 commit）：
```markdown
---
name: dotnet-backend-implementer
description: Implements .NET backend modules following DDD patterns
tools: [Read, Write, Edit, Bash, Grep, Glob]
model: claude-sonnet-4-6
---

You implement .NET 8 backend modules in the Billo.Platform codebase.

Conventions you MUST follow:
- DDD layering: Domain / Application / Infrastructure / API
- Use Result<T> pattern for error returns, no exceptions for control flow
- Async methods end in Async, ConfigureAwait(false) on library code
- Repository interfaces in Domain, implementations in Infrastructure

Before implementing:
1. Read PLAN.md sections relevant to your assigned files
2. Check existing patterns in adjacent modules
3. Write xUnit tests first (TDD)

When done: report files changed + test coverage % to the lead.
```

### 5.2 喺 Agent Teams 入面引用

```text
Spawn a teammate using the dotnet-backend-implementer agent type
to handle Subtask 2.1.
```

### 5.3 注意事项

- Teammate 跟 subagent 定义嘅 `tools` allowlist 同 `model`
- 定义嘅 body **append** 到 teammate 嘅 system prompt（**唔系替换**）
- `SendMessage` 同 task 管理工具**永远可用**，即使 `tools` 限制咗其他
- ⚠️ 定义入面嘅 `skills`、`mcpServers` 喺 team 模式**唔生效**，teammate 从 project / user settings 加载

---

## 6. 大型项目完整工作流

### 6.1 One-time Setup

1. **写好可复用嘅 subagent 定义**（`.claude/agents/*.md`）
   建议角色：`backend-implementer`、`frontend-implementer`、`domain-modeler`、`test-writer`、`integration-reviewer`、`db-migration-author`
   既有嘅可直接用：`code-reviewer`、`security-reviewer`、`tdd-guide`、`architect`

2. **写 PLAN.md**（放 repo 根目录）
   关键：**每个 subtask 列明 owned files glob**，呢个系防冲突嘅唯一可靠方法。
   ```markdown
   # Project Plan

   ## Phase 2: Customer Context
   - 2.1 Customer aggregate
     - Owner files: src/Customer.Domain/**
   - 2.2 Customer application layer
     - Owner files: src/Customer.Application/**
     - Depends on: 2.1
   - 2.3 Customer API + integration tests
     - Owner files: src/Customer.Api/**, tests/Customer.IntegrationTests/**
     - Depends on: 2.2

   ## Cross-cutting Rules
   - File ownership is exclusive per subtask
   - Coverage ≥ 80% per module
   ```

3. **配置 hooks 作为质量门**（详见第 7 节）

### 6.2 每个阶段嘅 Spawn Prompt 模板

```text
We're starting Phase {N}. Read PLAN.md for context.

Create an agent team with {3-5} teammates:

[Teammate A]
  - Name: "customer-domain"
  - Subagent type: dotnet-backend-implementer
  - Task: Subtask 2.1
  - Owned files: src/Customer.Domain/**
  - Require plan approval before implementation.

[Teammate B]
  - Name: "customer-app"
  - Subagent type: dotnet-backend-implementer
  - Task: Subtask 2.2
  - Owned files: src/Customer.Application/**
  - Depends on: customer-domain finishing aggregate signatures
  - Require plan approval.

[Teammate C]
  - Name: "customer-api"
  - Subagent type: dotnet-backend-implementer
  - Task: Subtask 2.3
  - Owned files: src/Customer.Api/**, tests/Customer.IntegrationTests/**
  - Depends on: customer-app

COORDINATION RULES:
1. Create shared task list with dependencies.
2. Each teammate reads PLAN.md + cross-cutting rules.
3. When customer-domain finishes the aggregate API, message
   customer-app and customer-api with signatures.
4. No teammate edits files outside their owned glob.
5. Wait for all to finish before synthesis.

PLAN APPROVAL CRITERIA (for the lead):
- Reject plans that skip writing tests first.
- Reject plans touching files outside ownership.
- Approve plans with explicit coverage ≥ 80%.

AFTER ALL FINISH:
Spawn code-reviewer teammate for cross-module review.
Then security-reviewer for the API surface only.
Report: files changed, coverage %, findings.
```

### 6.3 阶段过渡

**唔好一次 spawn 所有阶段**。原因：
- 一次只能开一个 team，必须 cleanup 先开新
- 下一阶段 spec 可能因为上一阶段发现要调整
- Token 成本

过渡 prompt：
```text
Phase 2 is complete. Summarize:
- What was delivered vs plan
- Open issues / deferred items
- Any architectural changes
Then clean up the team.
```

---

## 7. Hooks 质量门

| Hook | 触发时机 | exit code 2 作用 |
|------|---------|------------------|
| `TeammateIdle` | Teammate 准备 idle 之前 | 推回反馈，迫继续做 |
| `TaskCreated` | 任务创建时 | 阻止创建，反馈意见 |
| `TaskCompleted` | 任务标记完成时 | 阻止完成，反馈意见 |

例子（`~/.claude/settings.json`）：
```json
{
  "hooks": {
    "TaskCompleted": [
      {
        "matcher": ".*test.*",
        "command": "dotnet test --collect:\"XPlat Code Coverage\" | grep -q 'Line coverage.*[8-9][0-9]%\\|100%' || exit 2"
      }
    ],
    "TeammateIdle": [
      {
        "command": "git status --short | grep -v '^??' | wc -l | awk '$1==0 {exit 0} {print \"Uncommitted work\"; exit 2}'"
      }
    ]
  }
}
```

---

## 8. 控制操作

### 8.1 模型选择

Teammate **唔继承** lead 嘅 `/model`。要喺 `/config` 设置 **Default teammate model**，或选 "Default (leader's model)" 跟随 lead。Spawn prompt 入面也可显式：
```text
Use Sonnet for each teammate.
```

### 8.2 Plan Approval（高风险任务必用）

```text
Spawn an architect teammate to refactor authentication.
Require plan approval before any changes.
```
Teammate 留喺 read-only plan mode，lead 审核批准或反馈拒绝。

### 8.3 直接对话 Teammate

- **in-process**：`Shift+Down` 循环切 → 打字发消息 → `Enter` 进入睇 session → `Esc` 中断
- **split-pane**：直接 click 入嗰个 pane

### 8.4 关闭 Teammate / 清场

```text
Ask the researcher teammate to shut down
```

**清场必须由 lead 执行**：
```text
Clean up the team
```
（Teammate cleanup 会留下 inconsistent state）

---

## 9. 官方使用场景

### 9.1 并行 Code Review
```text
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.
```

### 9.2 竞争性假设调查（debug 神技）
```text
Users report the app exits after one message. Spawn 5 teammates
to investigate different hypotheses. Have them talk to each other
to disprove each other's theories, like a scientific debate.
Update findings doc with consensus.
```
精髓：互相 challenge 打破单 agent 嘅 anchoring bias。

---

## 10. Best Practices

| 项 | 建议 |
|----|------|
| Team 大小 | **3-5 个 teammate 最稳**，超过协调成本 > 收益 |
| 任务大小 | 每个 teammate 5-6 个 task 最高产 |
| 文件 ownership | **必须明确分割**，每个 teammate 独占 glob |
| Plan approval | 高风险（migration、API contract、auth）一定 require |
| 新手入门 | 由 review / research 开始，唔写代码嘅任务先体验 |
| Lead 偷跑 | 见 lead 自己动手就提佢 "Wait for your teammates to complete" |
| Permission | 预先批准常用操作，减少 prompt 打断 |

---

## 11. 实验性限制（实操要小心）

| 限制 | 影响 |
|------|------|
| `/resume` `/rewind` 唔恢复 in-process teammate | 恢复后 lead 可能发消息俾已死 teammate → 叫佢 spawn new |
| Task status 可能滞后 | Teammate 偶尔忘记 mark complete，阻塞下游 |
| Shutdown 慢 | Teammate 完成当前 tool call 先关 |
| **一次只能开一个 team** | 创建新 team 必须先 cleanup 旧 |
| **唔支持嵌套 team** | Teammate 不能 spawn 自己嘅 team |
| **Lead 唔可转让** | 创建 team 嗰个 session 永远系 lead |
| Permission 只喺 spawn 时跟 lead | Spawn 完先可单独改个别 teammate |
| Split-pane 限制 | VS Code 内置 terminal、Windows Terminal、Ghostty **唔支持** |

---

## 12. 思维模型

把多 Agent 编排映射到人类团队：

```
开发计划 (Plan)
  └── 阶段 (Phase)
        ├── 独立子任务 → 并行
        │     ├── 任务可切干净 → Subagents (廉价 fan-out)
        │     ├── 任务需独立 build/test → Worktrees (隔离)
        │     └── 任务需互相讨论 → Agent Teams (协同)
        └── 阶段尾审查
              └── 并行 reviewer teammates
                    (security / performance / test coverage 各一个)
```

启发：**如果你会同时分配呢两个任务俾两个唔同嘅工程师，并且佢哋唔需要事先沟通，咁就适合并行**。

---

## 13. 同既有笔记嘅区别

| 笔记 | 重点 |
|------|------|
| 本笔记 | **官方 Agent Teams**（v2.1.32+ 实验功能、tmux 集成、大型项目编排模板） |
| [[Everything Claude Code 多服务编排详解]] | **ECC 第三方** `/orchestrate` 命令（feature/bugfix/refactor/security 流水线） |
| [[ECC 编排实战手册]] | ECC 6 种正交编排模式总览 |
| [[dmux 多Agent并行编排]] | dmux 工具嘅并行 worktree 编排 |
| [[Ralphinho RFC-DAG 编排模式]] | RFC-DAG 风格强制隔离编排 |
| [[Autonomous Agent Harness 自主代理框架]] | 长时间自主运行嘅 harness 设计 |