ruflo-sparc 插件实战指南：用 SPARC 五阶段方法论驱动 Agent 化特性开发与质量门禁

ruflo-sparc 是 ruflo 项目中负责承载 SPARC 方法论（Specification、Pseudocode、Architecture、Refinement、Completion）的插件：它以 sparc-orchestrator 编排代理驱动特性走完五阶段生命周期，每个阶段之间强制通过质量门（quality gate）才能晋级，并将所有阶段产物与门禁结果写入 AgentDB 内存命名空间以备追溯。阅读本文后，你将掌握 sparc init/status/advance/phase/report 五个子命令的完整用法、三把技能（sparc-spec、sparc-implement、sparc-refine）的实操步骤、五阶段门禁判定标准，以及插件与 ruflo-goals / ruflo-adr / ruflo-ddd / ruflo-jujutsu / ruflo-docs 等兄弟插件的阶段交接关系。

插件总览：Agent 编排 + 阶段门禁 + 内存追溯

ruflo-sparc 的核心定位是"编排者"而非"执行者"。根据插件 ADR（0001-sparc-contract.md），它拥有 1 个 Agent（sparc-orchestrator，sonnet 模型）、3 个技能（sparc-spec、sparc-implement、sparc-refine）和 1 个命令（/ruflo-sparc，内含 5 个子命令）。

其工作机制是：编排器在每个阶段孵化一个专门的子 Agent 负责该阶段的深度工作，把上一阶段产出的工件通过内存检索传递给下一个 Agent，并将阶段产物、门禁结果全部落盘到内存命名空间，实现全生命周期的可追溯：

组件	配置位置	作用
sparc-orchestrator	agents/sparc-orchestrator.md	编排 5 阶段生命周期、强制门禁检查、孵化阶段 Agent、在内存中跟踪状态
sparc-spec	skills/sparc-spec/SKILL.md	运行 Specification 阶段
sparc-implement	skills/sparc-implement/SKILL.md	运行 Pseudocode + Architecture 阶段
sparc-refine	skills/sparc-refine/SKILL.md	运行 Refinement + Completion 阶段
/ruflo-sparc 命令	commands/ruflo-sparc.md	提供 5 个子命令驱动工作流状态机

安装与前置条件

在 ruflo 仓库根目录下，通过 Claude 的 --plugin-dir 参数加载本插件：

claude --plugin-dir plugins/ruflo-sparc

兼容性约束：插件 CLI 被固定（pin）在 @claude-flow/cli 的 v3.6 主版本+次版本（major+minor）上。这一 pin 是插件契约的一部分，smoke 脚本会校验 README 中存在 @claude-flow/cli v3.6 的固定声明，升级 CLI 主版本前应确认插件契约仍然成立。

验证入口：插件的"验证即契约"（smoke-as-contract）约定由 scripts/smoke.sh 承担，正确输出为 11 passed, 0 failed（详见下文"验证"一节）。

五阶段生命周期与质量门禁

SPARC 把特性开发拆成五个阶段，每个阶段有明确的产出物、门禁标准与负责的孵化 Agent：

阶段	名称	门禁标准（Gate Criteria）	孵化的 Agent
1	Specification	≥ 3 条验收标准、明确约束、识别边界用例	researcher
2	Pseudocode	覆盖全部验收标准、错误路径显式化、标注复杂度	planner
3	Architecture	约束全部被回应、类型化 API 契约、无循环依赖	system-architect
4	Refinement	全部验收标准有通过测试、评审通过、覆盖率 ≥ 80%	coder + tester
5	Completion	全部测试通过、文档齐全、部署清单核验	reviewer

Phase 1 — Specification（规格）

目标：精确捕获"要构建什么"以及"成功如何度量"。

核心活动（与 sparc-spec/SKILL.md 的 11 步流程对应）：

• 收集功能性与非功能性需求
• 用 Given/When/Then 格式定义可测试的验收标准（至少 3 条）
• 识别约束（性能、安全、兼容性、预算）
• 映射利益相关者关切与边界用例（至少 3 个）
• 将规格文档存入内存

门禁检查：规格必须包含 ≥ 3 条验收标准、显式约束与已识别的边界用例，且记录利益相关者签核。

产出物格式：需求（FR/NFR）、验收标准（AC-1/2/3）、约束（性能/安全/兼容性）、边界用例（EC-1/2/3）、集成点（IP），以 spec-{feature-slug} 为键存入 sparc-phases 命名空间。

Phase 2 — Pseudocode（伪代码）

目标：在写生产代码之前先设计算法与数据流。

