description: 仕様の包括的な技術設計を作成 argument-hint: [-y:$2] # 技術設計ジェネレーター - **ミッション**: 要件（WHAT）をアーキテクチャ設計（HOW）に変換する包括的な技術設計ドキュメントを生成 - **成功基準**: - すべての要件が明確なインターフェースを持つ技術コンポーネントにマップ - 適切なアーキテクチャ発見と調査の完了 - 設計が既存パターンに整合 - 複雑なアーキテクチャには視覚的ダイアグラムを含む ## コアタスク 承認済み要件に基づいて、機能 **$1** の技術設計ドキュメントを生成する。 ## 実行ステップ ### ステップ1: コンテキストの読み込み **必要なすべてのコンテキストを読み込み**: - `.cursor/$1/spec.json`、`requirements.md`、`design.md`（存在する場合） - `.cursor/templates/specs/design.md` からドキュメント構造 - `.cursor/rules/design-principles.md` から設計原則 - `.cursor/rules/spec-state-management.md` と `.cursor/rules/gate-invalidation-policy.md` から共通状態更新規則 - `.cursor/templates/specs/research.md` から発見ログ構造 - **`package.json`（プロジェクトルートに存在する場合）**: 既存の依存関係とバージョンを把握 - `.cursor/rules/artifacts-generation.md`（成果物の安全な初期作成ルール）を読み込み - `.cursor/$1/artifacts/data-model.md` / `.cursor/$1/artifacts/table-definition.md` が無ければ、テンプレから **init 作成（上書き禁止）** - テンプレ: `.cursor/templates/artifacts/create-data-model.md` / `.cursor/templates/artifacts/create-table-definition.md` - `.cursor/rules/frontend.md`（存在する場合）からフロントエンド設計原則 **要件承認の検証**: - `-y` フラグが提供された場合（$2 == "-y"）: spec.json で要件を自動承認 - それ以外: 承認状況を確認（未承認の場合は停止、安全性とフォールバック参照） ### ステップ2: 発見と分析 **重要: このフェーズは設計が完全で正確な情報に基づくことを保証。** - ブラウンフィールドでは、必要に応じて先に `/difference-check $1` を実行し、 既存実装とのギャップ情報を設計に取り込む。 1. **機能タイプの分類**: - **新機能**（グリーンフィールド）→ フル発見が必要 - **拡張**（既存システム）→ 統合重視の発見 - **シンプルな追加**（CRUD/UI）→ 最小限または発見なし - **複雑な統合** → 包括的な分析が必要 2. **既存パッケージの優先確認**（package.json が存在する場合）: - **優先原則**: 既にインストール済みのパッケージで要件を満たせる場合は、新規追加より既存を活用 - dependencies / devDependencies を確認し、使用可能なライブラリをリストアップ - 既存パッケージのバージョンと互換性を検証 - 不足している機能がある場合のみ、追加パッケージを検討 - **技術スタック記載ルール（必須）**: 設計ドキュメントの「技術スタック」セクションには、`package.json` から読み取った**実際のバージョン**を記載する（推測や汎用的なバージョンではなく、例: `next: "15.1.2"` なら "Next.js 15.1.2" と記載） 3. **適切な発見プロセスの実行**: **複雑/新機能の場合**: - `.cursor/rules/design-discovery-full.md` を読み込んで実行 - WebSearch/WebFetch を使用した徹底的な調査: - 最新のアーキテクチャパターンとベストプラクティス - 外部依存関係の検証（API、ライブラリ、バージョン、互換性） - 公式ドキュメント、移行ガイド、既知の問題 - パフォーマンスベンチマークとセキュリティ考慮事項 **拡張の場合**: - `.cursor/rules/design-discovery-light.md` を読み込んで実行 - 統合ポイント、既存パターン、互換性にフォーカス - Grep を使用して既存コードベースのパターンを分析 **シンプルな追加の場合**: - 正式な発見をスキップ、クイックパターンチェックのみ 4. **発見結果をステップ3用に保持**: - 外部APIの契約と制約 - 根拠を伴う技術的決定 - 従うまたは拡張する既存パターン - 統合ポイントと依存関係 - 特定されたリスクと緩和戦略 - 潜在的なアーキテクチャパターンと境界オプション（詳細を `research.md` に記録） - 将来の実装計画に向けた依存関係と実行順の考慮事項（`research.md` にキャプチャ） - **パッケージ選定結果**: - 既存パッケージの活用リスト（package.json から） - 追加推奨パッケージ（理由・用途を明記） - 不要または代替可能な既存パッケージ（あれば） 5. **発見結果をリサーチログに永続化**: - 共有テンプレートを使用して `.cursor/$1/research.md` を作成または更新 - 発見スコープと主要な発見をサマリーセクションに記録 - リサーチログトピックに調査、ソース、影響を記録 - テンプレートセクションを使用してアーキテクチャパターン評価、設計決定、リスクを文書化 - `research.md` の記述には spec.json で指定された言語を使用 ### ステップ3: 設計ドキュメントの生成 1. **設計テンプレートとルールの読み込み**: - `.cursor/templates/specs/design.md` から構造 - `.cursor/rules/design-principles.md` から原則 2. **設計ドキュメントの生成**: - **specs/design.md テンプレート構造と生成指示に厳密に従う** - **すべての発見結果を統合**: 調査した情報（API、パターン、技術）をコンポーネント定義、アーキテクチャ決定、統合ポイント全体で使用 - ステップ1で既存の design.md が見つかった場合、参照コンテキストとして使用（マージモード） - 設計ルールを適用: 型安全性、ビジュアルコミュニケーション、フォーマルトーン - spec.json で指定された言語を使用 - セクションが更新された見出し（"アーキテクチャパターンと境界マップ"、"技術スタックと整合性"、"コンポーネントとインターフェース契約"）を反映し、`research.md` からのサポート詳細を参照することを確認 3. **spec.json のメタデータを更新**: - 共通更新は `.cursor/rules/spec-state-management.md` と `.cursor/rules/gate-invalidation-policy.md` に従う - `phase: "design-generated"` を設定 - `approvals.design.generated: true, approved: false` を設定 - `approvals.design.checked: false` と `approvals.design.check_result: null` を設定 - `approvals.requirements.approved: true` を設定 - `quality_gates.design_check.status: "not_run"` を設定 - `quality_gates.review.status` / `quality_gates.final_check.status` / `traceability.status` は ポリシーに従って `not_run` または `stale` へ更新 ## 重要な制約 - **型定義は設計ドキュメントに含めない**: - 設計ドキュメントでは責任・振る舞い・制約を自然言語で記述 - 型定義は実装時にコードで定義（Prisma等のORMを使用する場合は自動生成される型を活用） - TypeScriptのインターフェースやコードブロックは設計ドキュメントに含めない - **最新情報**: 外部依存関係とベストプラクティスには WebSearch/WebFetch を使用 - **テンプレート準拠**: specs/design.md テンプレート構造と生成指示に厳密に従う - **設計フォーカス**: アーキテクチャとインターフェースのみ、実装コードなし - **要件トレーサビリティID**: requirements.md で定義された通りの数値要件IDのみを使用（例: "1.1"、"1.2"、"3.1"、"3.3"）。新しいIDを発明したりアルファベットラベルを使用しない。 ### 言語リマインダー - spec.json が設計出力に別の言語を要求しても、Markdownプロンプトコンテンツは英語のままにする。生成される design.md と research.md は spec の言語を使用すべき。 ## ツールガイダンス - **最初に読み込み**: アクション前にすべてのコンテキストを読み込み（specs、templates、rules） - **不確かな時は調査**: 外部依存関係、API、最新ベストプラクティスには WebSearch/WebFetch を使用 - **既存コードを分析**: Grep を使用してコードベースのパターンと統合ポイントを検索 - **最後に書き込み**: すべての調査と分析完了後にのみ design.md を生成 ## 出力説明 **コマンド実行出力**（design.md コンテンツとは別）: spec.json で指定された言語で簡潔なサマリーを提供: 1. **ステータス**: `.cursor/$1/design.md` に設計ドキュメント生成完了を確認 2. **発見タイプ**: どの発見プロセスが実行されたか（full/light/minimal） 3. **主要な発見**: 設計を形作った2-3の重要な洞察 4. **パッケージ選定サマリー**: - 既存パッケージで活用するもの - 追加推奨パッケージ（あれば理由と共に） 5. **次のアクション**: 承認ワークフローのガイダンス（安全性とフォールバック参照） 6. **状態更新**: design check / review / final check が未実行に戻った場合は明記 **フォーマット**: 簡潔なMarkdown（200語以内）- これはコマンド出力であり、設計ドキュメント自体ではない **注記**: 実際の設計ドキュメントは `.cursor/templates/specs/design.md` 構造に従う。 ## 安全性とフォールバック ### エラーシナリオ **要件が未承認**: - **実行停止**: 承認済み要件なしでは続行不可 - **ユーザーメッセージ**: "要件がまだ承認されていません。設計生成前に承認が必要です。" - **提案アクション**: "`/design $1 -y` を実行して要件を自動承認して進行" **要件が見つからない**: - **実行停止**: 要件ドキュメントが存在しなければならない - **ユーザーメッセージ**: "`.cursor/$1/requirements.md` に requirements.md が見つかりません" - **提案アクション**: "先に `/requirements $1` を実行して要件を生成してください" **テンプレートが見つからない**: - **ユーザーメッセージ**: "`.cursor/templates/specs/design.md` にテンプレートファイルがありません" - **提案アクション**: "リポジトリセットアップを確認するか、テンプレートファイルを復元" - **フォールバック**: 警告付きでインライン基本構造を使用 **発見の複雑さが不明確**: - **デフォルト**: フル発見プロセスを使用（`.cursor/rules/design-discovery-full.md`） - **根拠**: 重要なコンテキストを見逃すより過剰調査の方が良い - **無効な要件ID**: - **実行停止**: requirements.md に数値IDがない、または非数値の見出し（例: "Requirement A"）がある場合、停止して続行前に requirements.md の修正を指示。 ### 次のフェーズ: 実装 **設計が承認された場合**: - `.cursor/$1/design.md` で生成された設計をレビュー - **オプション**: `/check-design $1` でインタラクティブな品質レビューを実行 - その後 `/impl $1` で実装を開始 **修正が必要な場合**: - フィードバックを提供し `/design $1` を再実行 - 既存の設計は参照として使用（マージモード） **注記**: 実装に進む前に設計の承認が必須。