knowledge-base/6 - Zettelkasten/20260308221500 Everything Claude Code 多服务编排详解.md

created, type, tags, source

created	type	tags	source
2026-03-08 22:15	zettel	claude-code multi-agent orchestration workflow	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	安全专项审查

用法

# 完整功能开发流水线
/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 文档格式

## 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 保持上下文

用法

/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

# 阶段 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（实验性功能）

# 启用 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 链：

/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，控制阶段顺序：

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

/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

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

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

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

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

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

前后端全栈：用 /multi-workflow

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

/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 追踪指令：

/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 列表实现自动阶段协调：

# 所有实例共享同一个任务板
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 原生指南
• Claude Code Tasks 更新公告
• Claude Code Checkpointing 官方文档
• Claude Code Agent Teams 官方文档
• Claude Code 多 Agent 编排完整指南 2026
• Shipyard: Multi-agent orchestration
• 10+ Claude 实例并行编排实战
• Claude Code Swarm 编排 Skill
• Ruflo: Agent 编排平台
• Claude Code Workflow 框架