qe-sparc-methodology

SPARC 方法论——全面开发框架

概述

SPARC（Specification、Pseudocode、Architecture、Refinement、Completion，即规范、伪代码、架构、优化、完成）是一种系统化开发方法论，与 Claude Flow 的多 Agent 编排能力相集成。它提供 17 种专用模式，涵盖全面的软件开发流程，从初步研究到部署和监控。

目录

1. 核心理念
2. 开发阶段
3. 可用模式
4. 激活方法
5. 编排模式
6. TDD 工作流
7. 最佳实践
8. 集成示例
9. 常见工作流

---

核心理念

SPARC 方法论强调：

• 系统化方法：从规范到完成的结构化阶段
• 测试驱动开发：先编写测试，再进行实现
• 并行执行：协调多个 Agent 并发工作，提速 2.8–4.4 倍
• 记忆集成：在不同 Agent 和会话之间持续共享知识
• 质量优先：全面审查、测试和验证
• 模块化设计：清晰划分关注点，并定义明确的接口

核心原则

1. 先编写规范，再写代码：清晰定义需求和约束
2. 先设计，再实现：规划架构和组件
3. 先编写测试，再开发功能：编写未通过的测试，然后使其通过
4. 审查所有内容：检查代码质量、安全性和性能
5. 持续编写文档：在整个过程中维护最新文档

---

开发阶段

阶段 1：规范

目标：定义需求、约束和成功标准

• 需求分析
• 用户故事映射
• 约束识别
• 成功指标定义
• 伪代码规划

关键模式：researcher、analyzer、memory-manager

阶段 2：架构

目标：设计系统结构和组件接口

• 系统架构设计
• 组件接口定义
• 数据库架构规划
• API 契约规范
• 基础设施规划

关键模式：architect、designer、orchestrator

阶段 3：优化（TDD 实现）

目标：采用测试优先的方法实现功能

• 编写未通过的测试
• 实现最精简可行的代码
• 使测试通过
• 重构以提升质量
• 持续迭代直至完成

关键模式：tdd、coder、tester

阶段 4：审查

目标：确保代码质量、安全性和性能

• 代码质量评估
• 安全漏洞扫描
• 性能分析
• 最佳实践验证
• 文档审查

关键模式：reviewer、optimizer、debugger

阶段 5：完成

目标：集成、部署和监控

• 系统集成
• 部署自动化
• 监控设置
• 文档定稿
• 知识记录

关键模式：workflow-manager、documenter、memory-manager

---

可用模式

核心编排模式

orchestrator

通过 TodoWrite/Task/Memory 协调多 Agent 任务编排。

能力：

• 将任务分解为易于管理的单元
• 协调 Agent 并分配资源
• 跟踪进度并综合结果
• 自适应选择策略
• 跨 Agent 通信

用法：

mcp__claude-flow__sparc_mode {
  mode: "orchestrator",
  task_description: "coordinate feature development",
  options: { parallel: true, monitor: true }
}

swarm-coordinator

用于复杂多 Agent 工作流的专用集群管理。

能力：

• 拓扑优化（网状、分层、环形、星形）
• Agent 生命周期管理
• 根据工作负载动态扩展
• 容错与恢复
• 性能监控

workflow-manager

流程自动化和工作流编排。

能力：

• 工作流定义与执行
• 事件驱动触发
• 顺序和并行管道
• 状态管理
• 错误处理与重试逻辑

batch-executor

用于高吞吐量操作的并行任务执行。

功能：

• 并发文件操作
• 批处理优化
• 资源池化
• 负载均衡
• 进度汇总

---

开发模式

coder

通过批量文件操作自主生成代码。

功能：

• 功能实现
• 代码重构
• Bug 修复和补丁
• API 开发
• 算法实现

质量标准：

• ES2022+ 标准
• TypeScript 类型安全
• 全面的错误处理
• 性能优化
• 安全最佳实践

用法：

mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "implement user authentication with JWT",
  options: {
    test_driven: true,
    parallel_edits: true,
    typescript: true
  }
}

architect

使用基于 Memory 的协调进行系统设计。

功能：

• 微服务架构
• 事件驱动设计
• 领域驱动设计（DDD）
• 六边形架构
• CQRS 和事件溯源

Memory 集成：

• 存储架构决策
• 共享组件规范
• 保持设计一致性
• 跟踪架构演进

设计模式：

• 分层架构
• 微服务模式
• 事件驱动模式
• 领域建模
• 基础设施即代码

用法：

mcp__claude-flow__sparc_mode {
  mode: "architect",
  task_description: "design scalable e-commerce platform",
  options: {
    detailed: true,
    memory_enabled: true,
    patterns: ["microservices", "event-driven"]
  }
}

