はじめに
「それは詳細設計でいいよね？」
「そこまで書く必要ある？」
「逆に情報足りなくない？」
基本設計書を書いていると、必ず一度はぶつかる問題です。
この記事では、実務で迷いがちな
- 基本設計のスコープ
- 詳細設計との線引き
- “ちょうどいい粒度”の考え方
を整理します。
そもそも基本設計とは？
ウォーターフォール型開発（例：ウォーターフォールモデル）における基本設計は、
「システムとしてどうあるべきか」を定義する工程
です。
基本設計の目的
- 要件をシステム仕様に落とす
- 実装方針を決める
- ステークホルダーと合意する
- 詳細設計・実装のインプットを作る
ここで重要なのは、
「誰のためのドキュメントか」
という視点です。
結論：基本設計書は「実装者が迷わないレベル」まで書く
私の結論はこれです。
基本設計書は「何をどう作るか」が明確で、
実装者が設計方針で迷わないレベルまで書く。
ただし、以下は原則として基本設計には書きません。
- アルゴリズム詳細
- SQL全文
- クラス内メソッド設計
基本設計に書くべきこと
① 画面設計
- 画面レイアウト
- 入力項目
- バリデーション方針
- 画面遷移図
- 権限制御
※ワイヤーフレームだけでは不足することが多いです。
「どう制御するか」まで定義できているかがポイントです。
② API／外部インターフェース設計
- エンドポイント
- リクエスト／レスポンス項目
- エラー仕様
- 認証方式
REST設計の場合は、
冪等性やHTTPステータスの扱い方など、設計思想も明文化しておくと実装がブレません。
③ データ設計（論理設計レベル）
- テーブル一覧
- ER図
- 主キー／外部キー
- 正規化方針
※インデックス詳細やパフォーマンスチューニング値は通常、詳細設計以降で扱います。
④ 非機能要件の具体化
- 性能目標（例：レスポンス2秒以内）
- 同時接続数
- 可用性
- ログ出力方針
- バックアップ方式
- セキュリティ方針
ここが弱いと、高確率で後工程が炎上します。
書きすぎるパターン
よくある失敗例です。
SQL全文を書く
→ 変更に弱くなり、設計書がすぐ陳腐化する
クラス図を詳細レベルまで作る
→ 詳細設計との重複が発生する
例外パターンを網羅しすぎる
→ 読まれない設計書になる
書かなすぎるパターン
逆に危険なのはこちら。
「入力チェックを行う」とだけ書く
→ 何を？どの粒度で？
「適切にログ出力する」
→ 運用で困る
エラー設計未定義
→ 実装者ごとに挙動がバラバラになる
判断基準：3つの問い
迷ったら、次の問いで判断します。
① 実装者が設計判断を迫られるか？
YESなら基本設計に書く。
② 仕様変更時に影響範囲が大きいか？
YESなら基本設計に書く。
③ ステークホルダーと合意すべき内容か？
YESなら基本設計に書く。
詳細設計との線引き
| 観点 | 基本設計 | 詳細設計 |
|---|---|---|
| 目的 | 方針決定 | 実装定義 |
| 粒度 | 構造レベル | コードレベル |
| 読者 | 顧客・PM・開発者 | 開発者 |
一言で言うと、
「変えにくいもの」は基本設計
「変えても局所的なもの」は詳細設計
です。
上流工程の本質
基本設計の価値は、ドキュメントの厚さではありません。
価値は、
- 手戻りを減らすこと
- 認識齟齬をなくすこと
- リスクを先に潰すこと
にあります。
ここが曖昧だと、後工程で必ずコストとして返ってきます。
まとめ
基本設計書は
- すべてを書く場所ではない
- 何も書かない場所でもない
- 「設計方針を確定させる場所」
迷ったらこの問いを思い出してください。
実装者は迷うか？
これが線引きの本質です。