ruflo SPARC 方法学编排器:五阶段质量门与多智能体协调开发指南

本文围绕 ruflo 仓库中的 SPARC 方法学编排 Agent 模板 sparc-coordinator.md 展开,讲解它如何用 Specification(规格)、Pseudocode(伪代码)、Architecture(架构)、Refinement(精炼)、Completion(完成) 五个阶段加四道质量门的流水线,把一次功能开发拆解为可追踪、可并行、可验证的多智能体协作流程。读完后,你将掌握 SPARC 五阶段的进入/退出条件、各阶段专职 Agent 的职责划分与并行执行模式,并能结合 ruflo 的插件命令(如 sparc init / sparc advance)在 Claude Code 环境中实际驱动一整轮 SPARC 开发周期。

一、SPARC 编排 Agent 的定位

sparc-coord 是 ruflo 提供的一个 Agent 模板,其 frontmatter 定义如下:

---
name: sparc-coord
description: SPARC methodology orchestrator for systematic development phase coordination
---

它的职责原文表述为:"编排完整的 SPARC(Specification, Pseudocode, Architecture, Refinement, Completion)方法学,确保系统性、高质量的软件开发"。也就是说,它本身不写业务代码,而是作为"总指挥"驱动五个阶段按序推进,在阶段边界执行质量门检查,并调度各阶段专职 Agent 完成具体工作。

在仓库中,这个模板属于 .claude/agents/templates/ 目录下的可复用编排模板之一(同目录还有 orchestrator-task.md、coordinator-swarm-init.md 等协调类模板);而 SPARC 各阶段的"执行者"则分别存放在 specification.md、pseudocode.md、architecture.md、refinement.md 以及模板目录下的 implementer-sparc-coder.md。此外,ruflo 还以插件形式发布了同一套方法学的工程化实现 plugins/ruflo-sparc,二者构成"模板 + 插件"的呼应关系,本文会在对应章节交叉印证。

二、SPARC 五阶段总览

模板文档对每个阶段给出了明确的活动清单,这是理解整套编排的前提。

1. Specification(规格)阶段

• 详细的需求收集(Detailed requirements gathering)
• 用户故事创建(User story creation)
• 验收标准定义(Acceptance criteria definition)
• 边界情况识别(Edge case identification)

对应的专职 Agent specification.md 进一步规定了产出物形态:功能/非功能需求(带 FR-xxx / NFR-xxx 编号与优先级)、约束分析(技术/业务/合规三类)、用例定义(前置条件、主流程、后置条件、异常分支)、Gherkin 风格的验收场景(如登录成功、密码错误两个 Scenario)、以及"所有需求可测试、边界情况已记录、干系人已批准"的完成检查清单。

2. Pseudocode(伪代码)阶段

• 算法设计(Algorithm design)
• 逻辑流规划(Logic flow planning)
• 数据结构选择(Data structure selection)
• 复杂度分析(Complexity analysis)

阶段 Agent pseudocode.md 要求伪代码保持语言无关,并给出四类标准:结构化算法伪代码(如 AuthenticateUser 的完整 BEGIN/END 流程)、数据结构选型(如 LRU+TTL 用户缓存、Trie 权限树,并注明 get/set/evict 的 O(1) 复杂度)、算法模式(令牌桶限流的完整伪代码)、以及复杂度分析(如"认证流程总时间复杂度 O(log n)"的推导)。

3. Architecture(架构)阶段

• 系统设计(System design)
• 组件定义(Component definition)
• 接口契约(Interface contracts)
• 集成规划(Integration planning)

阶段 Agent architecture.md 定义了六类架构产出物:Mermaid 高层架构图(客户端层/API 网关/应用层/数据层/基础设施)、YAML 组件定义(职责、REST/gRPC/事件接口、依赖、水平扩缩容指标)、SQL 数据架构(含分区表策略)、OpenAPI 接口契约、Kubernetes 部署架构、以及安全架构(JWT/OAuth2/MFA、RBAC、加密与合规要求)。

4. Refinement(精炼)阶段

• TDD 实现(TDD implementation)
• 迭代改进(Iterative improvement)
• 性能优化(Performance optimization)
• 代码质量增强(Code quality enhancement)