tdd

通过全面测试进行测试驱动开发。

功能：

• 测试先行开发
• 红-绿-重构循环
• 测试套件设计
• 覆盖率优化（目标：90%+）
• 持续测试

TDD 工作流：

1. 编写失败的测试（RED）
2. 实现最少量的代码
3. 让测试通过（GREEN）
4. 重构以提升质量（REFACTOR）
5. 重复循环

测试策略：

• 单元测试（Jest、Mocha、Vitest）
• 集成测试
• 端到端测试（Playwright、Cypress）
• 性能测试
• 安全测试

用法：

mcp__claude-flow__sparc_mode {
  mode: "tdd",
  task_description: "shopping cart feature with payment integration",
  options: {
    coverage_target: 90,
    test_framework: "jest",
    e2e_framework: "playwright"
  }
}

reviewer

使用批量文件分析进行代码审查。

功能：

• 代码质量评估
• 安全漏洞检测
• 性能分析
• 最佳实践验证
• 文档审查

审查标准：

• 代码正确性和逻辑
• 遵循设计模式
• 全面的错误处理
• 测试覆盖率是否充分
• 可维护性和可读性
• 安全漏洞
• 性能瓶颈

批量分析：

• 并行文件审查
• 模式检测
• 依赖项检查
• 一致性验证
• 自动化报告

用法：

mcp__claude-flow__sparc_mode {
  mode: "reviewer",
  task_description: "review authentication module PR #123",
  options: {
    security_check: true,
    performance_check: true,
    test_coverage_check: true
  }
}

---

分析与研究模式

researcher

通过并行 WebSearch/WebFetch 和 Memory 协调进行深入研究。

功能：

• 全面收集信息
• 评估来源可信度
• 趋势分析与预测
• 竞争研究
• 技术评估

研究方法：

• 并行网络搜索
• 学术论文分析
• 行业报告综合
• 收集专家意见
• 汇总统计数据

Memory 集成：

• 存储带有引用的研究发现
• 构建知识图谱
• 跟踪信息来源
• 交叉引用洞见
• 维护研究历史

用法：

mcp__claude-flow__sparc_mode {
  mode: "researcher",
  task_description: "research microservices best practices 2024",
  options: {
    depth: "comprehensive",
    sources: ["academic", "industry", "news"],
    citations: true
  }
}

analyzer

通过模式识别进行代码和数据分析。

功能：

• 静态代码分析
• 依赖项分析
• 性能分析
• 安全扫描
• 数据模式识别

optimizer

性能优化与瓶颈解决。

功能：

• 算法优化
• 数据库查询调优
• 缓存策略设计
• 减小包体积
• 内存泄漏检测

---

创意与支持模式

designer

注重无障碍性的 UI/UX 设计。

功能：

• 界面设计
• 用户体验优化
• 无障碍合规性（WCAG 2.1）
• 设计系统创建
• 响应式布局设计

innovator

创意问题解决与新颖方案探索。

功能：

• 头脑风暴与构思
• 生成替代方案
• 技术评估
• 概念验证开发
• 创新可行性分析

documenter

全面的文档生成。

功能：

• API 文档（OpenAPI/Swagger）
• 架构图
• 用户指南和教程
• 代码注释和 JSDoc
• README 和变更日志维护

debugger

系统性调试和问题解决。

功能：

• 重现 Bug
• 根因分析
• 实施修复
• 防止回归
• 调试日志优化

tester

超越 TDD 的全面测试。

功能：

• 扩展测试套件
• 识别边界情况
• 性能测试
• 负载测试
• 混沌工程

memory-manager

知识管理和上下文保留。

功能：

• 跨会话记忆持久化
• 构建知识图谱
• 恢复上下文
• 提取学习模式
• 跟踪决策

---

激活方式

方式 1：MCP 工具（Claude Code 中首选）

最适用于：具备完整编排能力的集成式 Claude Code 工作流

// Basic mode execution
mcp__claude-flow__sparc_mode {
  mode: "<mode-name>",
  task_description: "<task description>",
  options: {
    // mode-specific options
  }
}

// Initialize swarm for complex tasks
mcp__claude-flow__swarm_init {
  topology: "hierarchical",  // or "mesh", "ring", "star"
  strategy: "auto",           // or "balanced", "specialized", "adaptive"
  maxAgents: 8
}

// Spawn specialized agents
mcp__claude-flow__agent_spawn {
  type: "<agent-type>",
  capabilities: ["<capability1>", "<capability2>"]
}

