ruflo SPARC 方法论编排实战：sparc-coord 协调器如何驱动五阶段多 Agent 开发流水线

ruflo 仓库中的 SPARC 协调器（sparc-coord）是面向系统性软件开发的方法论编排 Agent：它将 Specification（规格）、Pseudocode（伪代码）、Architecture（架构）、Refinement（精化）、Completion（完成）五个阶段串联为一条带质量门控的开发流水线，并调度 5 个专项 Agent 协同工作。读完本文，你将掌握 SPARC 各阶段的核心产出、阶段流转与质量门判定标准、协调器的记忆（Memory）集成机制，以及在 ruflo 中通过 $agent-sparc-coordinator 技能与 CLI 命令实际驱动这套工作流的完整方式。

SPARC 方法论在 ruflo 中的定位

SPARC 是 ruflo 多 Agent 体系内的一条结构化开发流水线。它解决的核心问题是：如何让多个 AI Agent 按"先规划、后编码"的纪律完成复杂功能开发，而不是直接跳到写代码。

仓库中这套体系由两类资源共同构成：

• 方法论技能：sparc-methodology 定义了 SPARC 的触发与跳过条件、每阶段对应的 CLI 路由命令。其明确边界是：新功能实现、复杂实现、架构变更、系统重构、需求不明确时使用；简单 Bug 修复、文档更新、配置变更则跳过。
• 协调器技能：agent-sparc-coordinator 即本文主角 sparc-coord，负责编排整个方法论周期，执行阶段管理与质量门强制。

技能通过 $skill-name 语法调用（见 .agents/README.md），因此协调器的调用方式是 $agent-sparc-coordinator。而 Agent 运行所依赖的模型、审批策略、沙箱模式等底层配置，由 .agents/config.toml 控制，例如 approval_policy = "on-request"、sandbox_mode = "workspace-write"——这保证了编排过程中 Agent 的文件写入被限制在工作区内。

协调器 Agent 定义：frontmatter 中的能力与钩子

sparc-coord 的技能定义以双段 YAML frontmatter 开头：第一段是技能注册信息（name: agent-sparc-coordinator），第二段是 Agent 本体元数据。核心字段如下：

name: sparc-coord
type: coordination
color: orange
description: SPARC methodology orchestrator for systematic development phase coordination
capabilities:
  - sparc_coordination      # 方法论编排
  - phase_management        # 阶段管理
  - quality_gate_enforcement # 质量门强制
  - methodology_compliance  # 方法论合规检查
  - result_synthesis        # 结果综合
  - progress_tracking       # 进度跟踪
priority: high

type: coordination 表明它属于协调类 Agent（区别于 analyst、developer 等执行类角色），priority: high 使其在调度队列中优先被唤醒。

更值得注意的是它的 pre/post 钩子，这是 SPARC 体系"状态可追溯"的关键：

hooks:
  pre: |
    echo "🎯 SPARC Coordinator initializing methodology workflow"
    memory_store "sparc_session_start" "$(date +%s)"   # 记录会话开始时间戳
    # Check for existing SPARC phase data
    memory_search "sparc_phase" | tail -1               # 检查是否有进行中的 SPARC 阶段
  post: |
    echo "✅ SPARC coordination phase complete"
    memory_store "sparc_coord_complete_$(date +%s)" "SPARC methodology phases coordinated"
    echo "📊 Phase progress tracked in memory"

从源码结构看，这套钩子与阶段子 Agent 是配合工作的：每个专项阶段 Agent 在自己的 pre 钩子里也会执行 memory_store "sparc_phase" "<phase>"，post 钩子写入 <phase>_complete_$(date +%s) 标记。例如 agent-specification 在 pre 钩子写入 spec_start_<ts>、post 钩子写入 spec_complete_<ts>；agent-pseudocode 的 pre 钩子还会 memory_search "spec_complete" | tail -1 取回上一阶段的规格产出。也就是说，记忆库就是各 Agent 之间的状态总线：协调器靠检索 sparc_phase 恢复中断的会话，子 Agent 靠检索 *_complete 标记串接阶段输入。

五阶段总览：各阶段的职责与产出

协调器文档将 SPARC 拆分为五个阶段，每个阶段有明确的职责清单：

1. Specification（规格）阶段

• 详细需求收集
• 用户故事创建
• 验收标准定义
• 边界用例识别

该阶段由 agent-specification（type: analyst，sparc_phase: specification）承担。它以 YAML 形式定义功能需求（FR 编号 + 优先级 + 验收标准）、非功能需求（NFR + 度量方式）、约束分析（技术/商业/法规三类），并以 Gherkin 场景描述验收标准，交付物包括需求文档、数据模型规格与 OpenAPI 风格的 API 规格。

2. Pseudocode（伪代码）阶段

• 算法设计
• 逻辑流规划
• 数据结构选择
• 复杂度分析

对应 agent-pseudocode（type: architect，sparc_phase: pseudocode）。它的产出标准要求算法伪代码"语言无关、任何开发者可在任何语言中实现"，并强制包含时间/空间复杂度分析。文档示例中给出了令牌桶限流、带权重评分的搜索排序等完整伪代码，以及 Strategy/Observer 等设计模式的应用模板。

