ECC /workflow 命令实战：多模型协作开发工作流（六阶段质量门 + Codex/Gemini/Claude 分工）

本篇指南围绕 ECC 仓库中的 /workflow 多模型协作开发命令展开（西班牙语规范文档见 docs/es/commands/multi-workflow.md，英文权威命令源文件为 commands/multi-workflow.md）。读完你可以掌握：如何以 /workflow <任务描述> 触发"研究 → 构思 → 计划 → 执行 → 优化 → 评审"的六阶段流水线；如何为外部模型（Codex 负责后端、Gemini 负责前端）与 Claude 编排设定明确的"代码主权"边界；以及如何通过需求完整性评分、SESSION_ID 会话复用与 TaskOutput 等待纪律，让整条流程可中断、可恢复、可验证。

命令定位：一个带质量门的六阶段开发流水线

/workflow 是 ECC 提供的多模型协作开发工作流，其核心设计是把一次完整的特性开发拆成六个严格有序的阶段，并嵌入质量门（quality gates）：

Research（研究）→ Ideation（构思）→ Plan（计划）→ Execute（执行）→ Optimize（优化）→ Review（评审）

使用方式非常直接，任务描述作为位置参数传入：

/workflow <descripción de la tarea>

三个关键定位（来自 docs/es/commands/multi-workflow.md 的 Context 小节）：

• 待开发任务即命令参数 $ARGUMENTS；
• 六阶段结构化流程，每阶段之间设有质量门；
• 多模型协作分工：Codex（后端）+ Gemini（前端）+ Claude（编排），并支持可选的 MCP 服务（ace-tool）增强能力。

关于模型分工，文档明确了"信任等级"：

模型	角色定位	信任规则
Codex	后端逻辑、算法、调试	后端权威（Backend authority），意见可信
Gemini	前端 UI/UX、视觉设计	前端专家；其对后端的意见仅作参考
Claude（自身）	编排、规划、执行、交付	唯一持有文件系统写权限的角色

版本差异说明：西班牙语文档的前端路由写的是 Gemini（"Frontend → Gemini"），而英文源命令 commands/multi-workflow.md 中同一前端角色写的是 Antigravity（"Frontend → Antigravity"）。两者是同一流程的不同版本表述，机制（前端权威模型 + 后端权威模型 + Claude 编排）完全一致，阅读时按此对应即可。

前置条件：ccg-workflow 运行时

英文源命令在文档开头给出了硬性前置条件（西班牙语版省略了该段，但属于该命令族的通用前提）：本命令依赖外部 ccg-workflow 运行时，它不属于 ECC 基础安装的一部分。需要先执行初始化：

npx ccg-workflow

该初始化会生成命令所依赖的两类资源：

