basic-design-workflow

# 基本設計・完全ワークフロー 要件定義書を入力として基本設計書を作成し、スペシャリストによるレビュー（合格基準9点）を通過するまで修正を繰り返す完全自動化ワークフローです。 ## 入力 $ARGUMENTS (要件定義書のパスなど) --- ## 全体フロー | Phase | 名称 | 内容 | |-------|------|------| | 0 | 技術スタック完全性チェック | 要件定義書の技術スタック検証 | | 0.5-A | 技術スタック確認ヒアリング | 定義済み技術の確認 + 未定義レイヤーの提案【必須】 | | 0.5-B | 既存設計整合性確認 | 既存基本設計書との整合性チェック（追加仕様時） | | 1 | コンテキスト解析 & ドラフト作成 | ``basic-design-writer` skill` による作成 | | 2 | 品質保証ループ | ``basic-design-reviewer` skill` によるレビュー（9点以上、最大3回） | | 2.5 | ユーザー承認 | `approval-gate` skill | | 3 | 詳細設計準備 | フォルダ構造作成、リンク設定 | > **Phase規約**: `workflow-phase-convention` skill を参照 --- ## 前提条件 - 要件定義書が8点以上でレビュー合格済みであること - 要件定義書に技術スタックが定義されていること（未定義の場合は未解決課題として扱う） - **推奨**: `/tech-catchup-workflow` で技術調査レポートが作成済みであること - 技術調査レポートがある場合、Phase 0.5-Aのヒアリングで参照される - 未実施でもワークフローは続行可能（ただし最新情報の把握漏れリスクあり） --- ## サーキットブレーカー | 条件 | アクション | |------|----------| | **最大リトライ回数**: 3回 | 3回修正しても9点に届かない場合、現状ファイルに警告マークを付与して終了 | | **スコア悪化検知** | 前回より低下した場合、即座に中断 | | **技術スタック未確認** | Phase 0.5-A ヒアリングを必ず実行 | --- ## 実行プロセス ### Phase 0: 技術スタック完全性チェック 要件定義書の技術スタックを検証し、Phase 0.5-A のヒアリング準備を行う。 **目的**: 定義済み/未定義のレイヤーを特定し、ヒアリングの焦点を明確にする。 **チェック項目:** | レイヤー | 必須/推奨 | 評価 | |---------|----------|------| | フロントエンド | 必須 | ✅ 定義済み / ❌ 未定義 | | バックエンド | 必須 | ✅ 定義済み / ❌ 未定義 | | データベース | 必須 | ✅ 定義済み / ❌ 未定義 | | 認証方式 | 必須 | ✅ 定義済み / ❌ 未定義 | | UIライブラリ | 推奨 | ✅ 定義済み / ❌ 未定義 | | 状態管理 | 推奨 | ✅ 定義済み / ❌ 未定義 | | ORM | 推奨 | ✅ 定義済み / ❌ 未定義 | | インフラ/クラウド | 推奨 | ✅ 定義済み / ❌ 未定義 | | CI/CD | 推奨 | ✅ 定義済み / ❌ 未定義 | | テスト | 推奨 | ✅ 定義済み / ❌ 未定義 | | モニタリング | 推奨 | ✅ 定義済み / ❌ 未定義 | **出力**: Phase 0.5-A に渡す「定義済み/未定義一覧」 --- ### Phase 0.5-A: 技術スタック確認ヒアリング【必須】 **常に実行**。要件定義書の技術スタックが定義済みでも、ユーザーに確認を行う。 **目的**: 技術選定の認識齟齬を防ぎ、未定義レイヤーを明確にする。 **実行内容:** 1. **技術調査レポート確認**: `docs/research/TECH-*.md` が存在する場合、内容を参照 - Breaking Changes、非推奨機能を考慮 - 新機能の活用可能性を検討 2. **要件分析**: 要件定義書からパフォーマンス/セキュリティ/可用性要件を抽出 3. **現状サマリー提示**: 定義済み/未定義のレイヤーを一覧表示 ```markdown ## 技術スタック確認 ### 定義済み（要件定義書より） | レイヤー | 技術 | 確認 | |---------|------|------| | フロントエンド | Next.js | ✅ このまま進めてよいですか？ | | バックエンド | Node.js | ✅ このまま進めてよいですか？ | ### 未定義（提案します） | レイヤー | 推奨 | 理由 | |---------|------|------| | UIライブラリ | shadcn/ui | カスタマイズ性、軽量 | | ORM | Prisma | 型安全、マイグレーション管理 | | 認証 | NextAuth.js | Next.js統合 | ``` 4. **ユーザー選択**: ```markdown **対応を選択してください**: 1. 承認 → 提案内容を確認して続行 2. 変更 → 変更したい技術を指定 3. スキップ → 確認不要で続行 > 番号を選択してください（1-3）: ``` 5. **選定確定**: ユーザー回答を元に技術スタックを確定 **ヒアリング対象（11レイヤー）:** | # | レイヤー | 例 | |---|---------|-----| | 1 | フロントエンド | Next.js / Nuxt.js / SvelteKit | | 2 | UIライブラリ | shadcn/ui / MUI / Chakra UI | | 3 | 状態管理 | TanStack Query+Zustand / Redux | | 4 | バックエンド | Node.js / Go / Python | | 5 | データベース | PostgreSQL / MySQL / MongoDB | | 6 | ORM | Prisma / Drizzle / TypeORM | | 7 | 認証 | NextAuth.js / Clerk / 自前JWT | | 8 | インフラ | Vercel+Supabase / AWS / GCP | | 9 | CI/CD | GitHub Actions / GitLab CI | | 10 | テスト | Vitest+Playwright | | 11 | モニタリング | Sentry / Datadog | **スキップ条件:** - ユーザーが選択肢「3. スキップ」を選択した場合のみ > **注意**: 「要件定義書で定義済み」だけではスキップしない。必ずユーザーに確認サマリーを提示する。 > **重要**: ヒアリング後も未確定の項目は「要選定（I-XXX）」と明記すること。 **仮定の明示ルール:** 基本設計書で仮定を置く場合は以下のフォーマットを使用： - 「要選定（I-XXX）」と記載し、未解決課題IDを付与 - 仮定で進める場合は「【仮定】」プレフィックスを使用 - 例: 「【仮定】React/Next.js（I-007で確定予定）」 --- ### Phase 0.5-B: 既存設計書との整合性確認【追加仕様時必須】 > **トリガー**: `docs/designs/basic/` に既存の基本設計書が存在する場合 **目的**: 追加仕様が既存設計と矛盾しないことを確認し、アーキテクチャへの影響を特定する。 **実行内容:** 1. **既存基本設計書の特定**: - `docs/designs/basic/BASIC-*.md` を検索 - 関連する基本設計書を特定（同一プロジェクト/システム） 2. **整合性チェック項目**: | チェック項目 | 確認内容 | 矛盾時のアクション | |-------------|---------|------------------| | アーキテクチャ互換性 | 既存システム構成に追加可能か | 統合方針を明記 | | 技術スタック一貫性 | 既存の技術選定と矛盾しないか | 差異がある場合は理由を明記 | | API設計互換性 | 既存APIとの整合性 | 既存API拡張 or 新規API設計を選択 | | データモデル互換性 | 既存DBスキーマとの整合性 | マイグレーション計画を作成 | | 画面ID/機能ID重複 | S-XXX/F-XXXが既存と重複しないか | 連番を調整 | 3. **アーキテクチャ影響分析**: ```markdown ## 既存設計書との整合性チェック結果 ### 関連する既存基本設計書 | ドキュメント | 関連度 | 影響 | |-------------|--------|------| | BASIC-XXX-001_既存機能.md | 高 | コンポーネント追加 | ### アーキテクチャ影響分析 | 既存コンポーネント | 影響 | 対応方針 | |------------------|------|---------| | Backend | 変更あり | 新規モジュール追加 | | Frontend | 変更あり | 新規画面追加 | | 共通モジュール | 変更なし | - | ### 技術スタック差異 | レイヤー | 既存 | 追加仕様 | 判定 | |---------|------|---------|------| | バックエンド | Rust 1.70 | Rust 1.75 | ⚠️ バージョンアップ必要 | | 新規依存 | - | serde_yaml | ✅ 追加可能 | ### データモデル変更 - 新規テーブル: `statistics` (追加) - 既存テーブル変更: なし - マイグレーション: 必要 ``` 4. **ユーザー確認（影響がある場合）**: ```markdown ⚠️ 既存設計への影響が検出されました。 **影響サマリー**: - アーキテクチャ変更: あり（バックエンドにモジュール追加） - 技術スタック変更: あり（依存ライブラリアップグレード） - DB変更: あり（新規テーブル追加） **対応方針を選択してください**: 1. 統合 → 既存基本設計書に追記 + 差分ドキュメント作成 2. 新規 → 新規基本設計書として独立作成（既存への影響は変更履歴に記載） 3. 中断 → 確認後に再開 > 番号を選択してください（1-3）: ``` **スキップ条件:** - `docs/designs/basic/` に既存基本設計書が存在しない（新規プロジェクト） - ユーザーから「独立設計として作成」と明示的に指示された場合 **完了条件:** - 既存設計書との整合性チェックが完了 - 影響がある場合はユーザー確認済み - 作成方針（統合 or 新規）が決定 - 必要に応じてマイグレーション計画が作成 --- ### Phase 1: コンテキスト解析 & ドラフト作成 (basic-design-writer) 1. **要件解析**: 要件定義書から機能一覧、非機能要件、技術制約を抽出 2. **技術スタック検証**: Phase 0の結果を反映 3. **既存設計との統合**: Phase 0.5-Bの結果を反映（追加仕様の場合） 4. **ドラフト作成**: `docs/designs/basic/BASIC-[カテゴリ]-[連番]_[機能名].md` を作成 **ドラフトに含めるべき内容:** - システムアーキテクチャ図 - 機能一覧（機能ID付き） - **画面一覧**（画面ID付き）← 詳細設計で使用 - API一覧 - データモデル概要 - 技術スタック（未選定項目は「要選定」と明記） --- ### Phase 2: 品質保証ループ (basic-design-reviewer) 1. **レビュー**: `basic-design-reviewer` エージェントがレビュー - 要件との整合性 - アーキテクチャの妥当性 - **技術スタックの網羅性**（追加チェック項目） - **仮定の明示**（未選定技術は「要選定」と明記されているか） - **要件との整合性**（要件定義書の技術制約と一致しているか） 2. **判定**: - **スコア >= 9**: 合格。Phase 3へ - **スコア < 9**: 修正ループ（最大3回） **レビュー観点チェックリスト:** ``` 【技術スタック完全性】★強化項目 □ 全レイヤー（FE/BE/DB/インフラ）の技術が定義されているか □ 技術スタック確認ヒアリングが実施されたか □ 各技術の選定理由が明記されているか（要件との適合性） □ 未選定の技術は「要選定（I-XXX）」と明記されているか □ 要件定義書の技術制約と一致しているか □ 仮定を置いている場合「【仮定】」プレフィックスがあるか □ UIライブラリ・状態管理・ORM・テスト等の推奨レイヤーも考慮されているか 【アーキテクチャ】 □ システム構成図が明確か □ コンポーネント間の依存関係が適切か □ スケーラビリティが考慮されているか □ 選定技術がアーキテクチャ図に反映されているか 【機能・画面一覧】 □ 全機能にIDが付与されているか □ 全画面にIDが付与されているか（詳細設計で使用） □ 優先度・フェーズが設定されているか ``` --- ### Phase 2.5: ユーザー承認ゲート【必須】 > **共通仕様・出力形式**: `approval-gate` skill を参照 | 項目 | 値 | |------|-----| | ドキュメント種別 | 基本設計書 | | 合格基準 | 9点以上 | | 次のアクション | 詳細設計準備（フォルダ構造作成） | **重要**: ユーザーからの明示的な応答があるまで次のフェーズに進んではならない。 --- ### Phase 3: 詳細設計準備 1. **機能抽出**: 基本設計書の機能一覧から、詳細設計が必要な単位を特定 2. **フォルダ作成**: `docs/designs/detailed/{機能名}/` などのフォルダ構造を自動生成 3. **リンク設定**: 基本設計書に詳細設計へのリンクを追加 **フォルダ構成:** ``` docs/designs/detailed/{親機能名}/ ├── README.md # 概要・インデックス ├── {サブ機能1}/ ├── {サブ機能2}/ └── 共通/ ├── データベース設計書.md ├── インフラ設計書.md └── セキュリティ設計書.md ``` --- ### Phase 3.5: 次ステップ選択【必須】 > **共通仕様・出力形式**: `approval-gate` skill の「ワークフロー完了後の次ステップ選択」を参照 | 項目 | 値 | |------|-----| | ワークフロー名 | 基本設計 | | 次ワークフロー | `/detailed-design-workflow` | | 追加成果物 | 詳細設計フォルダ | --- ## エラーハンドリング & リカバリ ### サーキットブレーカー発動時 | 状況 | 対処法 | |------|--------| | 3回修正しても9点未満 | 現状ファイルに `<!-- ⚠️ REVIEW_FAILED: 手動修正が必要 -->` マークを付与。問題点サマリーを出力 | | スコア悪化を検知 | 即座に中断。前回の修正内容をロールバック検討 | | ヒアリングで未確定項目あり | 未解決課題（I-XXX）として記録し、基本設計書に「要選定」と明記して続行 | ### 手動リカバリ手順 ``` 1. 問題点サマリーを確認 2. 指摘された箇所を手動で修正 3. 以下のコマンドで再開: /basic-design-workflow "要件定義書パス" --resume-from=phase2 ``` --- ## 完了チェックリスト ``` 【基本設計書完了チェック】 □ スコア9点以上で合格 □ 技術スタック確認ヒアリング実施済み □ 技術スタックが全レイヤーで定義（または「要選定」明記） □ 各技術の選定理由が記載されている □ 機能一覧に全機能IDが付与 □ 画面一覧に全画面IDが付与 □ 詳細設計フォルダが作成済み □ 基本設計書に詳細設計へのリンクが設定済み 【追加仕様時の追加チェック】★Phase 0.5-B実施時 □ 既存設計書との整合性チェック完了 □ アーキテクチャ影響分析が記載されている □ 技術スタック差異が明記されている（ある場合） □ データモデル変更・マイグレーション計画がある（ある場合） □ 既存設計書への変更履歴追記（統合の場合） ``` --- ## Sisyphusへの指示 ### 使用ツール - `basic-design-writer` エージェント: 基本設計書作成 - `basic-design-reviewer` エージェント: レビュー（スコアリング） - `web_search`: 技術スタックベストプラクティス調査 ### 処理フロー 1. **Phase 0: 技術スタック完全性チェック** - 要件定義書から技術スタック定義を検証 - 不足レイヤー（frontend/backend/database/auth）を特定 2. **Phase 0.5-A: 技術スタック確認ヒアリング**（必須） - 定義済み技術の確認サマリーを提示 - 未定義レイヤーの推奨を提案 - ユーザー選択（確認OK/変更あり/全て確定済み）を待機 - 未確定項目は `I-XXX` として記録 3. **Phase 0.5-B: 既存設計書との整合性確認**（追加仕様時のみ） - `docs/designs/basic/BASIC-*.md` を確認 - コンフリクト検出時はユーザーに対応方針を確認（統合/新規/中断） 4. **Phase 1: ドラフト作成** - 確定した技術スタックを反映して基本設計書を作成 - ⚠️ メインセッションでドラフトをreadしない（レビュアーにパスのみ渡す） 5. **Phase 2: 品質保証ループ**（最大3回） - `basic-design-reviewer` でレビュー実行 - スコア9点以上で Phase 2.5 へ - スコア低下時は即時失敗 - 最大リトライ到達時も失敗 6. **Phase 2.5: ユーザー承認ゲート** - 承認/修正/中断 を選択 - 修正選択時はループ継続 7. **Phase 3: 詳細設計準備**（承認後） - 詳細設計用フォルダを準備 - 成功を返却 --- ## 関連ドキュメント - 前工程: `/req-workflow` - **推奨前工程**: `/tech-catchup-workflow`（技術キャッチアップ） - 次工程: `/detailed-design-workflow` --- ## 参考スキル | スキル | 用途 | |--------|------| | `approval-gate` skill | ユーザー承認ゲート | | `workflow-phase-convention` skill | Phase命名規約 | | `design-document-types` skill | 技術スタック定義 | | `tech-stack-selection` skill | 技術スタック確認ヒアリング |