---
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. **現状サマリー提示**: 定義済み/未定義のレイヤーを一覧表示

   ```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 | 技術スタック確認ヒアリング |