---
created: "2026-03-08 22:15"
type: zettel
tags: [claude-code, multi-agent, orchestration, workflow]
source: "https://github.com/affaan-m/everything-claude-code"
---

# Everything Claude Code 多服务编排详解

ECC 的多服务编排分为两个层次，对应不同命令，加上社区总结的实战模式。

---

## 层次 1：/orchestrate — 单模型多 Agent 流水线

核心思路：把一个复杂任务拆成多个阶段，每个阶段由不同专用 Agent 处理，通过 Handoff 文档传递上下文。

### 4 种预设工作流

| 类型 | Agent 链 | 适用场景 |
|------|----------|----------|
| `feature` | planner → tdd-guide → code-reviewer → security-reviewer | 新功能开发全流程 |
| `bugfix` | planner → tdd-guide → code-reviewer | Bug 调查与修复 |
| `refactor` | architect → code-reviewer → tdd-guide | 安全重构 |
| `security` | security-reviewer → code-reviewer → architect | 安全专项审查 |

### 用法

```bash
# 完整功能开发流水线
/orchestrate feature "添加用户认证系统"

# 自定义 Agent 链
/orchestrate custom "architect,tdd-guide,code-reviewer" "重新设计缓存层"
```

### 执行过程

1. Planner 分析需求 → 生成 Handoff 文档
2. TDD Guide 读取 Handoff → 先写测试再实现 → 生成新 Handoff
3. Code Reviewer 审查 → 发现问题 → 传递给下一个
4. Security Reviewer 安全审计 → 最终报告 (SHIP / NEEDS WORK / BLOCKED)

独立阶段可以并行执行（如 code-reviewer + security-reviewer + architect 同时跑）。

### Handoff 文档格式

```markdown
## HANDOFF: [previous-agent] -> [next-agent]
### Context — 做了什么
### Findings — 关键发现或决策
### Files Modified — 修改的文件
### Open Questions — 未解决的问题
### Recommendations — 建议的下一步
```

---

## 层次 2：/multi-workflow — 多模型协作 6 阶段流水线

核心思路：Claude 作为编排者（Orchestrator），调度 Codex（后端权威）和 Gemini（前端权威）并行工作，最终由 Claude 综合并实施。

### 6 个阶段

```
Research → Ideation → Plan → Execute → Optimize → Review
```

| 阶段 | 做什么 | 谁来做 |
|------|--------|--------|
| 1. Research | 需求理解、上下文收集、打分(0-10) | Claude + MCP |
| 2. Ideation | 技术可行性分析、方案对比 | Codex + Gemini 并行 |
| 3. Plan | 后端架构 + 前端架构分别规划 | Codex + Gemini 并行 |
| 4. Execute | 按计划写代码 | Claude（唯一写代码的） |
| 5. Optimize | 安全/性能/可访问性审查 | Codex + Gemini 并行 |
| 6. Review | 最终验证，对照计划检查完成度 | Claude |

### 关键规则

- **Code Sovereignty**：只有 Claude 能写文件，Codex/Gemini 只输出 Unified Diff（"脏原型"）
- **Trust Rules**：后端听 Codex，前端听 Gemini
- **每阶段评分 < 7 分自动停止**，要求用户确认后才继续
- **Session 复用**：每次调用返回 SESSION_ID，后续阶段用 `resume` 保持上下文

### 用法

```bash
/multi-workflow 开发一个实时聊天功能，包含 WebSocket 后端和 React 前端
```

---

## 多实例 vs 单实例：两种并行模型

编排的底层机制有本质区别，选错方式会浪费 token 或产生文件冲突。

### 模型对比

| | 多实例（Agent Teams / 多终端） | 单实例（Subagent / /orchestrate） |
|---|---|---|
| 进程数 | N 个独立 Claude Code 进程 | 1 个主进程 |
| Context | 每个独立 context window | 共享主进程 context |
| Token 消耗 | 3-7 倍 | 1-2 倍 |
| 文件协调 | git 自动合并 / worktree 隔离 | 主进程统一写入，无冲突 |
| 适合场景 | 大项目、多模块并行开发 | 单功能、流水线审查 |
| 通信方式 | git commit + 共享文档 | Handoff 文档 + 内存传递 |

