qe-sparc-methodology

SPARC 方法論 - 包括的な開発フレームワーク

概要

SPARC（Specification、Pseudocode、Architecture、Refinement、Completion）は、Claude Flow のマルチエージェントオーケストレーション機能と統合された体系的な開発方法論です。初期調査からデプロイ、監視に至るまで、包括的なソフトウェア開発を支援する17種類の専門モードを提供します。

目次

1. 基本理念
2. 開発フェーズ
3. 利用可能なモード
4. 有効化方法
5. オーケストレーションパターン
6. TDD ワークフロー
7. ベストプラクティス
8. 統合例
9. 一般的なワークフロー

---

基本理念

SPARC 方法論では、次の点を重視します。

• 体系的なアプローチ: 仕様策定から完了までの構造化されたフェーズ
• テスト駆動開発: 実装前にテストを作成
• 並列実行: エージェントの同時連携による2.8～4.4倍の速度向上
• メモリ統合: エージェントやセッション間で永続的にナレッジを共有
• 品質優先: 包括的なレビュー、テスト、検証
• モジュール設計: 明確なインターフェースによる関心事の適切な分離

主な原則

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 を連携させたマルチエージェントタスクのオーケストレーションです。

機能:

• タスクを管理しやすい単位に分解
• エージェントの連携とリソースの割り当て
• 進捗の追跡と結果の統合
• 適応的な戦略の選択
• エージェント間の通信

使用方法:

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

swarm-coordinator

複雑なマルチエージェントワークフロー向けの専門的なスウォーム管理です。

機能:

• トポロジーの最適化（メッシュ、階層型、リング、スター）
• エージェントのライフサイクル管理
• ワークロードに応じた動的なスケーリング
• フォールトトレランスと復旧
• パフォーマンスの監視

workflow-manager

プロセスの自動化とワークフローのオーケストレーションです。

機能:

• ワークフローの定義と実行
• イベント駆動型のトリガー
• 順次および並列のパイプライン
• 状態管理
• エラー処理と再試行ロジック

batch-executor

高スループットの処理向け並列タスク実行。

機能：

• ファイル操作の並行処理
• バッチ処理の最適化
• リソースプール
• 負荷分散
• 進捗の集約

---

開発モード

coder

バッチファイル操作による自律的なコード生成。

機能：

• 機能の実装
• コードのリファクタリング
• バグ修正とパッチ適用
• 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 との連携：

• アーキテクチャ上の決定を保存
• コンポーネントの仕様を共有
• 設計の一貫性を維持
• アーキテクチャの変遷を追跡

設計パターン：

• レイヤードアーキテクチャ
• マイクロサービスパターン
• イベント駆動パターン
• ドメインモデリング
• Infrastructure as Code

使用方法：

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

体系的なデバッグと問題解決。

機能:

• バグの再現
• 根本原因の分析
• 修正の実装
• リグレッションの防止
• デバッグログの最適化

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. メモリの統合

エージェント間の連携には必ずメモリを使用してください:

// 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. 並列操作

関連する操作はすべて 1 つのメッセージにまとめてください:

// ✅ 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. フックの統合

すべての SPARC モードでフックを使用してください:

# 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: バグ調査

# 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% のトークン削減
• 並列実行による 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: "..." }

---

覚えておいてください: SPARC = 体系的、並列、アジャイル、洗練、完全