basic-design-workflow

name	basic-design-workflow
description	要件定義書から基本設計書を作成し、レビュー合格（9点以上）まで修正を繰り返す完全ワークフロー

基本設計・完全ワークフロー

要件定義書を入力として基本設計書を作成し、スペシャリストによるレビュー（合格基準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. 現状サマリー提示: 定義済み/未定義のレイヤーを一覧表示

   ## 技術スタック確認
   
   ### 定義済み（要件定義書より）
   | レイヤー | 技術 | 確認 |
   |---------|------|------|
   | フロントエンド | Next.js | ✅ このまま進めてよいですか？ |
   | バックエンド | Node.js | ✅ このまま進めてよいですか？ |
   
   ### 未定義（提案します）
   | レイヤー | 推奨 | 理由 |
   |---------|------|------|
   | UIライブラリ | shadcn/ui | カスタマイズ性、軽量 |
   | ORM | Prisma | 型安全、マイグレーション管理 |
   | 認証 | NextAuth.js | Next.js統合 |
   

4. ユーザー選択:

   **対応を選択してください**:
   
   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. アーキテクチャ影響分析:

   ## 既存設計書との整合性チェック結果
   
   ### 関連する既存基本設計書
   | ドキュメント | 関連度 | 影響 |
   |-------------|--------|------|
   | BASIC-XXX-001_既存機能.md | 高 | コンポーネント追加 |
   
   ### アーキテクチャ影響分析
   | 既存コンポーネント | 影響 | 対応方針 |
   |------------------|------|---------|
   | Backend | 変更あり | 新規モジュール追加 |
   | Frontend | 変更あり | 新規画面追加 |
   | 共通モジュール | 変更なし | - |
   
   ### 技術スタック差異
   | レイヤー | 既存 | 追加仕様 | 判定 |
   |---------|------|---------|------|
   | バックエンド | Rust 1.70 | Rust 1.75 | ⚠️ バージョンアップ必要 |
   | 新規依存 | - | serde_yaml | ✅ 追加可能 |
   
   ### データモデル変更
   - 新規テーブル: `statistics` (追加)
   - 既存テーブル変更: なし
   - マイグレーション: 必要
   

4. ユーザー確認（影響がある場合）:

   ⚠️ 既存設計への影響が検出されました。
   
   **影響サマリー**:
   - アーキテクチャ変更: あり（バックエンドにモジュール追加）
   - 技術スタック変更: あり（依存ライブラリアップグレード）
   - 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	技術スタック確認ヒアリング