### 多实例方式 1：Agent Teams（官方实验功能）

一个 Team Lead 进程自动 spawn 多个 Teammate 子进程：
- 每个 Teammate 在独立 context window 中工作
- 通过 git 自动协调：认领任务、合并变更、解决冲突
- 需要启用 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`
- Teammate 通常 20-30 秒内启动，1 分钟内开始产出

### 多实例方式 2：多终端手动运行

```
终端 1: claude → 后端架构
终端 2: claude → 数据库设计
终端 3: claude → 前端开发
终端 4: claude → 测试
```

- 每个终端是一个独立 Claude Code 实例
- 人工协调（通过共享 Plan 文件）
- 用 `claude --worktree` 让每个实例在独立 git worktree 中工作，避免文件冲突

### 单实例方式：Subagent（/orchestrate 和 Agent tool）

`/orchestrate` 在一个主进程内启动子代理：
- 子代理共享同一个会话，各自独立执行
- 主进程统一控制文件写入，不会冲突
- 通过 Handoff 文档在 Agent 间传递上下文
- 独立的子任务可并行（`run_in_background: true`）

### 选择决策

```
项目规模？
├── 小功能（1-3 文件）→ 单实例 /orchestrate feature
├── 中型功能（5-10 文件）→ 单实例 /orchestrate custom（多 Agent 链）
├── 大型模块（10+ 文件）→ 多实例 Agent Teams 或多终端
└── 全栈项目（多模块）→ 多实例 + 文件所有权分配
```

---

## 层次 3：社区实战模式

### 多 Agent 并行调查（Bug Hunt）

启动 5 个 Agent 分别调查不同假设：
- log-analyst: 分析日志模式
- code-archaeologist: 追溯 git 历史
- reproducer: 尝试复现
- db-detective: 检查数据库状态
- network-inspector: 抓包分析

让它们互相"辩论"，交叉验证结论。

### 全栈 7+ Agent 生产级编排

将一个全栈项目拆成 7 个专职 Agent，按依赖关系分 4 个阶段执行，能并行的并行，有依赖的串行。

#### 7 个 Agent 角色定义

| Agent | 职责 | 对应 ECC Agent | 输出物 |
|-------|------|---------------|--------|
| backend-architect | 后端架构：API 设计、服务分层、中间件、错误处理 | architect + planner | API 契约文档、路由定义、Service 接口 |
| database-architect | 数据库架构：Schema 设计、索引、迁移、RLS | database-reviewer | DDL 迁移文件、ER 图、索引策略 |
| frontend-developer | 前端实现：组件、状态管理、路由、UI/UX | code-reviewer (前端) | React/Vue 组件、页面、样式 |
| test-automator | 自动化测试：单元 + 集成 + E2E | tdd-guide + e2e-runner | 测试文件、覆盖率报告 |
| security-auditor | 安全审计：OWASP Top 10、secrets、注入防护 | security-reviewer | 安全报告、修复补丁 |
| deployment-engineer | 部署：Docker、CI/CD、环境配置 | (自定义) | Dockerfile、GitHub Actions、部署脚本 |
| observability-engineer | 可观测性：日志、监控、告警、tracing | (自定义) | 日志配置、Prometheus metrics、告警规则 |

#### 4 阶段执行流程

```
阶段 1 (并行)    阶段 2 (串行)         阶段 3 (串行)      阶段 4 (并行)
┌──────────────┐  ┌───────────────────┐  ┌──────────────┐  ┌─────────────────────┐
│ backend-     │  │                   │  │              │  │ security-auditor    │
│ architect    │──│ frontend-         │──│ test-        │──│ deployment-engineer │
│              │  │ developer         │  │ automator    │  │ observability-      │
│ database-    │  │ (依赖后端API契约) │  │ (依赖实现代码)│  │ engineer            │
│ architect    │  │                   │  │              │  │ (三者可并行)         │
└──────────────┘  └───────────────────┘  └──────────────┘  └─────────────────────┘
```

**阶段 1：架构设计（并行）**
- backend-architect 和 database-architect 同时工作
- backend-architect 输出 API 契约（RESTful 路由、请求/响应类型、中间件链）
- database-architect 输出 Schema DDL、索引策略、RLS 策略
- 两者通过共享的数据模型文档协调
- 产出：`HANDOFF: architects -> frontend-developer`

**阶段 2：前端实现（串行）**
- 依赖阶段 1 的 API 契约和数据模型
- frontend-developer 基于 API 契约生成类型定义和 API client
- 实现页面组件、状态管理、路由
- 产出：`HANDOFF: frontend-developer -> test-automator`

**阶段 3：测试（串行）**
- 依赖阶段 1+2 的全部实现代码
- 写单元测试（后端 Service、前端组件）
- 写集成测试（API 端点 + 数据库）
- 写 E2E 测试（关键用户流程）
- 验证覆盖率 >= 80%
- 产出：`HANDOFF: test-automator -> final-review`

**阶段 4：交付保障（并行）**
- security-auditor：OWASP Top 10 扫描、secrets 检测、依赖漏洞审计
- deployment-engineer：编写 Dockerfile、CI/CD pipeline、环境变量管理
- observability-engineer：配置结构化日志、metrics endpoint、告警规则
- 三者独立，可完全并行

#### 实际实现方式

**方式 A：用 /orchestrate custom**

```bash
# 阶段 1：并行架构设计
/orchestrate custom "architect,database-reviewer" "设计电商平台后端架构和数据库 Schema"

