Merge remote-tracking branch 'origin/main'
# Conflicts: # 4 - Resources/Claude-Code/Everything Claude Code 完整指南.md
This commit is contained in:
Yaojia Wang
416
4 - Resources/Claude-Code/Claude Code Agent Teams 官方多Agent编排.md
Normal file
416
4 - Resources/Claude-Code/Claude Code Agent Teams 官方多Agent编排.md
Normal file
@@ -0,0 +1,416 @@
|
||||
---
|
||||
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 设计 |
|
||||
Reference in New Issue
Block a user