• ~/.claude/bin/codeagent-wrapper：统一的后端调用封装脚本；
• ~/.claude/.ccg/prompts/*：按角色划分的提示词文件（analyzer / architect / reviewer 等）。

没有这个运行时，/workflow 无法正确运行。这一前提在 commands/multi-workflow.md、commands/multi-plan.md、commands/multi-execute.md 等整个 multi-* 命令族中均以相同的 Prerequisite 段落声明，可以确认这是整个命令族的统一要求。

通信规范：模式标签与强制停止

/workflow 要求 Claude 以**编排者（Orquestador / Orchestrator）**身份运行，并遵守一组通信与停止纪律：

1. 模式标签：每条回复以 [Modo: X]（英文源为 [Mode: X]）开头，初始标签为 [Modo: Investigación]（[Mode: Research]）；
2. 严格顺序：Investigación → Ideación → Plan → Ejecución → Optimización → Revisión，不得跳序；
3. 逐阶段确认：每完成一个阶段，向用户请求确认后再进入下一阶段；
4. 强制停止：当需求完整性评分 < 7，或用户不批准时，必须停下来（force stop），不得"带病前进"。

英文源命令还补充了一条：需要与用户交互（确认/选择/批准）时，使用 AskUserQuestion 工具，而不是在正文里裸问。

这套规则的本质是一个止损机制（Stop-Loss Mechanism）：当前阶段输出未通过验证前，不得进入下一阶段。同一机制也出现在 commands/multi-plan.md 的 Core Protocols 中（"Do not proceed to next phase until current phase output is validated"），可见它是整个多模型命令族的通用纪律，而非单条命令的局部约定。

六阶段流程逐段解析

以下逐阶段拆解。评分维度、并行调用对象、会话保存点均以 docs/es/commands/multi-workflow.md 的 Flujo de Ejecución 小节为准，并在需要处对照英文源命令补充调用细节。

阶段 1：研究与分析（Investigación）

[Modo: Investigación] —— 理解需求并收集上下文，共三步：

1. Prompt 增强（可选）：若 ace-tool MCP 可用，先调用 mcp__ace-tool__enhance_prompt，并用增强结果替换原始 $ARGUMENTS，供后续所有 Codex/Gemini 调用使用；不可用时则原样使用 $ARGUMENTS。
2. 上下文检索：若 ace-tool MCP 可用则调用 mcp__ace-tool__search_context；不可用时回退到内置工具组合：
   • Glob 做文件发现；
   • Grep 做符号搜索；
   • Read 收集上下文；
   • Task（Explore agent）做更深入的代码库探索。
3. 需求完整性评分（0–10 分），四个维度：

维度	分值
目标清晰度（Claridad del objetivo / Goal clarity）	0–3
预期结果（Resultado esperado / Expected outcome）	0–3
范围边界（Límites del alcance / Scope boundaries）	0–2
约束条件（Restricciones / Constraints）	0–2

质量门判定：总分 ≥ 7 才能继续；< 7 必须停止，向用户提出澄清问题。这是整条流水线的第一道、也是最关键的一道质量门——它把"需求是否说清楚了"这个最容易含糊的问题，量化成了一个可执行的数字门槛。

阶段 2：方案构思（Ideación）

[Modo: Ideación] —— 多模型并行分析：

• 并行调用（run_in_background: true）：
  • Codex：输出技术可行性、候选方案、风险评估（使用 analyzer 角色提示词）；
  • Gemini：输出 UI 可行性、候选方案、UX 评估（使用 analyzer 角色提示词）。
• 两个调用各返回 SESSION_ID: xxx，必须分别保存为 CODEX_SESSION 与 GEMINI_SESSION（英文源中对应变量为 ANTIGRAVITY_SESSION），供阶段 3 与阶段 5 的 resume 复用。
• 汇总两路分析后，输出至少两个可选方案对比，等待用户选择。

阶段 3：详细计划（Plan）

[Modo: Plan] —— 多模型协作规划：

• 并行调用（复用会话）：用 resume <SESSION_ID> 续接阶段 2 的会话：
  • Codex：architect 角色，输出后端架构；
  • Gemini：architect 角色，输出前端架构。
• Claude 综合：采纳 Codex 的后端计划 + Gemini 的前端计划，形成统一方案；用户批准后落盘到 .claude/plan/<task-name>.md。

这里体现了流程的"智能路由"思想：同一个任务里，后端问题以后端权威模型为准、前端问题以后端权威模型为准，Claude 只做综合与裁决，不越权代答。

阶段 4：实现（Ejecutar）

[Modo: Ejecutar] —— 代码开发阶段，纪律非常克制：

• 严格遵循已批准的计划；
• 遵循项目现有的代码标准；
• （英文源补充）在关键里程碑处主动向用户请求反馈。

这是六阶段中唯一由 Claude 独立承担写入的落地阶段——外部模型在此阶段不直接产出代码文件，代码主权始终在 Claude 手中。

阶段 5：代码优化（Optimizar）

[Modo: Optimizar] —— 多模型并行评审，两路关注点刻意错开：

• Codex：安全、性能、错误处理；
• Gemini：可访问性（accessibility）、设计一致性。

评审意见汇总后，经用户确认再执行优化，避免"评审即改写"。

阶段 6：质量评审（Revisión）

[Modo: Revisión] —— 最终评估，四项动作：

1. 对照计划核查完成度；
2. 运行测试验证功能；
3. 报告问题与建议；
4. （英文源补充）请求用户的最终确认，完成闭环。

多模型调用协议：codeagent-wrapper、角色提示词与会话复用

西班牙语文档以阶段化叙述为主，具体的调用语法、角色提示词路径与后台任务等待纪律，可以在英文源命令 commands/multi-workflow.md 的 "Multi-Model Call Specification" 一节找到完整定义。它们是让 /workflow 真正可执行的底层协议。

统一调用语法

新建会话与续接会话两种形态，均通过 Bash 工具执行 codeagent-wrapper，以 heredoc 传入结构化任务体：

# 新建会话调用（并行时 run_in_background: true，串行时 false）
Bash({
  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|antigravity> - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
  run_in_background: true,
  timeout: 3600000,
  description: "Brief description"
})

# 续接会话调用
Bash({
  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|antigravity> resume <SESSION_ID> - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
  run_in_background: true,
  timeout: 3600000,
  description: "Brief description"
})

任务体由四个约定段组成：ROLE_FILE 指定角色提示词路径；<TASK> 内嵌 Requirement:（需求，优先用阶段 1 增强后的版本）与 Context:（前序阶段沉淀的项目上下文）；OUTPUT: 声明期望的输出格式，把"模型该交付什么"显式化。

两个值得注意的参数细节：

• 模型参数：--backend antigravity 与 --backend codex 都不需要额外模型标志，codeagent-wrapper 会自动选择各后端的默认模型——也就是说模型选择被封装在 wrapper 内，编排层不关心具体模型名；
• 超时：Bash 调用设 timeout: 3600000（一小时），因为外部模型的规划/评审任务耗时不可控，短超时会把流水线打断。

角色提示词矩阵

各阶段使用的角色提示词按"后端 × 阶段"二维组织（英文源的路径表；西班牙语流程中 Gemini 对应同一张表的前端列）：

阶段	Codex	Antigravity（ES 文档中为 Gemini）
分析（Analysis）	~/.claude/.ccg/prompts/codex/analyzer.md	~/.claude/.ccg/prompts/antigravity/analyzer.md
规划（Planning）	~/.claude/.ccg/prompts/codex/architect.md	~/.claude/.ccg/prompts/antigravity/architect.md
评审（Review）	~/.claude/.ccg/prompts/codex/reviewer.md	~/.claude/.ccg/prompts/antigravity/reviewer.md

这解释了六阶段与提示词的对应关系：阶段 2（构思）用 analyzer，阶段 3（计划）用 architect，阶段 5（优化）用 reviewer。

会话复用：resume 而不是 --resume

每次调用会返回 SESSION_ID: xxx。后续阶段必须用 resume xxx 子命令续接（文档特别强调是 resume，不是 --resume），这样同一后端模型在构思→计划→优化三个阶段间保持上下文连续性，减少重复喂入项目背景，也让"它前面建议过什么"成为可追溯的状态。

后台任务的等待纪律（TaskOutput）

并行调用以 run_in_background: true 启动后，必须用 TaskOutput 阻塞等待全部模型返回，才能进入下一阶段：

TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })

文档为此写死了三条纪律（标注为 IMPORTANT）：

• 必须显式指定 timeout: 600000（10 分钟），否则默认 30 秒会过早超时；
• 10 分钟后仍未完成，继续用 TaskOutput 轮询，绝不杀掉进程；
• 若因超时跳过了等待，必须调用 AskUserQuestion 让用户决定继续等待还是终止任务，不得直接 kill。

这套纪律的意图很明确：外部模型任务是不可被"随手打断"的重型资源，编排者对后台任务只有"等待/询问"两种合法操作，没有"强杀"这一项。

外部编排出口：tmux + git worktree 的并行工作树

西班牙语文档聚焦会话内编排，而英文源命令多出一个 "When to Use External Orchestration" 出口：当工作必须拆给需要隔离 git 状态、独立终端或独立构建/测试执行的并行 worker 时，使用外部 tmux/worktree 编排；而当主会话仍是唯一写入者、只涉及轻量分析/规划/评审时，用进程内子代理即可。

示例命令：

node scripts/orchestrate-worktrees.js .claude/plan/workflow-e2e-test.json --execute

这条命令在仓库中有真实的实现支撑：

• scripts/orchestrate-worktrees.js 是 CLI 入口，解析 <plan.json> 与 --execute / --write-only 参数；不带 flag 时只打印 dry-run 计划（git 命令 + tmux 命令预览），--write-only 只落盘协调文件，--execute 才真正启动。
• 其底层逻辑来自 scripts/lib/tmux-worktree-orchestrator.js 中的 buildOrchestrationPlan（构建编排计划）、materializePlan（物化任务/交接/状态文件）、executePlan（启动 tmux 会话）三个函数；每个 worker 拥有独立的 worktree 路径、分支名、任务文件与交接文件，launcherCommand 支持 {worktree_path}、{branch_name}、{task_file} 等占位符。
• 执行完成后，脚本会打印会话名与协调目录，并提示用 tmux attach -t <session> 接管观察。
• 对应测试位于 tests/lib/tmux-worktree-orchestrator.test.js，说明该编排路径经过了测试覆盖。

从源码结构看，/workflow 因此具备两级编排能力：会话内的多模型并行（codeagent-wrapper 后台任务），以及仓库级的多 worker 并行（worktree 隔离），两者按"是否需要隔离 git 状态"来切换。

与 /multi-* 命令族的关系

/workflow 不是孤立命令，而是 multi-* 命令族的全流程整合版。同一目录下还有四条单职责命令，与它共享同一套 ccg-workflow 运行时、codeagent-wrapper 调用语法、角色提示词矩阵与 SESSION_ID 交接协议：

命令	源文件	职责	与 /workflow 的关系
/multi-plan	commands/multi-plan.md	只做计划，禁止修改生产代码，产出 .claude/plan/<feature>.md + 两个 SESSION_ID	对应阶段 1–3 的独立形态
/multi-execute	commands/multi-execute.md	读取计划文件 → 取原型 Diff → Claude 重构落地 → 双模型审计	对应阶段 4–6 的独立形态
/multi-frontend	commands/multi-frontend.md	前端主导的六阶段流程（Antigravity 牵头，Codex 仅参考）	前端任务的单侧特化
/multi-backend	commands/multi-backend.md	后端主导的六阶段流程（Codex 牵头，前端模型仅参考）	后端任务的单侧特化

几条贯穿整个命令族的协议值得单独强调：

• Planning Only 纪律：/multi-plan 明确规定只允许读上下文、只允许写 .claude/plan/* 计划文件，"NEVER modify production code"，且计划产出后必须立即结束当前响应，不得追问"Y/N"后自动执行——执行是 /multi-execute 的职责。
• Dirty Prototype Refactoring：/multi-execute 把外部模型返回的 Unified Diff 定位为"脏原型"，Claude 必须先做"心理沙盘"（模拟应用 Diff、检查逻辑一致性与副作用），再重构成企业级代码、最小化改动范围，然后才允许落盘；落盘后还必须强制再发起一轮双模型 Code Review（Codex 查安全/性能/错误处理，前端模型查可访问性/设计一致性），循环直至风险可接受。
• 模型路由参考：仓库另有一个轻量命令 commands/model-route.md，按任务复杂度与预算推荐模型档位（haiku：确定性低风险机械修改；sonnet：默认实现与重构；opus：架构、深度评审、模糊需求），可作为规划阶段评估"该阶段值不值得投入强模型"的辅助工具。

三条关键规则（Key Rules）

西班牙语文档结尾给出的三条硬规则，是整个 /workflow 的宪法，值得原样保留：

1. 阶段顺序不可跳过——除非用户明确指示；
2. 外部模型对文件系统零写权限（zero filesystem write access）——所有文件修改一律由 Claude 执行；
3. 强制停止——评分 < 7 或用户不批准时，立即停下。

规则 2 是这个设计里最反直觉、也最重要的一条：Codex 与 Gemini 无论"多聪明"，在这套流程里都是只读顾问。它们的产出（分析、Diff 建议、评审意见）必须经过 Claude 的理解、重构与最小化裁剪才能进入代码库。这既保证了单一写入者（single writer）可审计，也避免了多模型并发写文件导致的相互覆盖。

延伸阅读：仓库中的相关路径

资源	路径	说明
西语规范文档（本文主文档）	docs/es/commands/multi-workflow.md	六阶段流程、评分维度、关键规则的西班牙语表述
英文源命令	commands/multi-workflow.md	调用语法、角色提示词表、TaskOutput 纪律、worktree 编排出口
计划 / 执行单侧命令	commands/multi-plan.md、commands/multi-execute.md	Planning-Only 纪律与 Dirty Prototype 重构流程
前端 / 后端单侧命令	commands/multi-frontend.md、commands/multi-backend.md	单侧主导的六阶段变体
worktree 编排 CLI	scripts/orchestrate-worktrees.js	dry-run / write-only / execute 三模式入口
worktree 编排核心库	scripts/lib/tmux-worktree-orchestrator.js	buildOrchestrationPlan / materializePlan / executePlan
编排测试	tests/lib/tmux-worktree-orchestrator.test.js	worktree 编排路径的测试覆盖
命令注册表	docs/COMMAND-REGISTRY.json	全量命令的注册与索引

小结

/workflow 的价值不在于"调用了更多模型"，而在于它把多模型协作变成了一条有门槛、有分工、有审计的工程流水线：阶段 1 的需求评分门挡住模糊需求，信任等级表（后端听 Codex、前端听前端权威模型）裁决模型间分歧，SESSION_ID 复用保证跨阶段上下文不丢失，TaskOutput 等待纪律保证重型后台任务不被误杀，"外部模型零写权限 + Claude 统一落地"保证代码库始终只有一个写入者。配合 /multi-plan、/multi-execute 的单侧拆分和 worktree 外部编排出口，这套机制覆盖了从轻量单模型分析到多 worker 隔离并行的完整谱系。适用前提需要再次明确：运行该命令前必须先完成 npx ccg-workflow 初始化，获得 codeagent-wrapper 与角色提示词文件，否则命令无法正常工作。