核心活动（对应 sparc-implement/SKILL.md 的第 4 步）：

• 为每条验收标准编写语言无关的伪代码
• 定义带类型注解的数据结构与状态迁移
• 绘制控制流：happy path、每条边界用例的错误/异常路径、并发访问处理
• 对关键路径标注算法复杂度（时间与空间）

门禁检查：伪代码覆盖规格中全部验收标准、错误路径显式、复杂度已标注。以 pseudo-{feature-slug} 为键存入 sparc-phases。

Phase 3 — Architecture（架构）

目标：确立模块边界、API 契约与集成点。

核心活动（对应 sparc-implement/SKILL.md 的第 5 步）：

• 按 DDD 模式定义限界上下文（bounded context）与聚合根（aggregate root），记录聚合不变量（invariants），映射领域事件
• 设计类型化 API 契约（请求/响应 schema、错误码、版本策略）
• 规划模块边界：目录结构、依赖方向规则（禁止循环依赖）、公开与内部接口
• 指定基础设施关注点：持久化策略、缓存、消息模式、配置与环境需求

门禁检查：架构回应规格中全部约束、API 契约类型化、无循环依赖、DDD 不变量已文档化。以 arch-{feature-slug} 为键存入 sparc-phases。

Phase 4 — Refinement（精化）

目标：通过代码评审、测试与优化进行迭代改进。

核心活动（对应 sparc-refine/SKILL.md 的第 3–8 步）：

• 按规格合规性、架构遵循度、伪代码保真度、代码质量四个维度做代码评审
• 运行测试并测量覆盖率，补齐缺失测试（单元、集成、边界用例），新代码覆盖率目标 ≥ 80%
• 若规格含性能约束，对关键路径做剖析并与阈值对比，未达标则优化
• 迭代直到：全部验收标准有通过测试、评审无 critical/high 级问题、覆盖率达标、性能达标

门禁检查：全部验收标准有通过测试、评审通过且无 critical 问题、覆盖率达标。以 refine-{feature-slug} 为键存入 sparc-phases。

Phase 5 — Completion（完成）

目标：最终校验、文档与部署就绪。

核心活动（对应 sparc-refine/SKILL.md 的第 9–17 步）：

• 跑全量回归测试
• 对照 Phase 1 的每条验收标准做最终校验
• 生成 API 文档与使用示例
• 核验部署前置条件（迁移、配置、feature flag、回滚计划、安全评审）
• 产出带追溯矩阵（traceability matrix）的完成报告

门禁检查：全部测试通过、文档齐全、部署清单核验、追溯矩阵将每条验收标准链接到对应测试。以 complete-{feature-slug} 为键存入 sparc-phases。

门禁检查协议

每次门禁检查遵循固定流程（定义于 agents/sparc-orchestrator.md 的 Gate Check Protocol）：

1. 从 sparc-phases 命名空间检索阶段产物
2. 逐条评估门禁标准——每条都必须通过，部分通过即判定门禁失败
3. 将通过/失败结果及细节写入 sparc-gates 命名空间
4. 失败时：识别差距、给出可操作的反馈、停留在当前阶段
5. 成功时：推进阶段计数、通知用户、进入下一阶段

门禁结果的数据结构：

Key: gate-{phase}-{feature-slug}-{timestamp}
Value: { phase, passed, criteria: [{name, passed, detail}], blockers: [] }

五个子命令：完整工作流状态机

/ruflo-sparc 命令暴露 5 个子命令（详见 commands/ruflo-sparc.md），构成工作流的推进引擎：

sparc init <feature>

初始化新 SPARC 工作流：

1. 由特性名生成 feature slug（小写、连字符分隔）
2. 向 sparc-state 写入 current-phase-{slug}，值为 { "phase": 1, "phaseName": "Specification", "feature": "<feature>", "startedAt": "<ISO timestamp>", "gateAttempts": 0, "artifacts": [] }
3. 向 sparc-phases 写入 spec-{slug}，值为 { "status": "pending", "requirements": [], "acceptanceCriteria": [], "constraints": [], "edgeCases": [] }
4. 提示用户开始规格阶段：/sparc-spec <feature-description>

sparc status

展示当前阶段与门禁历史：

1. 搜索 sparc-state 列出所有活跃工作流
2. 对每个工作流展示：特性名与 slug、当前阶段（1-Specification 到 5-Completion）、开始时间与时长、门禁尝试次数
3. 搜索 sparc-gates 列出该特性的门禁历史（阶段、通过/失败、标准明细、blockers）
4. 渲染进度条，如 [=====> ] Phase 3/5 — Architecture