# 阶段 2：前端开发
/orchestrate custom "planner,tdd-guide,code-reviewer" "基于 API 契约实现 React 前端"

# 阶段 3+4：测试 + 安全 + 部署
/orchestrate custom "tdd-guide,e2e-runner,security-reviewer" "编写测试套件并进行安全审计"
```

**方式 B：用 Agent Teams（实验性功能）**

```bash
# 启用 Agent Teams
# 在 settings.json 中设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

# Team Lead 自动协调，启动多个 teammate
# 每个 teammate 在独立 context window 中工作
# 通过 git 自动协调文件修改
```

**方式 C：多终端手动编排**

```
终端 1 (Team Lead):    协调、规划、合并结果
终端 2 (Backend):      后端架构 + API 实现
终端 3 (Database):     Schema + 迁移 + 索引
终端 4 (Frontend):     组件 + 页面 + 状态管理
终端 5 (Testing):      测试编写 + 覆盖率验证
```

#### 关键协调机制

**文件所有权**：每个 Agent 拥有不同的文件集，避免冲突
```
backend-architect:       src/api/**, src/services/**, src/middleware/**
database-architect:      src/db/**, migrations/**, prisma/**
frontend-developer:      src/components/**, src/pages/**, src/hooks/**
test-automator:          tests/**, e2e/**, __tests__/**
security-auditor:        只读审计，不直接改文件
deployment-engineer:     Dockerfile, .github/**, docker-compose.yml
observability-engineer:  src/logging/**, src/metrics/**, alerting/**
```

**Handoff 文档**：每个阶段结束后生成结构化交接文档，包含上下文、发现、修改文件、未解决问题、建议。

**Git Worktree 隔离**：每个 Agent 在独立 worktree 中工作，最后由 Team Lead 合并。

#### 实际注意事项

- Token 消耗：7 个 Agent 约消耗单 Agent 的 5-7 倍 token
- 起步建议：先用 3-4 个核心 Agent（architect + tdd-guide + code-reviewer + security-reviewer），稳定后再扩展
- 协调开销：超过 4-5 个 Agent 后，协调成本开始上升，需权衡
- 适用规模：中大型项目（10+ 文件的功能模块），小功能用 `/orchestrate feature` 更高效

### 最佳实践

- 起步用 3-5 个 Agent，在并行效率和协调成本之间取平衡
- Agent 间通过共享文档（Handoff / Plan 文件）通信
- 用 git worktree 隔离不同 Agent 的工作区，避免冲突
- 每个 Agent 拥有独立的文件集，避免同时编辑同一文件
- 开发时间可缩减约 75%（社区用户反馈）

---

## 全自动编排实操 Prompt

两种方式实现全自动，不需要手动开关实例。

### 方式 1：/orchestrate custom（单实例，求稳）

一条命令，全自动串行执行 Agent 链：

```bash
/orchestrate custom "architect,database-reviewer,planner,tdd-guide,e2e-runner,code-reviewer,security-reviewer" "

## 项目需求
电商平台用户系统

## 功能范围
- 用户注册/登录（JWT）
- 个人资料 CRUD
- 密码重置流程
- 角色权限（admin/user）

## 技术栈
- 后端：Node.js + Express + TypeScript
- 数据库：PostgreSQL + Prisma
- 前端：React + TailwindCSS

## 约束
- RESTful API 设计
- 80%+ 测试覆盖率
- RLS 启用
"
```

### 方式 2：Agent Teams（多实例，求快）

Team Lead 自动 spawn teammate，控制阶段顺序：

```bash
claude "
你是 Team Lead。任务：设计并实现电商平台用户系统。

## 技术栈
- 后端：Node.js + Express + TypeScript
- 数据库：PostgreSQL + Prisma
- 前端：React + TailwindCSS

## 执行计划

### 阶段 1（并行启动 2 个 teammate）
- teammate-1 'backend-architect': 设计 RESTful API 路由、Service 层接口、中间件链。
  输出 API 契约文档到 docs/api-contract.md，实现 src/api/**、src/services/**、src/middleware/**
- teammate-2 'database-architect': 设计用户表 Schema，编写 Prisma migration，定义索引和 RLS。
  输出到 prisma/**、docs/schema.md

等待阶段 1 全部完成后继续。

### 阶段 2（启动 1 个 teammate）
- teammate-3 'frontend-developer': 读取 docs/api-contract.md，生成 API client 和类型。
  实现登录、注册、个人资料、密码重置页面。输出到 src/components/**、src/pages/**、src/hooks/**

等待阶段 2 完成后继续。

### 阶段 3（启动 1 个 teammate）
- teammate-4 'test-automator': 单元测试覆盖 Service 层，集成测试覆盖 API 端点，
  E2E 测试覆盖注册→登录→修改资料流程。覆盖率 >= 80%。输出到 tests/**、e2e/**

等待阶段 3 完成后继续。

### 阶段 4（并行启动 2 个 teammate）
- teammate-5 'security-auditor': 审计全部代码，OWASP Top 10 + secrets 检测。
  输出到 docs/security-report.md
- teammate-6 'deployment-engineer': Dockerfile、docker-compose.yml、GitHub Actions。
  输出到 .github/workflows/**、Dockerfile

## 文件所有权（避免冲突）
- teammate-1: src/api/**, src/services/**, src/middleware/**
- teammate-2: prisma/**, docs/schema.md
- teammate-3: src/components/**, src/pages/**, src/hooks/**, src/lib/api-client.ts
- teammate-4: tests/**, e2e/**
- teammate-5: docs/security-report.md（只读审计）
- teammate-6: Dockerfile, docker-compose.yml, .github/**

## 规则
- 每个阶段必须等前一阶段全部完成
- 每个 teammate 只修改自己负责的文件
- 发现阻塞性问题立即报告，不要猜测
"
```

### Prompt 写作要点

| 要素 | 为什么重要 |
|------|-----------|
| 功能范围 | 明确边界，防止 Agent 做多余的事 |
| 技术栈 | 避免 Agent 自行选型产生冲突 |
| 阶段划分 + 等待指令 | 控制串行/并行顺序 |
| 文件所有权 | 防止多 Agent 同时改同一文件 |
| 输出物路径 | 让下游 Agent 知道去哪里读上游产出 |
| 约束条件 | 覆盖率、安全标准等硬性要求 |

### 两种方式对比

| | /orchestrate custom | Agent Teams |
|---|---|---|
| 自动化程度 | 全自动 | 全自动 |
| 并行能力 | 有限（子代理级） | 真并行（多进程） |
| 速度 | 串行为主，较慢 | 并行阶段快 3-5 倍 |
| Token 消耗 | 1-2 倍 | 3-7 倍 |
| 稳定性 | 成熟稳定 | 实验性功能 |
| 上手难度 | 零配置 | 需启用实验 flag |

---

## 全新项目开发策略

### 单个功能：直接 /orchestrate feature

```bash
/orchestrate feature "Add JWT-based user authentication with login, register, password reset"
```

4 个 Agent 依次执行：

1. **Planner** — 规划出 controller、service、middleware、routes 等文件结构
2. **TDD Guide** — 先写 `auth.test.ts`，再写 `auth.service.ts`、`auth.controller.ts`
3. **Code Reviewer** — 检查错误处理、输入验证、代码质量
4. **Security Reviewer** — 检查 JWT 存储、密码哈希、CSRF、rate limiting

### 整个项目：先 /plan 拆分，再逐模块 /orchestrate

```bash
# 第 1 步：整体规划，拆分模块
/plan "电商平台：用户系统 + 商品管理 + 订单系统 + 支付集成"

# 第 2 步：按模块逐个走完整流水线
/orchestrate feature "用户注册登录系统"
/orchestrate feature "商品 CRUD 和分类管理"
/orchestrate feature "购物车和订单流程"
/orchestrate feature "支付网关集成"
```

### 需要架构设计时：自定义 Agent 链

全新项目往往需要先做架构决策，在链头加上 architect：

```bash
/orchestrate custom "architect,planner,tdd-guide,code-reviewer,security-reviewer" "设计并实现微服务网关"
```

### 前后端全栈：用 /multi-workflow

当前后端都要从头开发时，用多模型协作更高效：

```bash
/multi-workflow "电商平台用户系统，包含 React 前端和 Node.js 后端"
```

Codex 负责后端架构，Gemini 负责前端设计，Claude 综合实施。

### 选择决策树

```
全新项目？
├── 单个功能 → /orchestrate feature
├── 多模块项目 → /plan 拆分 → 逐个 /orchestrate feature
├── 需要架构设计 → /orchestrate custom (加 architect)
└── 前后端全栈 → /multi-workflow
```

---

## 阶段追踪最佳实践

ECC 本身没有内建 Kanban/Sprint board，但可以组合 3 层机制实现"完成一个阶段就 mark 完成"的效果。

### 3 层机制

| 层 | 机制 | 属于 | 作用 |
|---|------|------|------|
| 1 | TaskCreate + TaskUpdate | Claude Code 原生（v2.1.16+） | 状态追踪 + 依赖关系 + 跨 session 持久化 |
| 2 | `/checkpoint` | ECC | Git 级别快照，可回滚 |
| 3 | Handoff 文档 | ECC `/orchestrate` | Agent 间上下文传递 |

### Claude Code 原生 Tasks 系统

取代了旧的 TodoWrite，是最接近 Kanban 的原生机制：

```
TaskCreate("backend-architecture")
  → TaskUpdate(status: in_progress)    # 开始时标记
  → TaskUpdate(status: completed)       # 完成时标记
```

核心能力：
- **依赖关系**：`addBlockedBy` 让阶段 2 等阶段 1 完成
- **跨 session 持久化**：context 压缩后 task 状态不丢
- **跨实例共享**：设置 `CLAUDE_CODE_TASK_LIST_ID` 环境变量，多个 Claude 实例看到同一个任务板
- **3-Task 规则**：少于 3 步的直接做，不值得建 task

### 组合实践：/orchestrate + Tasks + /checkpoint

在 `/orchestrate` 的 prompt 中加入 Task 追踪指令：

```bash
/orchestrate custom "architect,database-reviewer,planner,tdd-guide,code-reviewer,security-reviewer" "

## 项目需求
电商平台用户系统

## 技术栈
Node.js + Express + TypeScript + PostgreSQL + Prisma + React

## 阶段追踪要求
每个 Agent 开始时：
1. TaskCreate 创建当前阶段任务
2. TaskUpdate 标记 in_progress
3. 如果依赖前一阶段，用 addBlockedBy 关联

每个 Agent 完成时：
1. /checkpoint create 'phase-N-done'
2. TaskUpdate 标记 completed
3. 生成 Handoff 文档传递给下一个 Agent
"
```

### Agent Teams + 共享 Task Board

多实例场景下，用共享 Task 列表实现自动阶段协调：

```bash
# 所有实例共享同一个任务板
export CLAUDE_CODE_TASK_LIST_ID="ecommerce-user-system"

claude "
你是 Team Lead。

## 任务追踪规则
- 用 TaskCreate 为每个阶段创建任务，带依赖关系
- teammate 开始工作时 TaskUpdate → in_progress
- teammate 完成后 TaskUpdate → completed
- 所有 teammate 共享同一个 CLAUDE_CODE_TASK_LIST_ID
- 通过 Task 状态判断前置阶段是否完成，自动启动下一阶段

## 阶段依赖
- Task: 'backend-architecture' → teammate-1
- Task: 'database-schema' → teammate-2
- Task: 'frontend' (blockedBy: backend-architecture, database-schema) → teammate-3
- Task: 'testing' (blockedBy: frontend) → teammate-4
- Task: 'security-audit' (blockedBy: testing) → teammate-5
- Task: 'deployment' (blockedBy: testing) → teammate-6
"
```

Team Lead 通过 Task 状态自动判断何时启动下一阶段，不需要人工干预。

### 追踪机制选择

| 需求 | 用什么 |
|------|--------|
| 阶段状态（pending/in_progress/completed） | TaskCreate + TaskUpdate（原生） |
| 阶段间依赖 | addBlockedBy（原生） |
| 多实例共享进度 | CLAUDE_CODE_TASK_LIST_ID（原生） |
| Git 级别快照回滚 | `/checkpoint`（ECC） |
| Agent 间上下文传递 | Handoff 文档（ECC `/orchestrate`） |
| 自主循环 + 质量门禁 | `/loop-start` + `/quality-gate`（ECC） |
| 完整 Kanban 3 文件看板 | planning-with-files（第三方插件，非 ECC） |

---

## 命令选择速查

| 场景 | 用哪个 |
|------|--------|
| 单个功能从规划到上线 | `/orchestrate feature` |
| 修 Bug 全流程 | `/orchestrate bugfix` |
| 安全重构 | `/orchestrate refactor` |
| 前后端都要改，多 AI 协作 | `/multi-workflow` |
| 只要多模型并行出方案 | `/multi-plan` |
| 只要多模型并行写代码 | `/multi-execute` |

---

## Related

- [[Everything Claude Code 用法速查]]
- [[Everything Claude Code Agent 编排模式]]
- [[Everything Claude Code 完整指南]]

## Source

- [Claude Code Task Management 原生指南](https://claudefa.st/blog/guide/development/task-management)
- [Claude Code Tasks 更新公告](https://venturebeat.com/orchestration/claude-codes-tasks-update-lets-agents-work-longer-and-coordinate-across)
- [Claude Code Checkpointing 官方文档](https://code.claude.com/docs/en/checkpointing)
- [Claude Code Agent Teams 官方文档](https://code.claude.com/docs/en/agent-teams)
- [Claude Code 多 Agent 编排完整指南 2026](https://www.eesel.ai/blog/claude-code-multiple-agent-systems-complete-2026-guide)
- [Shipyard: Multi-agent orchestration](https://shipyard.build/blog/claude-code-multi-agent/)
- [10+ Claude 实例并行编排实战](https://dev.to/bredmond1019/multi-agent-orchestration-running-10-claude-instances-in-parallel-part-3-29da)
- [Claude Code Swarm 编排 Skill](https://gist.github.com/kieranklaassen/4f2aba89594a4aea4ad64d753984b2ea)
- [Ruflo: Agent 编排平台](https://github.com/ruvnet/ruflo)
- [Claude Code Workflow 框架](https://github.com/catlog22/Claude-Code-Workflow)