ドキュメント定義マトリクス
| ドキュメント | 何を定義するか | 誰が使うか | 変更コスト | 最重要度 |
|---|---|---|---|---|
| システム方式設計書 | 技術スタック・アーキテクチャパターン（モノリス/マイクロサービス等）・サービス分割方針・通信方式 | 全チーム（設計の前提） | 高 | ◎ 最重要 |
| 認証・認可設計 | 認証方式（OAuth2/SAML/独自）・セッション管理・権限モデル・トークン設計 | FE・BE・インフラ・セキュリティ（全員の前提） | 高 | ◎ 最重要 |
| 論理データモデル（ER図） | エンティティと関係・属性の型・正規化方針・DB選定根拠（RDB/NoSQL） | DBA・BE・共通チーム | 高 | ◎ 最重要 |
| APIゲートウェイ設計方針 | APIのルーティングルール・共通ヘッダー・レート制限・認証フロー統合 | FE・BE全員（全APIの前提） | 高 | ◎ 最重要 |
| 技術選定ドキュメント（ADR） | なぜその技術を選んだか・検討した代替案・トレードオフ | 全チーム・将来の参照者 | 中 | ○ 重要 |
| インフラ構成図（論理） | サーバ・NW・クラウドサービスの構成の骨格・冗長化方針 | インフラ・DBA・QA | 高 | ○ 重要 |
| API一覧・API設計方針 | APIの全体像・命名規則・バージョニング方針・エラーコード体系 | FE・BE | 中 | ○ 重要 |
| スコープ確定書 | このフェーズ以降の変更管理の基準となるスコープの凍結 | PM・PMO・全チーム | 中 | ○ 重要 |
| WBS（詳細化） | タスク分解・担当・期間・依存関係 | PMO・PM | 低 | △ 記録 |
| リスク管理表 | リスクの一覧・発生確率・影響度・対応策 | PM・PMO | 低 | △ 記録 |
◎最重要ドキュメントの詳細
システム方式設計書
何を定義するか：技術スタック（言語・フレームワーク・ミドルウェア）・アーキテクチャパターン（モノリス/マイクロサービス/サーバレス）・サービス間通信方式（同期REST/非同期MQ）・デプロイ単位。
形骸化した場合の影響：各チームが独自に方式を決めてしまい、後から「インフラとアプリで前提が違った」が発覚。基本設計からやり直しになる。
認証・認可設計
何を定義するか：認証方式（OAuth2・SAML・LDAP・独自JWT等）・セッション管理の方式（ステートフル/ステートレス）・権限モデル（RBAC/ABAC）・トークンの有効期限・リフレッシュフロー。
⚠️ 認証設計は「後から変えられない」代表例
認証方式が確定すると、FEのリクエスト設計・BEの認証ミドルウェア・インフラのゲートウェイ設定・セキュリティポリシーのすべてがこれを前提に作られる。基本設計後に「OAuth2からSAMLに変える」という変更は、ほぼすべての設計成果物の作り直しを意味する。
論理データモデル（ER図）
何を定義するか：エンティティの一覧・エンティティ間の関係（1:1/1:N/M:N）・主要属性と型の方針・正規化レベル・DB選定根拠（なぜRDBかNoSQLか）。
形骸化した場合の影響：DBAとBEが独自にDB設計を進め、基本設計完了後に「テーブル構造の前提が違った」が発覚。物理設計のやり直しと、すでに書いたクエリの全面修正が必要になる。
APIゲートウェイ設計方針
何を定義するか：どのAPIをゲートウェイ経由にするか・認証チェックをどこで行うか・レート制限の方針・共通レスポンスヘッダー・エラーレスポンスの統一フォーマット。
形骸化した場合の影響：FEとBEが「ゲートウェイが何をしてくれるか」を別々に解釈し、認証チェックの二重実装や漏れが発生する。セキュリティホールにもなりうる。
技術選定ドキュメント（ADR）の書き方
ADR（Architecture Decision Record）は「なぜその技術を選んだか」を記録する。以下の項目を含める。
| 項目 | 内容 |
|---|---|
| ステータス | 提案中・採用・廃止・代替済み |
| 背景と課題 | この決定が必要になった理由 |
| 検討した選択肢 | 候補として考えた技術・方式の一覧 |
| 決定内容 | 選んだ選択肢と理由 |
| トレードオフ | この選択で犠牲にしたこと・受け入れたリスク |
💡 ADRは「未来の自分への手紙」
1年後に新メンバーが参加したとき、「なぜこのフレームワークを使っているのか」を説明できるのがADRだ。技術選定の根拠が消えると、後任者が「この設計は本当に正しいのか」と疑心暗鬼になり、不必要な再検討が生まれる。
✅ 次のPARTへ