// Monitor execution
mcp__claude-flow__swarm_monitor {
  swarmId: "current",
  interval: 5000
}

方式 2：NPX CLI（备用）

最适用于：终端使用，或 MCP 工具不可用时

# Execute specific mode
npx claude-flow sparc run <mode> "task description"

# Use alpha features
npx claude-flow@alpha sparc run <mode> "task description"

# List all available modes
npx claude-flow sparc modes

# Get help for specific mode
npx claude-flow sparc help <mode>

# Run with options
npx claude-flow sparc run <mode> "task" --parallel --monitor

# Execute TDD workflow
npx claude-flow sparc tdd "feature description"

# Batch execution
npx claude-flow sparc batch <mode1,mode2,mode3> "task"

# Pipeline execution
npx claude-flow sparc pipeline "task description"

方式 3：本地安装

最适用于：已在本地安装 claude-flow 的项目

# If claude-flow is installed locally
./claude-flow sparc run <mode> "task description"

---

编排模式

模式 1：分层协调

最适用于：职责委派层级明确的复杂项目

// Initialize hierarchical swarm
mcp__claude-flow__swarm_init {
  topology: "hierarchical",
  maxAgents: 12
}

// Spawn coordinator
mcp__claude-flow__agent_spawn {
  type: "coordinator",
  capabilities: ["planning", "delegation", "monitoring"]
}

// Spawn specialized workers
mcp__claude-flow__agent_spawn { type: "architect" }
mcp__claude-flow__agent_spawn { type: "coder" }
mcp__claude-flow__agent_spawn { type: "tester" }
mcp__claude-flow__agent_spawn { type: "reviewer" }

模式 2：网状协调

最适用于：需要点对点通信的协作任务

mcp__claude-flow__swarm_init {
  topology: "mesh",
  strategy: "balanced",
  maxAgents: 6
}

模式 3：顺序流水线

最适用于：按顺序执行的工作流（规范 → 设计 → 编码 → 测试 → 审查）

mcp__claude-flow__workflow_create {
  name: "development-pipeline",
  steps: [
    { mode: "researcher", task: "gather requirements" },
    { mode: "architect", task: "design system" },
    { mode: "coder", task: "implement features" },
    { mode: "tdd", task: "create tests" },
    { mode: "reviewer", task: "review code" }
  ],
  triggers: ["on_step_complete"]
}

模式 4：并行执行

最适用于：可同时运行的独立任务

mcp__claude-flow__task_orchestrate {
  task: "build full-stack application",
  strategy: "parallel",
  dependencies: {
    backend: [],
    frontend: [],
    database: [],
    tests: ["backend", "frontend"]
  }
}

模式 5：自适应策略

最适用于：需求不断变化的动态工作负载

mcp__claude-flow__swarm_init {
  topology: "hierarchical",
  strategy: "adaptive",  // Auto-adjusts based on workload
  maxAgents: 20
}

---

TDD 工作流

完整 TDD 工作流

// Step 1: Initialize TDD swarm
mcp__claude-flow__swarm_init {
  topology: "hierarchical",
  maxAgents: 8
}

// Step 2: Research and planning
mcp__claude-flow__sparc_mode {
  mode: "researcher",
  task_description: "research testing best practices for feature X"
}

// Step 3: Architecture design
mcp__claude-flow__sparc_mode {
  mode: "architect",
  task_description: "design testable architecture for feature X"
}

// Step 4: TDD implementation
mcp__claude-flow__sparc_mode {
  mode: "tdd",
  task_description: "implement feature X with 90% coverage",
  options: {
    coverage_target: 90,
    test_framework: "jest",
    parallel_tests: true
  }
}

// Step 5: Code review
mcp__claude-flow__sparc_mode {
  mode: "reviewer",
  task_description: "review feature X implementation",
  options: {
    test_coverage_check: true,
    security_check: true
  }
}

// Step 6: Optimization
mcp__claude-flow__sparc_mode {
  mode: "optimizer",
  task_description: "optimize feature X performance"
}

红-绿-重构循环

// RED: Write failing test
mcp__claude-flow__sparc_mode {
  mode: "tester",
  task_description: "create failing test for shopping cart add item",
  options: { expect_failure: true }
}

// GREEN: Minimal implementation
mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "implement minimal code to pass test",
  options: { minimal: true }
}

// REFACTOR: Improve code quality
mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "refactor shopping cart implementation",
  options: { maintain_tests: true }
}

---

最佳实践

1. 记忆集成

始终使用 Memory 进行跨 Agent 协调：