3. Architecture（架构）阶段

• 系统设计
• 组件定义
• 接口契约
• 集成规划

对应 agent-architecture（type: architect，sparc_phase: architecture）。该阶段把算法转化为系统设计，包含高层架构（客户端层 / API 网关 / 应用层 / 数据层 / 基础设施的 Mermaid 分层图）、接口契约、技术选型与扩展性规划。

4. Refinement（精化）阶段

• TDD 实现
• 迭代改进
• 性能优化
• 代码质量增强

对应 agent-refinement（type: developer，sparc_phase: refinement）。它按 Red-Green 的 TDD 循环推进：先写失败测试（Red），再写最小实现使测试通过（Green）。其 pre 钩子会执行 npm test --if-present 作为起点基线，post 钩子运行完整测试套件收尾——测试命令直接嵌入钩子，质量门不依赖人工。

5. Completion（完成）阶段

• 集成测试
• 文档定稿
• 部署准备
• 交接流程

完成阶段负责验证整体质量指标、固化文档并完成交接。

编排工作流：阶段流转与质量门

协调器文档定义了严格串行的阶段流转图：

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），共五条判定标准：

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

质量门是"无捷径"（No shortcuts）的：quality_gate_enforcement 被显式列为协调器的核心能力之一。配合 sparc-review.sh 脚本，可以机械地核对五个阶段产出文件是否齐备：

#!/bin/bash
# Run SPARC phase review checklist
FEATURE_DIR="${1:-.}"

for phase in specification pseudocode architecture refinement completion; do
  if [ -f "$FEATURE_DIR/${phase}.md" ]; then
    echo "[x] $phase - found"
  else
    echo "[ ] $phase - missing"
  fi
done

该脚本以"每阶段一个 Markdown 文件"为核对基准，缺失项以 [ ] 标出——这与 sparc-init.sh 的初始化逻辑一一对应：

#!/bin/bash
# Initialize SPARC workflow for a new feature
FEATURE_NAME="${1:-new-feature}"

mkdir -p "./docs/sparc/$FEATURE_NAME"
touch "./docs/sparc/$FEATURE_NAME/1-specification.md"
touch "./docs/sparc/$FEATURE_NAME/2-pseudocode.md"
touch "./docs/sparc/$FEATURE_NAME/3-architecture.md"
touch "./docs/sparc/$FEATURE_NAME/4-refinement.md"
touch "./docs/sparc/$FEATURE_NAME/5-completion.md"

echo "SPARC workflow initialized in ./docs/sparc/$FEATURE_NAME"

即：bash sparc-init.sh my-feature 会在 ./docs/sparc/my-feature/ 下创建五个带序号的阶段文件，阶段产物以文件形式落盘，保证可追溯。

专项 Agent 团队与并行执行模式

协调器文档定义了 5 个专项 SPARC Agent 的分工：

Agent	职责	仓库中的对应技能
SPARC Researcher	需求与可行性	由 analyst 型 Agent 承担（如 agent-specification）
SPARC Designer	架构与接口	agent-architecture
SPARC Coder	实现与精化	agent-refinement
SPARC Tester	质量保证	agent-tester
SPARC Documenter	文档与指南	agent-docs-api-openapi

其中带 sparc_phase 标记的前四个阶段 Agent 可通过技能调用触发：$agent-specification、$agent-pseudocode、$agent-architecture、$agent-refinement。

并行执行模式（Parallel Execution Patterns）是协调器的另一个核心能力：

• 为相互独立的组件派生多个 Agent
• 协调跨职能评审
• 测试与文档并行推进
• 在阶段边界处同步（Synchronize at phase boundaries）

关键约束是：并行只在阶段内部发生，阶段边界必须同步。这与质量门的串行设计一致——独立组件可以并行开发，但每个阶段出口的质量门必须由协调器统一裁决后才能进入下一阶段。

实战调用：从技能指令到 CLI 命令

方式一：技能指令驱动

在支持 $skill 调用的 CLI（如 Claude Code / Codex，配置见 .agents/config.toml）中，直接以自然语言向协调器下达任务。文档给出的三类典型用法：

1. 完整 SPARC 周期："Use SPARC methodology to develop a user authentication system"
2. 单阶段聚焦："Execute SPARC architecture phase for microservices design"
3. 并行组件开发："Apply SPARC to develop API, frontend, and database layers simultaneously"

方式二：逐阶段 CLI 路由

sparc-methodology 提供了面向每阶段的 hooks route 命令，通过任务前缀（specification:、pseudocode: 等）让路由层分派到对应 Agent：

# Specification 阶段：定义需求、验收标准与约束
npx @claude-flow/cli hooks route --task "specification: user authentication with OAuth2, MFA, and session management"

# Pseudocode 阶段：编写高层伪代码
npx @claude-flow/cli hooks route --task "pseudocode: OAuth2 login flow with token refresh"

# Architecture 阶段：设计系统结构、接口与依赖
npx @claude-flow/cli hooks route --task "architecture: auth module with service layer, repository, and API endpoints"

