ドキュメント定義マトリクス
図1: 詳細設計フェーズの成果物・担当・更新タイミング
| ドキュメント | 何を定義するか | 誰が使うか | 変更コスト | 最重要度 |
|---|---|---|---|---|
| 詳細API仕様書（OpenAPI 3.x） | エンドポイントURL・HTTPメソッド・リクエスト/レスポンスのスキーマ・エラーコード・認証要件 | FE（実装インプット）・BE（実装インプット）・QA（テスト設計） | 高 | ◎ 最重要 |
| 物理データモデル・DDL | テーブル定義・カラム・型・制約（NOT NULL/FK/UK）・デフォルト値 | BE（クエリ実装）・DBA（構築・チューニング） | 高 | ◎ 最重要 |
| インデックス設計書 | インデックス一覧・対象カラム・種別（単一/複合/部分）・設計根拠（対応クエリパターン） | DBA・BE | 高 | ◎ 最重要 |
| 共通コンポーネント仕様書 | 共通ライブラリのインターフェース・利用方法・制約・バージョン | FE・BE全員（依存する共通基盤） | 高 | ◎ 最重要 |
| 監視設計書（アラート定義） | 監視対象・アラート閾値・通知先・対応フロー | インフラ・運用チーム | 中 | ○ 重要 |
| 詳細画面設計書 | 画面レイアウト・状態遷移・入力バリデーション・エラー表示 | FE | 中 | ○ 重要 |
| コンポーネント仕様書（Storybook等） | UIコンポーネントの見た目・Props・状態パターン | FE | 中 | ○ 重要 |
| バックアップ・リストア方針 | バックアップ頻度・保持期間・リストア手順 | DBA・インフラ | 中 | ○ 重要 |
| コーディング規約・レビュー基準 | 命名規則・フォーマット・レビューの合否判断基準 | 全開発者 | 低 | ○ 重要 |
◎最重要ドキュメントの詳細
詳細API仕様書（OpenAPI 3.x）
何を定義するか：FEとBEの「契約書」として機能する。エンドポイントのURL・HTTPメソッド・リクエストボディ/クエリパラメータのスキーマ・レスポンスの構造・各フィールドの型と制約・認証方式（Bearer/Cookie等）・全エラーコードの定義。
⚠️ API仕様書の版がFEとBEで乖離すると開発が止まる
API仕様書は単一のソースオブトゥルースを維持しなければならない。FEとBEが別々にコピーを持つと版が乖離し、実装後に「レスポンスの構造が違う」が発生する。OpenAPIのYAML/JSONファイルをGit管理し、両者が同じファイルを参照する運用を徹底する。
物理データモデル・DDL
何を定義するか：論理ER図を物理レベルに落とし込む。テーブル名・カラム名・データ型・NOT NULL制約・外部キー制約・ユニーク制約・デフォルト値・コメント。DDLはそのままDBに流せる状態にする。
形骸化した場合の影響：BEがDDLを見ずにクエリを書き、実際のカラム名・型と乖離が生じる。テスト環境で動いていたコードが本番の本当のDDLで動かない。
インデックス設計書
何を定義するか：インデックスの一覧（テーブル名・カラム・種別）と、そのインデックスがどのクエリパターンのために設計されたかの根拠。根拠がないインデックス設計は後のチューニングで「このインデックスは本当に必要か」を判断できなくなる。
形骸化した場合の影響：BEがDDLを先に実装し、DBAが後からインデックスを追加しようとした際にアプリ側のクエリを全面修正する必要が生じる。インデックスはクエリパターンと同時に設計しなければならない。
OpenAPI仕様書に含めるべき項目
| 項目 | 必ず定義すること |
|---|---|
| エンドポイント | URL・HTTPメソッド・パスパラメータ・クエリパラメータ（型・必須/任意・説明） |
| リクエストボディ | スキーマ（全フィールドの型・必須/任意・バリデーション条件・例） |
| レスポンス | HTTPステータス別のレスポンススキーマ（200/400/401/403/404/500） |
| エラーコード | エラーコード一覧・意味・クライアント側での対処方針 |
| 認証 | 認証方式（Bearer/Cookie）・トークンの渡し方・認証失敗時の挙動 |
| 共通規約 | ページネーション方式・ソート・フィルタの共通パラメータ名 |
詳細設計フェーズでよくある失敗パターン
詳細設計のドキュメント管理で繰り返し発生する失敗と、その予防策を整理する。
| 失敗パターン | 結果 | 予防策 |
|---|---|---|
| OpenAPI仕様書をFEとBEが別々に管理する | 実装中に版が乖離し「仕様書と実装が違う」が多発。最終的に口頭調整で収束させる | GitでYAML/JSONを単一管理。PRマージの前にFE・BE両者がレビューする |
| DDLをExcelや設計書から手動でDBに反映する | 手動ミスによるカラム名・型の不一致。本番と開発のDDLが気づかず乖離する | DDLをIaC（Terraform/Flyway）として管理し、適用は自動化する |
| インデックス設計をDBAが実装直前に独自判断する | BEが想定していないクエリパターンでインデックスが設計され、実際の重要クエリがカバーされない | インデックス設計書にはBEが担当するクエリパターンを記載。DBAと共同レビューする |
| 非機能要件（レスポンスタイム・同時接続数）を詳細設計で未定義のまま進む | 実装完了後にパフォーマンスが要件を満たさず、インデックス追加・クエリ全面書き直しが発生 | 詳細API仕様書に非機能要件（SLA・想定TPS）を明記し、インデックス設計の前提とする |
✅ 次のPARTへ