// Store architectural decisions
mcp__claude-flow__memory_usage {
  action: "store",
  namespace: "architecture",
  key: "api-design-v1",
  value: JSON.stringify(apiDesign),
  ttl: 86400000  // 24 hours
}

// Retrieve in subsequent agents
mcp__claude-flow__memory_usage {
  action: "retrieve",
  namespace: "architecture",
  key: "api-design-v1"
}

2. 并行操作

在单条消息中批量执行所有相关操作：

// ✅ CORRECT: All operations together
[Single Message]:
  mcp__claude-flow__agent_spawn { type: "researcher" }
  mcp__claude-flow__agent_spawn { type: "coder" }
  mcp__claude-flow__agent_spawn { type: "tester" }
  TodoWrite { todos: [8-10 todos] }

// ❌ WRONG: Multiple messages
Message 1: mcp__claude-flow__agent_spawn { type: "researcher" }
Message 2: mcp__claude-flow__agent_spawn { type: "coder" }
Message 3: TodoWrite { todos: [...] }

3. Hook 集成

每种 SPARC 模式都应使用 Hook：

# Before work
npx claude-flow@alpha hooks pre-task --description "implement auth"

# During work
npx claude-flow@alpha hooks post-edit --file "auth.js"

# After work
npx claude-flow@alpha hooks post-task --task-id "task-123"

4. 测试覆盖率

保持至少 90% 的覆盖率：

• 为所有函数编写单元测试
• 为 API 编写集成测试
• 为关键流程编写 E2E 测试
• 覆盖边界情况
• 测试错误路径

5. 文档

在构建过程中同步编写文档：

• API 文档（OpenAPI）
• 架构决策记录（ADR）
• 复杂逻辑的代码注释
• 包含设置说明的 README
• 用于跟踪版本的变更日志

6. 文件组织

切勿将文件保存到根目录：

project/
├── src/           # Source code
├── tests/         # Test files
├── docs/          # Documentation
├── config/        # Configuration
├── scripts/       # Utility scripts
└── examples/      # Example code

---

集成示例

示例 1：全栈开发

[Single Message - Parallel Agent Execution]:

// Initialize swarm
mcp__claude-flow__swarm_init {
  topology: "hierarchical",
  maxAgents: 10
}

// Architecture phase
mcp__claude-flow__sparc_mode {
  mode: "architect",
  task_description: "design REST API with authentication",
  options: { memory_enabled: true }
}

// Research phase
mcp__claude-flow__sparc_mode {
  mode: "researcher",
  task_description: "research authentication best practices"
}

// Implementation phase
mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "implement Express API with JWT auth",
  options: { test_driven: true }
}

// Testing phase
mcp__claude-flow__sparc_mode {
  mode: "tdd",
  task_description: "comprehensive API tests",
  options: { coverage_target: 90 }
}

// Review phase
mcp__claude-flow__sparc_mode {
  mode: "reviewer",
  task_description: "security and performance review",
  options: { security_check: true }
}

// Batch todos
TodoWrite {
  todos: [
    {content: "Design API schema", status: "completed"},
    {content: "Research JWT implementation", status: "completed"},
    {content: "Implement authentication", status: "in_progress"},
    {content: "Write API tests", status: "pending"},
    {content: "Security review", status: "pending"},
    {content: "Performance optimization", status: "pending"},
    {content: "API documentation", status: "pending"},
    {content: "Deployment setup", status: "pending"}
  ]
}

示例 2：研究驱动的创新

// Research phase
mcp__claude-flow__sparc_mode {
  mode: "researcher",
  task_description: "research AI-powered search implementations",
  options: {
    depth: "comprehensive",
    sources: ["academic", "industry"]
  }
}

// Innovation phase
mcp__claude-flow__sparc_mode {
  mode: "innovator",
  task_description: "propose novel search algorithm",
  options: { memory_enabled: true }
}

// Architecture phase
mcp__claude-flow__sparc_mode {
  mode: "architect",
  task_description: "design scalable search system"
}

// Implementation phase
mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "implement search algorithm",
  options: { test_driven: true }
}

// Documentation phase
mcp__claude-flow__sparc_mode {
  mode: "documenter",
  task_description: "document search system architecture and API"
}

示例 3：重构遗留代码

// Analysis phase
mcp__claude-flow__sparc_mode {
  mode: "analyzer",
  task_description: "analyze legacy codebase dependencies"
}

// Planning phase
mcp__claude-flow__sparc_mode {
  mode: "orchestrator",
  task_description: "plan incremental refactoring strategy"
}

// Testing phase (create safety net)
mcp__claude-flow__sparc_mode {
  mode: "tester",
  task_description: "create comprehensive test suite for legacy code",
  options: { coverage_target: 80 }
}

