「この項目は基本設計に書く？ それとも詳細設計？」。設計工程に入り始めると、同じような迷いが何度も出てきます。
結論から言うと、違いは文書名ではなく、誰と何を合意するかと、実装できる粒度までどこまで具体化するかです。ここを押さえると、画面・API・DBのどこを設計していても判断しやすくなります。
基本設計と詳細設計の違いを先に整理する
一般的なシステム開発では、基本設計は要件を外部仕様へ落とし込み、詳細設計はその仕様を実装可能な内部構造へ落とし込む工程として扱われます。
| 比較軸 | 基本設計 | 詳細設計 |
|---|---|---|
| 主な目的 | 何を実現するかを具体化する | どう実装するかを具体化する |
| 主な視点 | 利用者・業務・外部から見える仕様 | 開発者・プログラム内部の仕様 |
| 主な確認相手 | 顧客、業務担当、PM、開発チーム | 開発者、テックリード、レビュー担当 |
| 代表的な成果物 | 画面、画面遷移、機能、帳票、外部I/Fなど | クラス、処理フロー、物理DB、例外、トランザクションなど |
| 判断基準 | 利用者や外部システムから見た振る舞いが合意できるか | 実装者が処理を迷わず組み立てられるか |
よく「基本設計＝WHAT、詳細設計＝HOW」と説明されます。入口としては分かりやすい整理です。ただし、実務ではその境界が会社や案件によって変わる点に注意が必要です。
最初に注意したいのは「工程名は会社ごとに違う」こと
「基本設計」「詳細設計」という名前だけで担当範囲を決めると、現場でズレることがあります。
IPAの共通フレーム2013は、ソフトウェアやシステムに関わる人が同じ言葉で認識を合わせるための共通枠組みです。IPAの過去資料でも、同じ工程名でも実施内容が異なる、同じ実施内容でも工程名称が異なるケースが示されています。
つまり、「詳細設計だからクラス図を書くはず」と決め打ちするより、プロジェクト開始時に成果物一覧と責任範囲を確認するほうが安全です。
- この工程で確定させる仕様は何か
- 誰がレビュー・承認するか
- 次工程へ何を引き渡すか
- 変更時にどの設計書へ戻るか
この4点が分かれば、工程名が多少違っても設計の役割を見失いにくくなります。
基本設計は「外から見える仕様」を決める
基本設計では、要件定義で決めた要求を「システムとしてどう振る舞うか」へ変換します。
たとえばWebシステムなら、画面に何を表示するか、どの操作でどこへ遷移するか、APIへ何を渡して何が返るか、外部サービスとどう連携するか、といった内容です。
基本設計で扱うことが多い成果物
- 機能一覧・機能構成
- 画面一覧・画面レイアウト・画面遷移
- 入力項目・出力項目・入力チェック方針
- 帳票仕様
- 外部インターフェース仕様
- 論理データモデルや主要なデータ関係
- 権限や認証の外部仕様
ポイントは、実装方式より先に利用者や外部システムから観測できる仕様を固めることです。ここで認識がずれたまま詳細設計へ進むと、後から内部構造を直すだけでは済まなくなります。
詳細設計は「実装の迷い」を減らす
詳細設計では、基本設計で決めた振る舞いを、プログラム内部でどう実現するかまで具体化します。
ここで重要なのは、細かく書くこと自体ではありません。実装者が「この場合はどうする？」と毎回仕様を決め直さなくてもよい状態を作ることです。
詳細設計で扱うことが多い成果物
- クラス・モジュール構成
- メソッドや処理単位の責務
- シーケンス・処理フロー
- 物理テーブル・カラム・インデックス
- トランザクション境界
- 例外処理・エラーコードの内部マッピング
- バッチ処理やジョブの詳細
- 必要に応じて単体テスト観点との対応
案件によってはAPI仕様やDB定義を基本設計側に置くこともあります。だからこそ「成果物名」より「外部仕様を決めているのか、内部実装を決めているのか」で考えると整理しやすくなります。
ユーザー登録APIで違いを見る
抽象論だけだと分かりにくいので、ユーザー登録APIを例に比べてみます。
基本設計で決める内容
POST /usersで登録する- 入力は氏名・メールアドレス・パスワード
- メールアドレスは必須で重複不可
- 成功時は作成したユーザーIDを返す
- 入力エラー時は400、重複時は409を返す
- 誰がこのAPIを実行できるかを決める
ここでは、呼び出し側から見て「何を渡せば、どう振る舞うか」を合意します。
詳細設計で決める内容
UserController
↓ request validation
UserService
↓ duplicate check / transaction
UserRepository
↓
users table- Controller・Service・Repositoryの責務
- メール重複をどの層で確認するか
- DBの一意制約とアプリ側チェックをどう組み合わせるか
- どこをトランザクション境界にするか
- 例外をHTTP 409へどう変換するか
- パスワードをどのタイミングでハッシュ化するか
同じ「ユーザー登録」でも、基本設計は外部の約束、詳細設計は内部の実現方法を中心に扱います。
境界で迷ったら「変更時に誰へ確認するか」で考える
実務では、基本設計と詳細設計の境界がきれいに分かれないことがあります。そんなときは、仕様を変更した場合の影響先で考えると判断しやすくなります。
- 利用者の操作や表示が変わる → 基本設計側へ戻る可能性が高い
- APIの入出力や外部I/Fが変わる → 基本設計側の合意を確認する
- 内部クラスの分割だけ変わる → 詳細設計・実装側で閉じる可能性が高い
- SQLやインデックス変更で外部仕様が変わらない → 詳細設計側で扱うことが多い
「外部との約束が変わるか？」を最初の質問にすると、文書の置き場所より重要な判断ができます。
が設計で意識したいポイント
実装経験が増えて設計を任され始める時期は、「設計書を埋めること」が目的になりがちです。ですが、評価されやすいのはテンプレートを埋めた量ではなく、後工程の判断を減らせる設計です。
基本設計では「利用者の期待」を確認する
画面やAPIを設計するとき、正常系だけでなく、入力ミス、権限不足、データなし、外部サービス失敗時に利用者からどう見えるかまで確認します。
詳細設計では「分岐と失敗」を先に洗う
処理フローを書くなら、成功パスだけでは不十分です。例外、再実行、ロールバック、重複実行、null、境界値など、実装時に迷いやすい分岐を設計段階で見つけます。
設計根拠を一言で説明できるようにする
「前の案件もこうだったから」ではなく、「外部I/Fを変えずに影響範囲を限定したいから」「一意性をDBでも保証したいから」のように、判断理由を説明できる状態を目指します。
よくある設計のズレと直し方
基本設計に内部実装を書き込みすぎる
クラス名やメソッド名まで基本設計に固定すると、外部仕様を変えずにリファクタリングしたいときまで設計変更が必要になります。外から見える約束と内部実装は、必要に応じて分離します。
詳細設計で基本設計を勝手に変える
実装しにくいからといって、レスポンス項目や業務ルールを詳細設計だけで変更すると、合意済みの外部仕様とずれます。実現性に問題があれば基本設計へ戻して確認します。
設計書同士の対応が追えない
画面ID、機能ID、API IDなどを揃え、どの基本設計がどの詳細設計・実装へつながるか追えるようにします。変更時の影響調査がかなり楽になります。
レビュー前に確認したいチェックポイント
- 要件定義と矛盾していないか
- 基本設計の外部仕様を詳細設計が満たしているか
- 正常系だけでなく異常系・境界値が考慮されているか
- 用語、ID、データ名が設計書間で揃っているか
- 未決事項が設計済みのように書かれていないか
- 実装者が追加判断しなければならない箇所が残っていないか
全部を詳細に書けば品質が上がるわけではありません。必要な判断が必要な工程で終わっているか、という視点でレビューすると設計書が実務で使いやすくなります。
違いを覚えるより「設計の受け渡し」を理解する
基本設計と詳細設計の違いは、単純に「粗い設計」と「細かい設計」ではありません。
基本設計では外部から見える振る舞いを合意し、詳細設計ではその約束を内部でどう実現するかを決める。さらに、工程名や成果物の分け方はプロジェクトごとに異なるため、最初に責任範囲を確認する。この3点を押さえておけば、現場で判断しやすくなります。
次に設計書を開いたら、「これは誰との約束か」「次工程の誰が使うか」「ここで決めないと実装者が迷うことは何か」の3つを書き出してみてください。設計工程の境界が、文書名ではなく仕事の流れとして見えるようになります。
