knowledge-base/4 - Resources/Claude-Code/Claude Code Agent Teams 官方多Agent编排.md

created, type, tags, source

created	type	tags	source
2026-05-16	resource	resource claude-code agent-teams orchestration multi-agent tmux subagents official workflow	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：

{
  "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 启动 / 重接

# 首次创建（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）：

---
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 入面引用

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，呢个系防冲突嘅唯一可靠方法。

   # 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 模板

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：

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）：

{
  "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 入面也可显式：

Use Sonnet for each teammate.

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

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 / 清场

Ask the researcher teammate to shut down

清场必须由 lead 执行：

Clean up the team

（Teammate cleanup 会留下 inconsistent state）

---

9. 官方使用场景

9.1 并行 Code Review

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 神技）

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 设计