Spec Workflow MCP

# ワークフロープロセスガイド このガイドでは、Spec Workflow MCPを使用するための完全な仕様駆動開発ワークフローとベストプラクティスについて説明します。 ## 概要 仕様駆動ワークフローは構造化されたアプローチに従います： ``` ステアリング → 仕様 → 実装 → 検証 ``` 各フェーズは前のフェーズの上に構築され、体系的で十分に文書化された開発を保証します。 ## フェーズ1：ステアリングドキュメントによるプロジェクトセットアップ ### なぜステアリングドキュメント？ ステアリングドキュメントは、プロジェクトを整合させ一貫性を保つための高レベルのガイダンスを提供します。すべての開発決定のための北極星として機能します。 ### ステアリングドキュメントの作成 ``` 「プロジェクトのステアリングドキュメントを作成して」 ``` これにより3つの主要なドキュメントが生成されます： #### 1. プロダクトステアリング（`steering/product.md`） - 製品ビジョンとミッション - ターゲットユーザーとペルソナ - コア機能と優先順位 - 成功メトリクスとKPI - 非目標と制約 #### 2. 技術ステアリング（`steering/tech.md`） - アーキテクチャ決定 - 技術スタックの選択 - パフォーマンス要件 - セキュリティ考慮事項 - スケーラビリティアプローチ #### 3. 構造ステアリング（`steering/structure.md`） - プロジェクト構成 - ファイルとフォルダーの規則 - 命名規則 - モジュール境界 - ドキュメント構造 ### ステアリングのベストプラクティス 1. **早期に作成** - 仕様の前にステアリングをセットアップ 2. **更新を継続** - プロジェクトの進化に応じて改訂 3. **頻繁に参照** - 意思決定に使用 4. **広く共有** - チームの整合性を確保 ## フェーズ2：仕様作成 ### 3ドキュメントシステム 各仕様は3つの順次ドキュメントで構成されます： ``` 要件 → 設計 → タスク ``` ### 要件ドキュメント **目的**：何を構築する必要があるかを定義 **内容**： - 機能概要 - ユーザーストーリー - 機能要件 - 非機能要件 - 受け入れ基準 - 制約と仮定 **作成例**： ``` 「以下をサポートするユーザー通知システムの要件を作成して： - メール通知 - アプリ内通知 - プッシュ通知 - ユーザー設定 - 通知履歴」 ``` ### 設計ドキュメント **目的**：どのように構築するかを定義 **内容**： - 技術アーキテクチャ - コンポーネント設計 - データモデル - API仕様 - 統合ポイント - 実装アプローチ **自動生成**：要件承認後に作成 ### タスクドキュメント **目的**：構築するためのステップを定義 **内容**： - 階層的タスク分解 - 依存関係 - 作業見積もり - 実装順序 - テスト要件 **構造例**： ``` 1.0 データベースセットアップ 1.1 通知テーブルを作成 1.2 インデックスをセットアップ 1.3 マイグレーションスクリプトを作成 2.0 バックエンド実装 2.1 通知サービスを作成 2.1.1 メールハンドラー 2.1.2 プッシュハンドラー 2.2 APIエンドポイントを作成 2.3 認証を追加 3.0 フロントエンド実装 3.1 通知コンポーネントを作成 3.2 APIと統合 3.3 設定UIを追加 ``` ## フェーズ3：レビューと承認 ### 承認ワークフロー 1. **ドキュメント作成** - AIがドキュメントを生成 2. **レビューリクエスト** - 承認が自動的にリクエストされる 3. **ユーザーレビュー** - ダッシュボード/拡張機能でレビュー 4. **決定** - 承認、変更リクエスト、または却下 5. **改訂**（必要な場合） - フィードバックに基づいてAIが更新 6. **最終承認** - 実装のためにドキュメントをロック ### 承認決定の実施 #### 承認するとき - 要件が完全で明確 - 設計が述べられた問題を解決 - タスクが論理的で包括的 - 主要な懸念やギャップがない #### 変更をリクエストするとき - 重要な詳細が欠けている - 仕様が不明確 - より良いアプローチが利用可能 - 基準との整合性が必要 #### 却下するとき - 根本的な誤解 - 完全に間違ったアプローチ - 完全な再考が必要 ### 効果的なフィードバックの提供 良いフィードバック： ``` 「認証フローはセッションではなくJWTトークンを使用すべきです。 APIエンドポイントにレート制限を追加してください。 ネットワーク障害のエラー処理を含めてください。」 ``` 悪いフィードバック： ``` 「これは正しく見えません。修正してください。」 ``` ## フェーズ4：実装 ### タスク実行戦略 #### 順次実装 依存タスクに最適： ``` 「user-auth仕様のタスク1.1を実装して」 「次にタスク1.2を実装して」 「タスク1.3を続けて」 ``` #### 並行実装 独立したタスクの場合： ``` 「バックエンドで作業している間に、dashboard仕様のすべてのUIタスクを実装して」 ``` #### セクションベース実装 論理的なグループ化の場合： ``` 「payment仕様のすべてのデータベースタスクを実装して」 ``` ### 進捗追跡 以下を通じて実装を監視： - ダッシュボードタスクビュー - 進捗バー - ステータスインジケーター - 完了率 ### ブロッカーの処理 ブロックされた場合： 1. ブロッカーを文書化 2. 解決のためのサブタスクを作成 3. 可能であれば並行タスクに移動 4. タスクステータスを「ブロック中」に更新 ## フェーズ5：検証 ### テスト戦略 実装後： 1. **ユニットテスト** ``` 「通知サービスのユニットテストを作成して」 ``` 2. **統合テスト** ``` 「APIエンドポイントの統合テストを作成して」 ``` 3. **エンドツーエンドテスト** ``` 「完全な通知フローのE2Eテストを作成して」 ``` ### ドキュメント更新 ドキュメントを最新に保つ： ``` 「新しいエンドポイントのAPIドキュメントを更新して」 「READMEに使用例を追加して」 ``` ## ファイル構造と整理 ### 標準プロジェクト構造 ``` your-project/ ├── .spec-workflow/ │ ├── steering/ │ │ ├── product.md │ │ ├── tech.md │ │ └── structure.md │ ├── specs/ │ │ ├── user-auth/ │ │ │ ├── requirements.md │ │ │ ├── design.md │ │ │ └── tasks.md │ │ └── payment-gateway/ │ │ ├── requirements.md │ │ ├── design.md │ │ └── tasks.md │ └── approval/ │ └── [承認追跡ファイル] ├── src/ │ └── [実装] └── tests/ └── [テスト] ``` ### 命名規則 **仕様名**： - kebab-caseを使用：`user-authentication` - 説明的に：`payment-processing`（`payments`ではなく） - バージョンを避ける：`user-profile`（`user-profile-v2`ではなく） **ドキュメント名**： - 常に：`requirements.md`、`design.md`、`tasks.md` - すべての仕様で一貫 ## 高度なワークフロー ### 機能の反復 進化する機能の場合： 1. 初期仕様を作成 2. MVPを実装 3. 拡張仕様を作成 4. 元の仕様を参照 5. 既存の作業の上に構築 例： ``` 「以下を追加するuser-authの拡張仕様を作成して： - ソーシャルログイン（Google、Facebook） - 生体認証 - セッション管理の改善」 ``` ### リファクタリングワークフロー 1. **現在の状態をドキュメント化** ``` 「現在の認証システムをドキュメント化する仕様を作成して」 ``` 2. **改善を設計** ``` 「認証パフォーマンスを向上させるリファクタリングを設計して」 ``` 3. **移行を計画** ``` 「リファクタリングのための移行タスクを作成して」 ``` 4. **段階的に実装** ``` 「後方互換性を持ってリファクタリングタスクを実装して」 ``` ### バグ解決ワークフロー 1. **バグレポート** ``` 「ログインタイムアウト問題のバグレポートを作成して」 ``` 2. **調査** ``` 「バグ#45の根本原因を調査して」 ``` 3. **ソリューション設計** ``` 「タイムアウト問題の修正を設計して」 ``` 4. **実装** ``` 「バグ修正を実装して」 ``` 5. **検証** ``` 「バグ#45のリグレッションテストを作成して」 ``` ## ベストプラクティス ### 1. 仕様の粒度を維持 **良い**：機能ごとに1つの仕様 - `user-authentication` - `payment-processing` - `notification-system` **悪い**：過度に広い仕様 - `backend-system` - `all-features` ### 2. 順次ドキュメント作成 常に順序に従う： 1. 要件（何を） 2. 設計（どのように） 3. タスク（ステップ） 先に進まないでください。 ### 3. 実装前に承認を完了 - ✅ 要件を承認 → 設計を作成 - ✅ 設計を承認 → タスクを作成 - ✅ タスクをレビュー → 実装を開始 - ❌ 承認をスキップ → 実装の問題 ### 4. 仕様を更新し続ける 要件が変わったとき： ``` 「user-authの要件を更新してSSOサポートを含めて」 ``` ### 5. 一貫した用語を使用 以下で一貫性を維持： - 仕様名 - コンポーネント名 - API用語 - データベース命名 ### 6. 完了した仕様をアーカイブ ワークスペースをきれいに保つ： ``` 「完了したuser-auth仕様をアーカイブして」 ``` ## 一般的なパターン ### MVPから完全な機能へ 1. MVP仕様から始める 2. コア機能を実装 3. 拡張仕様を作成 4. 段階的に構築 5. 後方互換性を維持 ### マイクロサービス開発 1. サービスステアリングドキュメントを作成 2. サービス境界を定義 3. サービスごとに仕様を作成 4. 統合ポイントを定義 5. サービスを独立して実装 ### API優先開発 1. 最初にAPI仕様を作成 2. コントラクトを設計 3. ドキュメントを生成 4. エンドポイントを実装 5. クライアントSDKを作成 ## ワークフロー問題のトラブルシューティング ### 仕様が大きくなりすぎる **解決策**：小さな仕様に分割 ``` 「eコマース仕様を以下に分割して： - product-catalog - shopping-cart - checkout-process - order-management」 ``` ### 要件が不明確 **解決策**：明確化をリクエスト ``` 「要件には以下についてより詳細が必要です： - ユーザーロールと権限 - エラー処理シナリオ - パフォーマンス要件」 ``` ### 設計が要件と一致しない **解決策**：改訂をリクエスト ``` 「設計はマルチテナンシー要件に対応していません。 テナント分離を含めるように改訂してください。」 ``` ## 開発プロセスとの統合 ### Gitワークフロー 1. 仕様ごとに機能ブランチを作成 2. タスク完了後にコミット 3. コミットメッセージで仕様を参照 4. 仕様が完了したらPR ### CI/CD統合 - 完了したタスクのテストを実行 - 要件に対して検証 - 完了した機能をデプロイ - 成功メトリクスに対して監視 ### チームコラボレーション - ダッシュボードURLを共有 - チームメンバーに仕様を割り当て - お互いの仕様をレビュー - 承認を通じて調整 ## 関連ドキュメント - [ユーザーガイド](USER-GUIDE.ja.md) - 一般的な使用説明 - [プロンプティングガイド](PROMPTING-GUIDE.ja.md) - プロンプト例とパターン - [ツールリファレンス](TOOLS-REFERENCE.ja.md) - 完全なツールドキュメント - [インターフェースガイド](INTERFACES.ja.md) - ダッシュボードと拡張機能の詳細