# Refinement 阶段：基于反馈迭代设计
npx @claude-flow/cli hooks route --task "refinement: add rate limiting and brute force protection"

# Completion 阶段：以测试与文档收尾
npx @claude-flow/cli hooks route --task "completion: verify all tests pass, update API docs, security review"

方式三：显式派生协调器 Agent

当需要独立、持久的编排会话时，可直接派生协调器实例：

npx @claude-flow/cli agent spawn --type sparc-coord --name sparc-lead

--type sparc-coord 对应的正是本文主角的技能名，--name 指定实例名，便于在 Swarm 拓扑中定位与回收。

阶段产物检查

bash .agents/skills/sparc-methodology/scripts/sparc-review.sh ./docs/sparc/my-feature

输出形如 [x] specification - found / [ ] architecture - missing，是质量门前的人工复核手段。

集成模式：协调器与外部 Agent 的协作接口

协调器文档定义了三组集成接口，决定了它在更大 Agent 拓扑中的位置：

与 Task Orchestrator（任务编排器）协作

• 接收高层目标
• 按 SPARC 阶段分解任务
• 协调各阶段执行
• 回传进度报告

与 GitHub Agents 协作

• 每个阶段创建独立分支
• 在阶段边界管理 PR
• 在质量门处协调评审
• 处理合并工作流

这意味着一次 SPARC 周期会映射为 Git 仓库中的多个阶段分支与若干 PR，阶段边界与 PR 边界一一对应，质量门评审即 PR 评审。

与 Testing Agents 协作

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

结合 agent-refinement 的钩子设计（pre 跑基线测试、post 跑完整套件），可以推断测试 Agent 的质量指标输入直接来自这两次测试运行的结果，而非独立采样。

最佳实践：阶段执行纪律与三类常见模式

阶段执行四条纪律

1. Never skip phases（绝不跳过阶段）——每个阶段都建立在前一阶段之上
2. Enforce quality gates（强制质量门）——无捷径
3. Document decisions（记录决策）——保持可追溯性
4. Iterate within phases（阶段内允许迭代）——精化是预期行为

这四条划出了一个重要边界：迭代发生在阶段内部，而跨阶段回退（例如从 Refinement 跳回 Specification）必须经过协调器显式调度。

三类任务的差异化打法

模式	策略
功能开发（Feature Development）	完整 SPARC 周期，强调规格阶段，充分测试
Bug 修复（Bug Fixes）	轻量规格，聚焦精化阶段，重点回归测试
重构（Refactoring）	强调架构阶段，保持性测试（Preservation Testing），同步更新文档

这套差异化策略与 sparc-methodology 技能的"跳过条件"（简单 Bug 修复可跳过完整 SPARC）形成呼应：轻量场景不必走全流程，但一旦进入 SPARC 周期，五阶段纪律不可裁剪。

记忆集成与成功指标

存储工件（Stored Artifacts）

协调器在记忆库中持久化五类工件：阶段产出与决策、质量门结果、架构决策、测试策略、经验教训（Lessons learned）。

检索模式（Retrieval Patterns）

• 检索此前类似项目的记录
• 复用已验证的架构模式
• 应用已学到的优化手段
• 规避历史踩过的坑

从各阶段 Agent 的钩子实现看（如 pseudocode 的 pre 钩子检索 spec_complete、architecture 的 pre 钩子检索 pseudo_complete），这套检索模式不是文档层面的倡导，而是嵌入钩子脚本的强制行为——前序阶段产物必须经记忆检索传递，而非靠上下文拼接。

成功指标体系

阶段级指标：规格完备度、算法效率、架构清晰度、代码质量分、文档覆盖率。

整体指标：每阶段耗时、质量门通过率、缺陷发现时机、方法论合规度。

其中"缺陷发现时机"（Defect discovery timing）是衡量 SPARC 价值的关键观测点：规格/伪代码阶段拦截的缺陷成本远低于精化阶段，若质量门持续把缺陷挡在前置阶段，说明方法论正在发挥预期作用。

小结：在 ruflo 中落地一条 SPARC 周期的最短路径

综合协调器定义与配套技能，一个可复制的最小工作流是：

1. bash .agents/skills/sparc-methodology/scripts/sparc-init.sh my-feature 初始化五阶段产物目录；
2. 依次用 npx @claude-flow/cli hooks route --task "<phase>: <任务>" 驱动五个阶段，或 $agent-sparc-coordinator 交给协调器统一编排；
3. 阶段产物写入 ./docs/sparc/my-feature/，跨 Agent 状态经 memory_store/memory_search 在记忆库传递；
4. 用 sparc-review.sh 核对产物齐备性，逐门通过质量门后再进入下一阶段；
5. 完成后按"存储工件"清单把架构决策、测试策略与经验教训沉淀进记忆，供后续 SPARC 周期检索复用。

整套机制的设计意图清晰：用 frontmatter 声明能力与钩子，用记忆库串接 Agent 状态，用质量门强制阶段纪律——三者共同使 SPARC 从一份流程文档变成 ruflo 多 Agent 体系中可执行、可审计的开发流水线。