This commit is contained in:
Yaojia Wang
2026-03-14 20:23:32 +01:00
parent 50d7d1de3d
commit ad79665527
13 changed files with 2724 additions and 0 deletions

View File

@@ -0,0 +1,586 @@
---
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 文档 + 内存传递 |
### 多实例方式 1Agent 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 10secrets注入防护 | security-reviewer | 安全报告修复补丁 |
| deployment-engineer | 部署DockerCI/CD环境配置 | (自定义) | DockerfileGitHub 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-auditorOWASP 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 个核心 Agentarchitect + 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 启用
"
```
### 方式 2Agent 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)