ドキュメント定義マトリクス

基本設計フェーズのドキュメント定義マトリクス

図1: 基本設計フェーズの成果物・担当・更新タイミング

ドキュメント何を定義するか誰が使うか変更コスト最重要度
システム方式設計書技術スタック・アーキテクチャパターン（モノリス/マイクロサービス等）・サービス分割方針・通信方式全チーム（設計の前提）高◎ 最重要
認証・認可設計認証方式（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が「ゲートウェイが何をしてくれるか」を別々に解釈し、認証チェックの二重実装や漏れが発生する。セキュリティホールにもなりうる。

基本設計フェーズでよくある失敗パターン

基本設計は後の詳細設計・実装の前提を確定させる工程であり、ここでの見落としは詳細設計後半や実装中盤で大きなやり直しを生む。

失敗パターン後工程への影響予防策
認証方式を「後で決める」と先送りにする FEのHTTPリクエスト設計・BEの認証ミドルウェア・インフラのゲートウェイ設定がすべて認証方式を前提とするため、後から変えると全成果物の作り直しになる 基本設計フェーズのend条件に「認証方式の確定と全チームへの周知」を含める
ER図を論理レベルで止めてDBAに渡す DBAがER図を元に物理設計を始めるとカラム型・制約・正規化レベルの解釈がずれ、詳細設計後半で両者の認識差が露呈する 主要エンティティについてはDBの型・制約レベルまで合意した上でDBAに渡す
APIゲートウェイの責務範囲を曖昧にする FEとBEが「ゲートウェイが認証を担う」「アプリ側で認証する」と別々に解釈し、二重実装や認証漏れが発生する ゲートウェイの責務（認証・レート制限・ルーティング・ロギング）を設計書に明記する
技術選定の理由を記録しない 1年後に「なぜこのフレームワークを選んだか」が分からなくなり、新メンバーが根拠なく代替案を提案し無用な議論が生まれる ADR（Architecture Decision Record）として背景・選択肢・トレードオフを残す

技術選定ドキュメント（ADR）の書き方

ADR（Architecture Decision Record）は「なぜその技術を選んだか」を記録する。以下の項目を含める。

項目内容
ステータス提案中・採用・廃止・代替済み
背景と課題この決定が必要になった理由
検討した選択肢候補として考えた技術・方式の一覧
決定内容選んだ選択肢と理由
トレードオフこの選択で犠牲にしたこと・受け入れたリスク

💡 ADRは「未来の自分への手紙」

1年後に新メンバーが参加したとき、「なぜこのフレームワークを使っているのか」を説明できるのがADRだ。技術選定の根拠が消えると、後任者が「この設計は本当に正しいのか」と疑心暗鬼になり、不必要な再検討が生まれる。

✅ 次のPARTへ

→ PART 05 — 詳細設計フェーズのドキュメント定義へ