阶段 Agent refinement.md 把该阶段落地为 Red-Green-Refactor 三步:先写会失败的测试(如"连续 5 次失败后锁定账户")、再写最小实现使其变绿、最后在测试保持绿色的前提下重构(提取 validateLoginAttempt、引入事件总线等)。此外还包含性能优化前后对比(N+1 查询改单条 JOIN + 缓存)、错误层级与全局错误处理、重试装饰器与熔断器、80% 覆盖率阈值的 Jest 配置、以及圈复杂度从 7 降到 2 的重构示例。

5. Completion(完成)阶段

• 集成测试(Integration testing)
• 文档定稿(Documentation finalization)
• 部署准备(Deployment preparation)
• 交接流程(Handoff procedures)

需要说明的是,.claude/agents/sparc/ 目录只提供了前四个阶段的专职 Agent,Completion 阶段在插件侧由 reviewer 角色承担最终审计、文档审查与部署就绪检查(见下文 sparc-orchestrator.md 的 Phase 5 定义)。

三、编排工作流:阶段转换与质量门

阶段转换流水线

模板给出的核心编排流程是一张阶段转换图:

Specification → Quality Gate 1 → Pseudocode
     ↓
Pseudocode → Quality Gate 2 → Architecture
     ↓
Architecture → Quality Gate 3 → Refinement
     ↓
Refinement → Quality Gate 4 → Completion
     ↓
Completion → Final Review → Deployment

即每个阶段结束后必须先通过一道质量门(Quality Gate)才能进入下一阶段,最后一道门之后还有 Final Review 再到 Deployment。

五道质量门的判定标准

模板原文列出的质量门:

1. Specification Complete:所有需求已文档化
2. Algorithms Validated:逻辑已验证并优化
3. Design Approved:架构已评审并被接受
4. Code Quality Met:测试通过、覆盖率达标
5. Ready for Production:所有标准均满足

插件版编排器 sparc-orchestrator.md 把这些门细化成了可机检的量化判据,与模板形成一一对应:

阶段	质量门判据(插件版细化)
1 Specification	至少 3 条验收标准、显式约束、已识别边界情况、干系人签署记录
2 Pseudocode	覆盖规格中全部验收标准、错误路径显式、复杂度已标注
3 Architecture	响应规格全部约束、API 契约有类型、无循环依赖、DDD 不变量已记录
4 Refinement	每条验收标准有通过的测试、代码评审无关键问题、覆盖率 ≥ 80%
5 Completion	全部测试绿色、文档完整、部署清单核对、可追溯矩阵把每条验收标准链接到测试

门检查协议(Gate Check Protocol)

从源码结构看,插件版编排器为"门检查"定义了统一的五步协议(见 sparc-orchestrator.md):

1. 从记忆命名空间 sparc-phases 中取回本阶段产物;
2. 逐条评估门判据——任何一条不满足即整门失败,不存在部分通过;
3. 把门结果(通过/失败 + 明细)写入 sparc-gates 命名空间,键格式为 gate-{phase}-{feature-slug}-{timestamp},值为 { phase, passed, criteria: [{name, passed, detail}], blockers: [] };
4. 失败时:定位缺口、给出可执行的改进反馈、退回当前阶段;
5. 成功时:推进阶段计数器、通知用户、进入下一阶段。

这套协议解释了模板中"Enforce quality gates - No shortcuts"(强制执行质量门,不走捷径)这一最佳实践是如何落地的:门结果本身也是一等公民产物,带时间戳存入记忆,保证可审计。

四、多智能体协调:专职 Agent 与并行模式

五个专职 SPARC 角色

模板将执行角色划分为:

1. SPARC Researcher:需求与可行性分析
2. SPARC Designer:架构与接口设计
3. SPARC Coder:实现与精炼
4. SPARC Tester:质量保证
5. SPARC Documenter:文档与指南

仓库中这些角色有具体的落点:研究/规划/编码/测试/评审的通用 Agent 位于 core/researcher.md、core/planner.md、core/coder.md、core/tester.md、core/reviewer.md,SPARC 专用的实现专家是 implementer-sparc-coder.md。插件版编排器则按阶段显式声明了 spawn 映射:Phase 1 → researcher,Phase 2 → planner,Phase 3 → system-architect,Phase 4 → coder + tester,Phase 5 → reviewer,每个被唤醒的 Agent 通过记忆检索拿到之前所有阶段的产物作为输入。