sparc advance

尝试通过当前门禁并推进：

1. 从 sparc-state 取当前状态，从 sparc-phases 取阶段产物
2. 按当前阶段执行对应门禁检查（五套标准与上文表格一致）
3. 以 gate-{phase}-{slug}-{timestamp} 为键将结果存入 sparc-gates
4. 通过：递增 sparc-state 中的 phase；若越过 Phase 5 则宣告 "SPARC workflow complete"；失败：递增 gateAttempts，列出未达标标准并给出针对性改进建议

sparc phase <phase-name>

跳转到指定阶段（用于重入或迭代）：

• 合法值：specification / pseudocode / architecture / refinement / completion，别名 spec / pseudo / arch / refine / complete，或数字 1–5
• 向前跳转会发出警告："Jumping forward skips gate checks"，提醒先在各前序阶段运行 /sparc advance 以保证质量

sparc report

生成完整 SPARC 方法论报告：汇总 sparc-state、sparc-phases、sparc-gates 三处数据，输出阶段汇总表、规格/伪代码/架构摘要、门禁时间线以及追溯矩阵（每条验收标准 → 测试 → 状态）。

三个技能：阶段产出的可执行手册

/sparc-spec <feature-description>

运行 Specification 阶段（11 步，见 sparc-spec/SKILL.md）。核心流程：启动轨迹记录（trajectory-start）→ 检索既有状态与相似模式（memory_search + neural_predict）→ 收集功能/非功能需求、集成点、数据需求 → 用 Given/When/Then 写至少 3 条验收标准 → 记录性能/安全/兼容性/基础设施约束 → 至少列 3 个边界用例 → 将规格存入 sparc-phases（键 spec-{slug}）→ 更新 sparc-state → 记录轨迹步骤 → 展示规格并建议运行 /sparc advance。

验收标准模板：

AC-1: Given [precondition], when [action], then [expected result]
AC-2: Given [precondition], when [action], then [expected result]
AC-3: Given [precondition], when [action], then [expected result]

/sparc-implement

运行 Pseudocode + Architecture 两个紧密耦合的阶段（见 sparc-implement/SKILL.md）。先检索规格与阶段状态并做架构模式预测，然后依次产出 pseudo-{slug} 与 arch-{slug} 两份工件；若用户确认，可继续进入实现：按模块边界建文件、先实现接口与类型、按伪代码实现核心逻辑、伴随单元测试（优先 TDD）、运行测试验证验收标准。

技能内置的模块结构模板：

src/{feature}/
  {feature}.types.ts      # Interfaces and types
  {feature}.service.ts     # Business logic
  {feature}.controller.ts  # HTTP handling
  {feature}.repository.ts  # Data access
  {feature}.test.ts        # Tests

/sparc-refine

运行 Refinement + Completion 两个收尾阶段（见 sparc-refine/SKILL.md）。Phase 4 聚焦代码评审（规格合规/架构遵循/伪代码保真/代码质量四维）、覆盖率分析（新代码 ≥ 80%）、性能剖析与迭代；Phase 5 完成全量回归、追溯矩阵、文档生成与部署就绪清单，并以 neural_train 训练成功周期、把经验模式存入 patterns 命名空间（键 sparc-{slug}）。

技能内置的部署就绪清单（Phase 5 门禁依据）：

- [ ] All tests passing
- [ ] Documentation complete
- [ ] Database migrations prepared (if applicable)
- [ ] Configuration changes documented
- [ ] Feature flags configured (if applicable)
- [ ] Rollback plan defined
- [ ] Security review complete (no secrets, inputs validated)

内存命名空间：状态、工件、门禁与模式

插件拥有三个 AgentDB 命名空间（均符合 ruflo-agentdb ADR-0001 的 kebab-case 命名规范），并消费共享的 patterns 命名空间：

命名空间	用途	归属
sparc-state	每个特性的当前阶段跟踪（键 current-phase-{slug}）	拥有
sparc-phases	阶段工件：规格、伪代码、ADR、报告	拥有
sparc-gates	门禁检查结果与历史	拥有
patterns	跨特性的 SPARC 执行模式学习	消费（非拥有）

命名约束：注意 patterns 是复数，与 ReasoningBank 目标中单数的 pattern 命名空间不同；保留命名空间（pattern、claude-memories、default）严禁被遮蔽。

阶段状态通过 mcp__plugin_ruflo-core_ruflo__memory_store 写入 sparc-state，键 current-phase-{feature-slug}，值 { phase: 1-5, phaseName, feature, startedAt, gateAttempts, artifacts: [] }；任何阶段操作前先用 memory_search 检索当前状态以防状态漂移。