// Refactoring phase
mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "refactor module X with modern patterns",
  options: { maintain_tests: true }
}

// Review phase
mcp__claude-flow__sparc_mode {
  mode: "reviewer",
  task_description: "validate refactoring maintains functionality"
}

---

常见工作流

工作流 1：功能开发

# Step 1: Research and planning
npx claude-flow sparc run researcher "authentication patterns"

# Step 2: Architecture design
npx claude-flow sparc run architect "design auth system"

# Step 3: TDD implementation
npx claude-flow sparc tdd "user authentication feature"

# Step 4: Code review
npx claude-flow sparc run reviewer "review auth implementation"

# Step 5: Documentation
npx claude-flow sparc run documenter "document auth API"

工作流 2：Bug 调查

# Step 1: Analyze issue
npx claude-flow sparc run analyzer "investigate bug #456"

# Step 2: Debug systematically
npx claude-flow sparc run debugger "fix memory leak in service X"

# Step 3: Create tests
npx claude-flow sparc run tester "regression tests for bug #456"

# Step 4: Review fix
npx claude-flow sparc run reviewer "validate bug fix"

工作流 3：性能优化

# Step 1: Profile performance
npx claude-flow sparc run analyzer "profile API response times"

# Step 2: Identify bottlenecks
npx claude-flow sparc run optimizer "optimize database queries"

# Step 3: Implement improvements
npx claude-flow sparc run coder "implement caching layer"

# Step 4: Benchmark results
npx claude-flow sparc run tester "performance benchmarks"

工作流 4：完整流水线

# Execute full development pipeline
npx claude-flow sparc pipeline "e-commerce checkout feature"

# This automatically runs:
# 1. researcher - Gather requirements
# 2. architect - Design system
# 3. coder - Implement features
# 4. tdd - Create comprehensive tests
# 5. reviewer - Code quality review
# 6. optimizer - Performance tuning
# 7. documenter - Documentation

---

高级功能

神经模式训练

// Train patterns from successful workflows
mcp__claude-flow__neural_train {
  pattern_type: "coordination",
  training_data: "successful_tdd_workflow.json",
  epochs: 50
}

跨会话记忆

// Save session state
mcp__claude-flow__memory_persist {
  sessionId: "feature-auth-v1"
}

// Restore in new session
mcp__claude-flow__context_restore {
  snapshotId: "feature-auth-v1"
}

GitHub 集成

// Analyze repository
mcp__claude-flow__github_repo_analyze {
  repo: "owner/repo",
  analysis_type: "code_quality"
}

// Manage pull requests
mcp__claude-flow__github_pr_manage {
  repo: "owner/repo",
  pr_number: 123,
  action: "review"
}

性能监控

// Real-time swarm monitoring
mcp__claude-flow__swarm_monitor {
  swarmId: "current",
  interval: 5000
}

// Bottleneck analysis
mcp__claude-flow__bottleneck_analyze {
  component: "api-layer",
  metrics: ["latency", "throughput", "errors"]
}

// Token usage tracking
mcp__claude-flow__token_usage {
  operation: "feature-development",
  timeframe: "24h"
}

---

性能优势

经验证的成果：

• 84.8% 的 SWE-Bench 问题解决率
• 通过优化减少 32.3% 的 token 用量
• 并行执行速度提升 2.8-4.4x
• 用于模式学习的 27+ 个神经模型
• 90%+ 的测试覆盖率标准

---

支持与资源

• 文档：https://github.com/ruvnet/claude-flow
• 问题反馈：https://github.com/ruvnet/claude-flow/issues
• NPM 包：https://www.npmjs.com/package/claude-flow
• 社区：Discord 服务器（链接见代码仓库）

---

快速参考

最常用命令

# List modes
npx claude-flow sparc modes

# Run specific mode
npx claude-flow sparc run <mode> "task"

# TDD workflow
npx claude-flow sparc tdd "feature"

# Full pipeline
npx claude-flow sparc pipeline "task"

# Batch execution
npx claude-flow sparc batch <modes> "task"

最常用的 MCP 调用

// Initialize swarm
mcp__claude-flow__swarm_init { topology: "hierarchical" }

// Execute mode
mcp__claude-flow__sparc_mode { mode: "coder", task_description: "..." }

// Monitor progress
mcp__claude-flow__swarm_monitor { interval: 5000 }

// Store in memory
mcp__claude-flow__memory_usage { action: "store", key: "...", value: "..." }

---

请记住：SPARC = 系统化、并行、敏捷、精炼、完整