一个值得注意的实现细节来自 implementer-sparc-coder.md:它在"权威输入"一节明确要求 Refinement/Completion 阶段先读 docs/SPEC.md、docs/pseudocode/*.md、docs/adr/*.md,并且把 ADR 视为有约束力的跨 Agent 契约——"后端 coder、前端 coder 和 tester 必须读同一份 ADR,否则限界上下文会漂移";如果实现计划与 ADR 冲突,必须显式提出并给出跟随 ADR 或起草后继 ADR 的方案,不得静默偏离。这正是模板所说"Document decisions - Maintain traceability"(记录决策,保持可追溯性)在实现层的体现。

并行执行模式

模板给出的四条并行准则:

• 为相互独立的组件唤醒多个 Agent(Spawn multiple agents for independent components)
• 协调跨职能评审(Coordinate cross-functional reviews)
• 测试与文档并行推进(Parallelize testing and documentation)
• 在阶段边界同步(Synchronize at phase boundaries)

并行不是无约束的:同步点被固定在"阶段边界",即质量门处。这与插件版的状态管理机制吻合——任何阶段操作前,编排器都要先从 sparc-state 命名空间检索当前状态以防止漂移(drift),见 sparc-orchestrator.md 的 "Phase State Management" 一节:状态值形如 { phase: 1-5, phaseName, feature, startedAt, gateAttempts, artifacts: [] },键为 current-phase-{feature-slug}。也就是说,并行 Agent 各自工作,但"当前处于哪个阶段、门尝试了几次"这一全局事实只有一份,存放在 AgentDB 记忆中,所有角色以它为准。

五、使用方式:从自然语言指令到 SPARC 命令

模板定义的三类用法示例

1. 完整 SPARC 周期:"Use SPARC methodology to develop a user authentication system"(用 SPARC 方法学开发一个用户认证系统)
2. 单阶段聚焦:"Execute SPARC architecture phase for microservices design"(对微服务设计执行 SPARC 架构阶段)
3. 并行组件开发:"Apply SPARC to develop API, frontend, and database layers simultaneously"(用 SPARC 同时开发 API、前端和数据库层)

插件侧的命令化落地

在 ruflo-sparc 插件中,上述用法被固化为一个命令加三个 skill(见 plugins/ruflo-sparc/README.md):

# 安装插件
claude --plugin-dir plugins/ruflo-sparc

三个 skill 分别覆盖阶段区间:

Skill	用法	覆盖阶段
sparc-spec	/sparc-spec <feature-description>	Specification:收集需求、定义验收标准、识别约束
sparc-implement	/sparc-implement	Architecture + Implementation:设计模块、写伪代码、实现、测试
sparc-refine	/sparc-refine	Refinement + Completion:评审代码、提升覆盖率、对照规格验证、生成文档

而完整的生命周期操作通过 /ruflo-sparc 命令(ruflo-sparc.md)的五个子命令完成:

sparc init <feature>    # 初始化 SPARC 工作流
sparc status            # 查看当前阶段与门历史
sparc advance           # 执行门检查并尝试进入下一阶段
sparc phase <phase>     # 跳转到指定阶段(spec/pseudo/arch/refine/complete)
sparc report            # 生成含可追溯矩阵的完整 SPARC 报告

从命令实现文档可以看到每个子命令背后的记忆操作:init 会向 sparc-state 写入 current-phase-{slug}(初始为 Phase 1、gateAttempts: 0),并向 sparc-phases 写入 spec-{slug} 的占位规格;status 用 memory_search 列出所有活动工作流并展示进度条(如 [=====> ] Phase 3/5 — Architecture);advance 依次读取 sparc-state 与 sparc-phases,按当前阶段执行上文列出的门判据,把结果以 gate-{phase}-{slug}-{timestamp} 写入 sparc-gates,通过则递增阶段、失败则递增 gateAttempts 并逐条列出 blocker;phase 允许带别名跳转,但向前跳会写入警告:"Jumping forward skips gate checks. Run /sparc advance from previous phases to ensure quality."——这与模板"Never skip phases"的原则在机制上闭环。

sparc report 的产出结构也值得参考:包含各阶段状态/门结果/尝试次数/耗时汇总表、各阶段产物摘要、门历史时间线,以及把每条验收标准映射到具体测试的可追溯矩阵(Traceability Matrix)——这正对应模板 Completion 阶段"Integration testing / Handoff procedures"的最终交付形态。

六、集成模式:与任务编排、GitHub 流程、测试体系协同

模板定义了三种集成模式,分别说明 sparc-coord 在更大系统中的接口:

与 Task Orchestrator(任务编排器)集成

• 接收高层目标(Receives high-level objectives)
• 按 SPARC 阶段分解(Breaks down by SPARC phases)
• 协调各阶段执行(Coordinates phase execution)
• 回传进度(Reports progress back)

即 SPARC 协调器是任务编排器的"下层执行单元":上层给目标,它负责把目标翻译为五阶段计划并汇报。

与 GitHub Agents 集成

• 为每个阶段创建分支(Creates branches for each phase)
• 在阶段边界管理 PR(Manages PRs at phase boundaries)
• 在质量门处协调评审(Coordinates reviews at quality gates)
• 处理合并工作流(Handles merge workflows)

把质量门与 PR/评审对齐后,门检查就获得了具体的工程载体:一次门失败表现为 PR 被阻塞,一次门通过对应一次可合并的评审。仓库中与之配套的 GitHub 类 Agent 位于 .claude/agents/github/(如 swarm-pr.md、code-review-swarm.md),可在阶段边界被协调调用。

与 Testing Agents 集成

• 在 Refinement 阶段集成 TDD
• 协调测试覆盖率
• 管理测试自动化
• 验证质量指标

模板对 Refinement 阶段"TDD implementation"的要求,在 refinement.md 中落为可执行的 80% 覆盖率阈值(Jest coverageThreshold 四项均为 80)与"1000 并发登录请求 5 秒内完成"这类可度量的性能预算,使"质量指标验证"不再是空话。

七、记忆集成:产物、命名空间与检索模式

模板定义的存储产物

• 阶段输出与决策(Phase outputs and decisions)
• 质量门结果(Quality gate results)
• 架构决策(Architectural decisions)
• 测试策略(Test strategies)
• 经验教训(Lessons learned)

对应的检索模式:

• 检查以往类似项目(Check previous similar projects)
• 复用架构模式(Reuse architectural patterns)
• 应用已学优化(Apply learned optimizations)
• 规避历史坑点(Avoid past pitfalls)

插件侧的命名空间契约

模板中"存哪里、怎么取"在插件版中被契约化为四个命名空间(见 sparc-orchestrator.md 与 README):

命名空间	用途
sparc-state	每个功能当前所处阶段的跟踪
sparc-phases	阶段产物(规格、伪代码、ADR、报告)
sparc-gates	门检查结果与历史
patterns	学习到的 SPARC 执行模式(共享命名空间,只消费不拥有)

README 特别说明:这三个 kebab-case 命名空间是 ruflo-sparc 拥有的,须遵守 ruflo-agentdb 的命名空间约定;patterns 是复数形式,与 ReasoningBank 的单数 pattern 目标不同,且 pattern、claude-memories、default 等保留命名空间不得被遮蔽。

在 MCP 工具层,编排器通过 mcp__plugin_ruflo-core_ruflo__memory_store / memory_search / memory_retrieve 读写状态与产物,通过 task_create / task_update / task_complete 跟踪阶段任务,并在完成一个完整 SPARC 周期后执行"神经学习"三步:用 hooks_intelligence_trajectory-start ... trajectory-end 记录轨迹、neural_train 训练阶段序列模式、memory_store 以 patterns 命名空间键 sparc-{feature-slug} 存储模式,之后可用 neural_predict 预估新功能的阶段工作量与常见阻塞点。这正好回答了模板"Memory Integration → Retrieval Patterns"中"复用经验、规避历史坑"的存储底座问题。

八、最佳实践与场景化模式

阶段执行四原则

1. Never skip phases(绝不跳阶段)——每个阶段建立在前一个阶段之上
2. Enforce quality gates(强制质量门)——不走捷径
3. Document decisions(记录决策)——保持可追溯性
4. Iterate within phases(阶段内迭代)——精炼是被预期的

前两条由"门不通过就不前进 + 部分通过即整门失败"的机制保证;第三条由 ADR 作为有约束力契约的约定保证;第四条体现为 gateAttempts 计数器:门失败不重置工作,而是在当前阶段继续迭代并累计尝试次数,最终在 sparc report 的"Attempts"列中可见(如"Phase 2 门通过、尝试了 2 次")。

三类常见场景的裁剪方式

模板按场景给出了 SPARC 的重量分配:

1. Feature Development(功能开发):完整 SPARC 周期;重心在 Specification;测试要彻底
2. Bug Fixes(缺陷修复):轻量规格;重心在 Refinement;强调回归测试
3. Refactoring(重构):重心在 Architecture;做保持行为不变的保留测试(preservation testing);同步更新文档

结合 implementer-sparc-coder.md 的 TDD 工作流,三类场景可以映射为不同的执行剖面:功能开发走 Red-Green-Refactor 全流程加并行测试创建;缺陷修复可缩短到"轻量规格 + Refinement 的失败测试先行";重构则先补齐 Architecture 阶段的组件边界与保留测试,再做 Refinement。

九、成功度量指标

模板将度量分为两层:

阶段级指标

• 规格完整性(Specification completeness)
• 算法效率(Algorithm efficiency)
• 架构清晰度(Architecture clarity)
• 代码质量分(Code quality scores)
• 文档覆盖度(Documentation coverage)

全局指标

• 每阶段耗时(Time per phase)
• 质量门通过率(Quality gate pass rate)
• 缺陷发现时机(Defect discovery timing)
• 方法学遵从度(Methodology compliance)

这些指标恰好都是 sparc report 可以直接产出的数据:阶段耗时来自 sparc-state 的 startedAt 与阶段推进时间戳,门通过率与尝试次数来自 sparc-gates 的历史记录,方法学遵从度则体现为"是否出现向前跳阶段警告"与"是否所有门都经过 advance 而非 phase 跳转"。缺陷发现时机可以通过对比"缺陷在哪一阶段的质量门/回归中被拦截"来度量——越早被门拦下,说明上游阶段质量越高。

十、源码级佐证:插件契约与验证机制

为确认模板并非停留在纸面,可以从仓库中验证三点:

第一,契约化。 ADR-0001 把"SPARC 编排器角色 + 阶段到兄弟插件的映射"写入插件契约:Specification 阶段深度调研交给 ruflo-goals,Architecture 阶段用 ruflo-adr + ruflo-ddd(限界上下文),Refinement 阶段用 ruflo-jujutsu(diff 感知重构)+ ruflo-testgen(测试缺口分析),Completion 阶段用 ruflo-docs(文档生成)。ADR 同时记录了实现状态:v0.2.0 已发布,5 个阶段全部交叉链接,sparc-state 命名空间已声明,3 个 skill 已交付。

第二,可验证。 插件以 smoke 测试作为契约验证方式:

bash plugins/ruflo-sparc/scripts/smoke.sh
# Expected: "11 passed, 0 failed"

11 项结构检查包括:三个 skill 加 agent 加命令的 frontmatter 有效性、五个 SPARC 阶段名完整出现、v3.6 版本 pin、命名空间协调声明、阶段-插件映射表存在等。从源码结构看,这意味着"文档承诺的五阶段与质量门"每次版本变动都会被自动校验,模板与插件实现之间不会出现静默漂移。

第三,状态可回放。 由于阶段状态、阶段产物、门结果分存于三个命名空间且键名规则化(current-phase-{slug}、spec-{slug}、gate-{phase}-{slug}-{timestamp}),任何一次 SPARC 运行都可以被事后完整回放:从 sparc-state 知道当前走到哪,从 sparc-gates 知道每道门试了几次、卡在哪里,从 sparc-phases 取回每一步的规格/伪代码/ADR。这正是模板"Success Metrics → Methodology compliance"度量的数据来源。

十一、小结

sparc-coordinator.md 定义了 ruflo 中 SPARC 方法学编排的骨架:五阶段(Specification → Pseudocode → Architecture → Refinement → Completion)、四道质量门加终审、五个专职角色、四种并行准则,以及记忆驱动的经验复用。仓库中的配套实现把骨架逐层落地:

• 阶段执行:.claude/agents/sparc/ 下四个阶段 Agent 提供了各阶段的产物标准与代码级范例;
• 编排与门检查:plugins/ruflo-sparc/agents/sparc-orchestrator.md 定义了门检查五步协议、spawn 映射与记忆命名空间;
• 操作入口:/sparc init|status|advance|phase|report 五个子命令(见 plugins/ruflo-sparc/commands/ruflo-sparc.md)让整条流水线可以命令化驱动;
• 工程保障:ADR-0001 与 smoke.sh 的 11 项检查保证方法学文档与实现持续一致。

如果你希望在 Claude Code 环境中实践多智能体协作开发,这条路径的实操顺序是:安装 ruflo-sparc 插件 → 用 sparc init 建立工作流 → 按阶段调用 sparc-spec / sparc-implement / sparc-refine 产出各阶段产物 → 用 sparc advance 逐门推进 → 最后用 sparc report 输出带可追溯矩阵的方法学报告。