Spec Workflow MCP

# プロンプティングガイド AIアシスタントを通じてSpec Workflow MCPと対話するための包括的なガイドで、例とベストプラクティスを掲載しています。 ## クイックリファレンス ### 基本的なコマンド ``` "[機能]の仕様を作成して" "すべての仕様をリストして" "[spec-name]のステータスを表示して" "[spec]のタスク[番号]を実装して" "ステアリングドキュメントを作成して" ``` ## 仕様の作成 ### 基本的な仕様作成 #### シンプルなリクエスト ``` "ユーザー認証の仕様を作成して" ``` AIは以下を作成します: - 要件ドキュメント - 設計ドキュメント（承認後） - タスク分解（設計承認後） #### 詳細なリクエスト ``` "payment-processingという名前の仕様を作成して、以下を含む: - Stripeを使用したクレジットカード決済 - PayPal統合 - 返金処理 - 決済イベントのWebhook処理 - PCI準拠の考慮事項" ``` #### 既存のドキュメントから ``` "@product-requirements.mdのPRDから仕様を作成して" ``` ``` "@figma-export.mdの設計ドキュメントに基づいて仕様を作成して" ``` ### 高度な仕様作成 #### 技術的な制約を含む ``` "リアルタイム通知の仕様を作成して、以下の要件を含む: - ライブ更新にWebSocketを使用 - 古いブラウザ向けにポーリングにフォールバック - 最大10,000の同時接続を処理 - メッセージの順序を維持 - オフラインキューのサポートを含む" ``` #### 受け入れ基準を含む ``` "検索機能の仕様を以下の受け入れ基準で作成して: - 結果が200ms以内に表示される - あいまい一致をサポート - 日付、カテゴリ、著者のフィルターを含む - 関連性スコアを表示 - タイプミスと同義語を処理" ``` #### マイクロサービス仕様 ``` "在庫マイクロサービスの仕様を作成して、以下を含む: - REST APIを公開 - ストレージにPostgreSQLを使用 - Kafkaにイベントを発行 - CQRSパターンを実装 - ヘルスチェックエンドポイントを含む" ``` ## 仕様の管理 ### リストとステータス #### 概要を取得 ``` "すべての仕様をリストして" "すべての仕様とその進捗を表示して" "承認待ちの仕様はどれ？" "現在進行中の仕様はどれ？" ``` #### 特定のステータス ``` "user-auth仕様のステータスを表示して" "payment-processingの進捗はどう？" "notification仕様で残っている作業を表示して" "user-profileで完了したタスクはどれ？" ``` #### フィルタリング ``` "50%以上完了している仕様を表示して" "承認待ちの仕様をリストして" "まだタスクが完了していない仕様はどれ？" "ブロックされているまたは停滞している仕様を表示して" ``` ### ドキュメント管理 #### ドキュメントの表示 ``` "user-authの要件を表示して" "paymentsの設計ドキュメントを表示して" "通知システムのタスクは何？" "search仕様のすべてのドキュメントを表示して" ``` #### ドキュメントの更新 ``` "user-auth要件を更新して2FAを含めて" "payment設計を改訂してStripe Connectを使用するようにして" "user-profileにセキュリティテストのタスクを追加して" "このフィードバックに基づいて要件を更新して: [feedback]" ``` ## 実装のプロンプト ### 個別のタスク #### 基本的な実装 ``` "user-authのタスク1.2を実装して" "payment仕様のタスク2.1.3を完了して" "notificationsの次の保留中のタスクに取り組んで" ``` #### コンテキストを含む ``` "TypeScriptとExpressを使用してuser-authのタスク1.2を実装して" "Prismaを使用してデータベース移行タスクを完了して" "REST規約に従ってAPIエンドポイントタスクを実装して" ``` ### バッチ実装 #### セクション別 ``` "user-authのすべてのデータベースタスクを実装して" "dashboard仕様のすべてのフロントエンドタスクを完了して" "paymentsのすべてのAPIタスクに取り組んで" ``` #### 優先度別 ``` "まず重要なタスクをすべて実装して" "user-profileのMVPタスクを完了して" "デモに必要なタスクに集中して" ``` #### 順次 ``` "user-authのタスク1.1から1.5を実装して" "セクション2のすべてのサブタスクを完了して" "セットアップタスクを順番に進めて" ``` ### 実装戦略 #### テスト駆動 ``` "タスク1.2について、まずテストを書いてから実装して" "タスク2.1を完全なテストカバレッジで実装して" "サービスタスクを実装しながら単体テストを作成して" ``` #### ドキュメント付き ``` "タスク1.3を実装してAPIをドキュメント化して" "インラインコメント付きで認証タスクを完了して" "タスク2.2を実装して使用例を作成して" ``` ## ステアリングドキュメント ### ステアリングの作成 #### 完全なセット ``` "eコマースプロジェクトのステアリングドキュメントを作成して" "SaaSアプリケーションのステアリングを設定して" "モバイルアプリのプロジェクトガイダンスを作成して" ``` #### 個別のドキュメント ``` "ユーザーエクスペリエンスに焦点を当てたプロダクトステアリングドキュメントを作成して" "マイクロサービスアーキテクチャのテクニカルステアリングを作成して" "モノレポセットアップの構造ステアリングを作成して" ``` #### コンテキストから ``` "@project-brief.mdに基づいてステアリングドキュメントを作成して" "@architecture.mdの技術的決定からステアリングを生成して" ``` ### ステアリングの更新 ``` "プロダクトステアリングを更新してB2B機能を含めて" "テクニカルステアリングを改訂してRESTの代わりにGraphQLを使用するようにして" "新しいモジュールシステムの構造ステアリングを更新して" ``` ## 承認ワークフロー ### フィードバックのリクエスト #### 特定の懸念事項を含む ``` "user-auth要件の承認をリクエストして - 特にセキュリティセクションを確認して" "payment設計のレビューを依頼して - エラー処理に焦点を当てて" "タスク分解のフィードバックをリクエストして - 細かすぎる？" ``` #### 修正リクエスト ``` "要件に以下の詳細を追加する必要があります: - エラー処理シナリオ - パフォーマンス要件 - セキュリティの考慮事項 修正して再提出してください" ``` ### 承認の決定 #### 承認 ``` "user-auth要件を承認して" "設計は良さそう、承認して" "タスク分解をそのまま受け入れて" ``` #### 変更のリクエスト ``` "要件への変更をリクエスト: - マルチテナントサポートを追加 - レート制限を含める - データ保持ポリシーを指定" ``` #### 却下 ``` "現在の設計を却下 - 代わりにイベント駆動アーキテクチャを使用する必要がある" "要件をやり直して - 範囲が広すぎる" ``` ## バグワークフロー ### バグの報告 #### 詳細なレポート ``` "バグレポートを作成: タイトル: 特殊文字でログインが失敗する 手順: 1) '+'を含むメールを入力 2) フォームを送信 3) エラーを確認 期待: ログイン成功 実際: 500エラー 優先度: 高 環境: 本番" ``` #### エラーログから ``` "このエラーからバグレポートを作成して: [スタックトレースを貼り付け]" "Sentryアラートからこのバグをドキュメント化して: [リンク]" ``` ### バグの解決 #### 調査 ``` "バグ#45の根本原因を調査して" "決済webhookが失敗する理由を分析して" "検索エンドポイントのパフォーマンス問題をデバッグして" ``` #### 修正の実装 ``` "ユーザー認証のバグ#45の修正を作成して" "決済タイムアウト問題の解決策を実装して" "通知サービスのメモリリークを修正して" ``` ## 実装中の変更 ### 開発中に仕様が変更された場合 要件と設計は実装中に進化することがよくあります。その場合、完了した作業を保持しながらtasks.mdを現在の仕様に合わせる必要があります。 ### タスク更新機能の使用 AIは、refresh-tasksプロンプトを通じて包括的なタスク更新手順にアクセスできます。変更についてAIに通知するだけです: #### 基本的なタスク更新 ``` "要件が更新されました。現在のrequirements.mdとdesign.mdに合わせてtasks.mdを更新してください。" ``` #### コンテキスト付き詳細タスク更新 ``` "仕様を以下の変更で更新しました: - レポートモジュールを削除 - データベースをMongoDBからPostgreSQLに変更 - ソーシャルログイン機能を追加 タスク更新プロセスに従ってtasks.mdを更新してください: 1. 完了および進行中のタスクをすべて保持 2. データベース変更の移行タスクを追加 3. レポートモジュールの保留中タスクを削除 4. ソーシャルログインの新しいタスクを追加" ``` #### 移行が必要なアーキテクチャ変更 ``` "REST APIからGraphQLに切り替えています。いくつかのRESTエンドポイントはすでに実装されています。tasks.mdを以下で更新してください: 1. 完了したRESTワークをすべて保持 2. RESTロジックをGraphQLリゾルバーでラップする移行タスク 3. 新しいGraphQL実装タスク 4. GraphQL検証後にRESTを削除するクリーンアップタスク" ``` ### 期待されるAIの動作 タスク更新をリクエストすると、AIは以下を実行します: 1. **現在の状態を分析** - 現在の仕様についてrequirements.mdとdesign.mdを読む - 完了、進行中、保留中のタスクを特定 - 追加、削除、変更された機能を判断 2. **完了した作業を保持** - すべての[x]完了タスクを変更せずに保持 - すべての[-]進行中タスクを変更せずに保持 - 削除された機能の完了作業にメモを追加 3. **アーキテクチャ変更を処理** - 更新が必要な完了作業の後に移行タスクを追加 - 段階的移行の移行タスクを作成 - 古い実装を削除する前に検証タスクを含める 4. **保留中のタスクを更新** - 削除された機能の保留中タスクを削除 - 変更された要件の保留中タスクを更新 - 新機能の新しいタスクを追加 5. **タスク構造を維持** - 連番を維持 - タスク形式を保持 - 要件参照を含める - 依存関係の順序を維持 ### シナリオ例 #### 機能の削除 ``` "仕様からレポートモジュールを削除することにしました。それに応じてtasks.mdを更新してください。" ``` 期待されるAIの動作: - すべての完了したレポートタスクを[x]ステータスで保持 - すべての進行中のレポートタスクを[-]ステータスで保持 - 保留中の[ ]レポートタスクのみを削除 - メモを追加: "_注: レポート機能は仕様から削除されましたが、完了した作業は保持されています_" #### 完了した作業を伴うアーキテクチャ変更 ``` "MongoDBからPostgreSQLに切り替えています。保留中のデータベースタスクを更新してください。MongoDBスキーマと接続ロジックはすでに実装されています。" ``` 期待されるAIの動作: - 完了したすべてのMongoDBタスクを書かれたとおりに保持 - 進行中のすべてのMongoDBタスクを書かれたとおりに保持 - 完了したMongoDBワークの直後に新しい移行タスクを追加: - MongoDBスキーマをPostgreSQLテーブルに移行 - MongoDB接続ロジックをPostgreSQLクライアントに置き換え - データベースクエリをMongoDBからPostgreSQL構文に更新 - 既存のMongoDBデータをPostgreSQLに移行 - PostgreSQLの環境設定を更新 - 移行検証後にMongoDBの依存関係を削除 - 残りの保留中データベースタスクをPostgreSQLを使用するように更新 - タスクナンバリングシーケンスを維持 #### 機能の追加 ``` "認証仕様にソーシャルログインを追加してください。要件と設計は更新されています。" ``` 期待されるAIの動作: - 論理的な挿入ポイントのために現在のタスク構造を分析 - 適切なナンバリングで新しいソーシャルログインタスクを追加 - ソーシャルログインの特定の要件を参照 - 新しいタスクが依存関係の順序を維持することを確認 - 基本認証がすでに実装されている場合、統合タスクを追加 ### アーキテクチャ移行の処理 アーキテクチャ変更がすでに実装されたコードに影響を与える場合: #### RESTからGraphQLへの移行 ``` "RESTからGraphQLに変更しています。いくつかのRESTエンドポイントはすでに実装されています。" ``` 期待されるタスクの追加: - 完了したRESTエンドポイントタスクを保持 - GraphQLスキーマ定義タスクを追加 - リゾルバー実装タスクを追加 - 既存のRESTロジックをGraphQLリゾルバーでラップする移行タスクを追加 - クライアントコードをGraphQLを使用するように更新するタスクを追加 - GraphQL検証後にRESTエンドポイントを削除するクリーンアップタスクを追加 #### モノリスからマイクロサービスへの分割 ``` "モノリシックなユーザーサービスを個別の認証とプロファイルサービスに分割しています。" ``` 期待されるタスクの追加: - 完了したモノリシックサービスタスクを保持 - サービス分離タスクを追加 - サービス間通信タスクを追加 - データベースを分割する場合はデータ移行タスクを追加 - 新しいサービスのデプロイ設定タスクを追加 - サービス検証後にモノリシックコードを削除するクリーンアップタスクを追加 ### 移行のタスク形式 移行タスクはその目的を明確に示す必要があります: ``` "タスク更新後、以下を追加したことを確認します: - [ ] 2.4 MongoDBスキーマをPostgreSQLテーブルに移行 - ファイル: src/database/migrations/mongo-to-postgres.ts - ドキュメントスキーマをリレーショナルテーブルに変換 - 埋め込みドキュメントを外部キー関係にマッピング - すべての既存データ関係を保持 - 目的: データベースレイヤーを新しいアーキテクチャに移行 - _活用: タスク2.1-2.3で完了したMongoDBスキーマ_ - _要件: 設計セクション3.2_" ``` ### AIへの変更の伝達 仕様の変更についてAIに通知する際: #### 変更と影響について具体的に ``` "決済処理の要件が変更されました。PayPalの代わりにStripeが必須になりました。PayPal webhookハンドラーはすでに実装されています。移行タスクを含めてこの変更を反映するようにtasks.mdを更新してください。" ``` #### 保持と移行のコンテキストを提供 ``` "MongoDBからPostgreSQLに移行していますが、その作業はすでに完了しているため、完了したすべてのMongoDBタスクを保持してください。実装されたMongoDBコードをPostgreSQLに移行する移行タスクを追加してください。" ``` #### 検証をリクエスト ``` "tasks.mdの更新後、requirements.mdのすべての要件に対応するタスクがあること、アーキテクチャ変更の移行パスが存在すること、削除された機能の保留中タスクがないことを確認してください。" ``` ### 段階的移行戦略 主要なアーキテクチャ変更の場合、AIは段階的移行をサポートするタスクを作成する必要があります: 1. 既存のアーキテクチャと並行して新しいアーキテクチャを実装 2. 互換性レイヤータスクを追加 3. 機能を段階的に移行 4. 各移行ステップを検証 5. 完全な検証後にのみ古い実装を削除 これにより、移行中もアプリケーションが機能し続けることが保証されます。 ### Refresh Tasksプロンプトの使用 refresh tasksプロンプトを明示的に呼び出すこともできます: ``` "user-auth仕様にrefresh-tasksプロンプトを使用してください。変更点は: 認証にJWTの代わりにOAuth2に切り替えました。" ``` AIは包括的な更新手順に従って、完了したすべての作業を保持しながらタスクを更新します。 ## 高度なパターン ### マルチ仕様ワークフロー #### 関連する仕様 ``` "以下と統合するadmin-dashboardの仕様を作成して: - user-management仕様 - analytics仕様 - reporting仕様" ``` #### 仕様の依存関係 ``` "以下に依存するnotificationsの仕様を作成して: - user-authが完了していること - message-queueが実装されていること - email-serviceが利用可能であること" ``` ### 段階的開発 #### まずMVP ``` "user-profilesのMVP仕様を以下のみで作成して: - 基本的なプロファイル作成 - 表示名とアバター - 公開プロファイルビュー （ソーシャル機能は後で追加します）" ``` #### 拡張仕様 ``` "user-authの拡張仕様を作成して以下を追加: - ソーシャルログイン（Google、GitHub） - 生体認証 - 拡張セッション管理 - アカウントリンク" ``` ### 複雑なシナリオ #### 移行仕様 ``` "MongoDBからPostgreSQLへの移行仕様を作成して: - 現在のスキーマをドキュメント化 - 新しいリレーショナル構造を設計 - ゼロダウンタイム移行を計画 - ロールバック手順を含める" ``` #### リファクタリング仕様 ``` "以下を行うリファクタリング仕様を作成して: - モノリスをサービスに分割 - 共有コンポーネントを抽出 - テストカバレッジを80%に改善 - 後方互換性を維持" ``` #### パフォーマンス仕様 ``` "パフォーマンス最適化仕様を作成して: - 現在のボトルネックをプロファイル - キャッシング戦略を設計 - データベースインデックス作成を計画 - モニタリングを実装" ``` ## ワークフローの組み合わせ ### 完全な機能フロー ``` 1. "プロジェクトのステアリングドキュメントを作成して" 2. "ユーザー認証の仕様を作成して" 3. "要件をレビューして承認して" 4. "設計をレビューして承認して" 5. "タスク1.1を実装して - データベーススキーマ" 6. "タスク1.2を実装して - 認証サービス" 7. "認証フローのテストを作成して" 8. "すべてのタスクを完了としてマークして" ``` ### 並行開発 ``` "要件をレビューしている間に、API設計のドラフトを開始して" "フロントエンドとバックエンドの両方の仕様を並行して作成して" "バックエンドチームがAPIタスクを行う間にUIタスクに取り組んで" ``` ### 反復的改善 ``` 1. "検索の初期仕様を作成して" 2. "基本的な検索を実装して（タスク1-3）" 3. "高度な検索の拡張仕様を作成して" 4. "フィルタリングとソート機能を追加して" 5. "検索パフォーマンスの最適化仕様を作成して" ``` ## コンテキスト対応プロンプト ### プロジェクトコンテキストの使用 ``` "既存のパターンに従った仕様を作成して" "コードベースと一貫性を持ってこのタスクを実装して" "現在のアーキテクチャと統合するようにこの機能を設計して" ``` ### 他の仕様の参照 ``` "user-authに似た仕様を作成して、ただし管理者認証用" "payment仕様と同じ設計パターンを使用して" "notification仕様のタスク構造に従って" ``` ### 以前の作業の構築 ``` "user-auth仕様を拡張してチーム管理を含めて" "既存のREST API仕様にGraphQLサポートを追加して" "機械学習機能で検索仕様を拡張して" ``` ## 効果的なプロンプティングのヒント ### 具体的に ❌ **曖昧**: "ログイン仕様を作成して" ✅ **具体的**: "2FA、ログイン状態の保持、パスワードリセットを含むメール/パスワードログインの仕様を作成して" ### コンテキストを提供 ❌ **コンテキストなし**: "タスクを実装して" ✅ **コンテキスト付き**: "既存のExpressミドルウェアとPostgreSQLデータベースを使用してタスク1.2を実装して" ### 明確な期待を設定 ❌ **不明確**: "より良くして" ✅ **明確**: "設計を改善して、現在のトラフィックの10倍を200ms未満の応答時間で処理できるようにして" ### 段階的なリクエストを使用 ❌ **多すぎる**: "5つの仕様を作成してすべて実装して" ✅ **段階的**: "まずuser-auth仕様を作成して、次に進む前にレビューしましょう" ### 既存の作業を参照 ❌ **新規開始**: "新しい決済システムを作成して" ✅ **構築**: "決済仕様を拡張してサブスクリプション課金を追加して" ## 共通パターンライブラリ ### CRUD操作 ``` "製品のCRUD操作の仕様を作成して、以下を含む: - 検証付き作成 - ページネーションとフィルタリング付き読み取り - 楽観的ロック付き更新 - 回復オプション付き論理削除" ``` ### 認証と認可 ``` "以下を含む認証仕様を作成して: - JWTベースの認証 - ロールベースのアクセス制御 - APIキー管理 - セッション処理 - リフレッシュトークンローテーション" ``` ### リアルタイム機能 ``` "リアルタイムチャットの仕様を作成して: - WebSocket接続 - メッセージ永続化 - 入力インジケーター - 既読通知 - オフラインメッセージキュー" ``` ### ファイル管理 ``` "ファイルアップロード仕様を作成して: - 大きなファイルのチャンクアップロード - 進捗追跡 - 再開機能 - ウイルススキャン - CDN統合" ``` ### アナリティクスとレポート ``` "アナリティクス仕様を作成して: - イベント追跡 - カスタムディメンション - リアルタイムダッシュボード - スケジュールレポート - データエクスポートオプション" ``` ## トラブルシューティングプロンプト ### 問題が発生した場合 ``` "この仕様が表示されないのはなぜ？" "タスクが完了しない理由をデバッグして" "承認を妨げているものは何？" "このエラーを理解するのを手伝って" ``` ### 行き詰まりの解消 ``` "次に何をすべき？" "進捗を妨げているものを表示して" "待っている間に取り組めるタスクは？" "この依存関係をどう解決する？" ``` ## 関連ドキュメント - [ユーザーガイド](USER-GUIDE.md) - 一般的な使用方法 - [ワークフロープロセス](WORKFLOW.md) - ワークフローの理解 - [ツールリファレンス](TOOLS-REFERENCE.md) - 完全なツールドキュメント - [トラブルシューティング](TROUBLESHOOTING.md) - 一般的な問題の解決