阶段与兄弟插件的对齐（Phase-to-Plugin Alignment）

这是插件的关键架构决策：ruflo-sparc 负责编排生命周期，各阶段的深度工具由对应的"规范交接插件"（canonical handoff plugin）承担：

阶段	归属插件	提供能力
Specification	ruflo-goals（deep-research）	多源研究编排以收集需求
Pseudocode	ruflo-sparc（本插件）	伪代码生成 + 复杂度标注
Architecture	ruflo-adr + ruflo-ddd	ADR 创建 + 限界上下文建模
Refinement	ruflo-jujutsu + ruflo-testgen	Diff 感知重构 + 测试缺口分析
Completion	ruflo-docs	自动化文档生成

在编排器内部，跨阶段协作还涉及：

• ruflo-goals：用 horizon 跟踪把 SPARC 特性放进长期规划视界，查询 horizons 命名空间对齐阶段时间线与目标里程碑
• ruflo-workflows：把 SPARC 阶段固化为工作流模板，用 workflow_create / workflow_execute 复用阶段流程
• ruflo-ddd：Phase 3 直接利用 DDD 限界上下文模式，查询 ddd-contexts 命名空间复用既有领域模型

神经网络学习：让门禁自我调优

完成一轮完整 SPARC 周期后，编排器执行闭环学习：

1. 用 trajectory-start → trajectory-step → trajectory-end 记录执行轨迹
2. 用 neural_train 以成功阶段序列训练模式
3. 用 memory_store 把模式存入 patterns 命名空间，键 sparc-{feature-slug}

之后可用 neural_predict 依据特性描述估算各阶段工作量，或用 memory_search 检索相似特性经验，提前预判阶段时长与常见阻塞点。在每阶段或完整周期后，还可通过 CLI 将阶段质量反馈喂入学习回路：

npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true

验证：smoke 脚本即契约

插件的可验证性由 scripts/smoke.sh 保证，它执行 11 项结构化检查：

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

11 项检查覆盖：plugin.json 版本号 0.2.1 且包含 mcp/phase-gates/quality-gates 关键词；3 个技能 + Agent + 命令文件存在且 frontmatter 含 name:/description:；README 记录全部 5 个阶段名；命令文件非空；README 固定 @claude-flow/cli v3.6；README 引用 ruflo-agentdb 命名规范；三个 sparc-* 命名空间已被声明；阶段-插件对齐表交叉引用了 adr/ddd/jujutsu/docs/goals；ADR-0001 存在且状态为 Accepted；5 套门禁标准关键词齐备（acceptance criteria / error paths / circular deps / coverage / deployment checklist）；技能中无通配符工具授权（allowed-tools: *）。

架构决策与版本演进

插件的契约化由 ADR-0001（状态 Accepted）固化，决策内容包括：README 增补 Compatibility（pin v3.6）、Phase-to-plugin alignment 表、Namespace coordination、Verification 与 Architecture Decisions 章节；版本从 0.1.0 升至 0.2.0（关键词增加 mcp、phase-gates、quality-gates）；smoke.sh 承载 11 项结构检查。从实现状态看，v0.2.0 已发布并列入 marketplace.json，五个阶段全部与兄弟插件（goals、ddd、adr、testgen、docs）完成交叉链接，三个技能与 smoke 门禁均已落地。当前 smoke 脚本已按 0.2.1 版本校验。

快速上手路径

把上述要素串成一条完整实战链路：

# 1. 加载插件并初始化工作流
claude --plugin-dir plugins/ruflo-sparc
/sparc init my-feature

# 2. 运行阶段技能，每完成一个阶段就尝试晋级
/sparc-spec "实现 xxx 功能，支持 a/b/c"
/sparc advance          # 通过 Phase 1 门禁

/sparc-implement        # 产出伪代码 + 架构
/sparc advance          # 通过 Phase 3 门禁

/sparc-refine           # 评审、补测、收尾、文档
/sparc advance          # 通过 Phase 5 门禁

# 3. 随时查看进度与最终报告
/sparc status
/sparc report           # 含追溯矩阵的完整方法论报告

许可与延伸阅读

插件以 MIT 许可开源。若需深入各阶段的契约细节，可继续阅读：编排器完整协议见 agents/sparc-orchestrator.md，子命令逐行语义见 commands/ruflo-sparc.md，三份技能手册见 sparc-spec、sparc-implement、sparc-refine，契约与验证见 ADR-0001 与 smoke.sh。