sparc-methodology

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

概述

SPARC（Specification、Pseudocode、Architecture、Refinement、Completion）是一种系统化开发方法论，与此框架的多 Agent 编排能力集成。它提供 17 种专用模式，支持全面的软件开发，涵盖从初步研究到部署和监控的整个过程。

在 agent-studio 中： 如果以下示例中的 mcp__claude-flow__* 或 npx claude-flow 不可用，请使用 Task 工具启动 Agent（例如 planner、developer、qa、architect），并遵循 .claude/workflows/ 和 router-decision.md 中的工作流。

目录

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

使用 TaskCreate/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-Green-Refactor 循环

// 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. 记忆集成

始终使用记忆来协调多个 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" }
  TaskCreate { tasks: [8-10 tasks] }

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

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 task creation
TaskCreate {
  tasks: [
    {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.4 倍速度
• 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: "..." }

---

铁律

1. 绝不在完成规格阶段之前编写实现代码
2. 务必在精炼阶段的任何实现工作之前编写会失败的测试
3. 绝不在未完成当前阶段的所有评审关卡之前进入下一 SPARC 阶段
4. 务必在启动 Agent 之前，将复杂任务分解为带有明确依赖关系的子任务
5. 绝不在没有通过质量关卡的记录证据时，宣称阶段已完成

反模式

反模式	失败原因	正确做法
跳过规格阶段	实现针对了错误的需求	在编写任何代码之前定义需求、用户故事和约束
在测试之前实现	无法验证正确性；回归问题会漏网	在精炼阶段先编写会失败的测试，再编写任何功能代码
时间紧迫时跳过阶段	错过质量关卡；后续阶段会失败	在进入下一阶段之前完成所有评审关卡；这些关卡的存在自有其意义
未梳理依赖关系就启动 Agent	Agent 会互相阻塞或重复工作	在启动 Agent 之前梳理任务依赖关系和并行分组
无证据就标记阶段完成	未完成的工作会遗留到后续阶段	每个阶段都要求提供明确的关卡证据（测试结果、评审签字）

记忆协议（强制）

开始之前： 阅读 .claude/context/memory/learnings.md

完成之后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设工作可能中断：如果没有记录在记忆中，就等于没有发生。

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