基本設計を初めて任されたとき、テンプレートを開いても「どこまで書けばいいのか」で手が止まりませんか。
結論から言うと、基本設計は設計書の項目を埋める作業ではありません。要件定義で合意した内容を、利用者や外部システムから見える具体的な判断へ変え、後工程へ渡せる状態にする仕事です。
画面・API・データ・権限・エラーの名前や条件がつながっていれば、詳細設計や実装で「これはどうする？」という追加判断を減らせます。逆に、文書がきれいでも判断が残っていれば設計はまだ途中です。
なお、基本設計の成果物や詳細設計との境界はプロジェクトごとに異なります。固定の目次を正解にせず、まず現場の開発標準とレビュー対象を確認してください。
基本設計は「判断を残す」工程
IPAのDX SQUAREでは、要件定義でまとめた要件を、その後の基本設計で具体化し、業務フロー、必要な機能やソフトウェア構成、外部インターフェースなどを整理すると説明しています。
実務では、この「具体化」を3段階で考えると書きやすくなります。
| 段階 | 考えること | 例 |
|---|---|---|
| 要件 | 何を満たす必要があるか | 管理者が会員情報を更新できる |
| 基本設計 | 利用者・外部からどう見えるか | 編集できる項目、操作、権限、入力チェック、成功・失敗時の表示 |
| 詳細設計・実装 | 内部でどう実現するか | クラス構成、処理フロー、内部モジュール、実装方式 |
大切なのは、基本設計の読み手が後工程で製品仕様を勝手に補わなくてよいことです。「どの技術で作るか」より先に、「外から見た約束は何か」をそろえます。
書き始める前に5つの入力をそろえる
基本設計で苦しくなる原因の一つは、要件が足りないまま設計書を書き始めることです。未決事項を設計者が推測で埋めると、後で要件との食い違いになります。
- 目的と要件：何の課題を解決し、何ができれば完了か
- 利用者と権限：誰が使い、役割ごとに何が許可されるか
- 既存仕様とデータ：現在の画面・API・データ・運用に何があるか
- 外部連携：他システムとの入出力、責任分界、失敗時の扱いは何か
- 制約：性能・セキュリティ・監査・運用など、設計へ影響する条件は何か
この時点で分からないものは、無理に埋めません。「未決」「確認先」「判断期限」を残し、誰が決める項目なのかを明確にします。設計の仕事は、すべてを一人で決めることではなく、決めるべきことを見つけることでもあります。
6つの順番で基本設計を組み立てる
成果物名から考えると、「画面設計書」「API仕様書」「テーブル定義書」のように文書が分断されがちです。先に利用者の操作とデータの流れを追い、その判断を各成果物へ反映すると整合性を保ちやすくなります。
1. 機能の範囲と利用シーンを決める
誰が、どの入口から、何を完了させる機能なのかを一文で置きます。対象外も分かるなら書いておきます。
2. 画面と入出力を決める
表示項目、入力項目、必須条件、操作、遷移、初期表示、0件時の状態など、利用者から確認できる振る舞いを整理します。
3. API・外部I/Fをそろえる
画面や外部システムが必要とする入力・出力・エラーを定義します。画面で使う名称とAPIの項目が別の意味になっていないかも確認します。
4. データの意味を決める
保持する情報、項目の意味、識別子、状態の種類、更新条件を整理します。物理DBの細部まで基本設計で扱うかは現場標準に従います。
5. 権限・入力チェック・例外を決める
正常系だけでなく、「権限がない」「入力が不正」「対象が存在しない」「外部連携が失敗した」場合を確認します。ここが未定だと、実装者ごとに挙動が分かれやすくなります。
6. 必要ならバッチ・通知・運用をつなぐ
非同期処理、メール通知、ファイル連携、監査ログなどが機能に関係する場合は、利用者の操作から運用まで途切れないようにします。
すべての案件でこの6種類の文書が必要という意味ではありません。重要なのは、要件を満たすための判断がどこにも抜け落ちないことです。
例：会員情報編集を仕様へ落とす
例として「管理者が会員情報を更新できる」という要件を考えます。これは説明用の例なので、実際の案件では要件・権限・運用ルールを確認してください。
| 観点 | 曖昧な書き方 | 確認して設計へ落とすこと |
|---|---|---|
| 画面 | 会員情報を編集できる | 編集対象項目、初期値、保存・キャンセル時の遷移 |
| 権限 | 権限に応じて制御する | どの役割が閲覧・編集できるか、権限なし時の扱い |
| 入力 | 不正な値はエラー | 必須・形式・桁数など、利用者へ示す条件 |
| API | 更新APIを呼ぶ | 入力項目、成功時の結果、対象なし・競合・権限エラーの扱い |
| データ | 会員データを更新 | どの項目が更新対象か、状態値の意味、更新日時などの扱い |
基本設計で見るのは「文章が長いか」ではなく、利用者・API・データの間で同じ判断になっているかです。
粒度は「後工程が勝手に決めるか」で判断
基本設計で一番迷いやすいのが粒度です。書きすぎれば実装と二重管理になり、書かなければ担当者ごとに製品仕様が変わります。
迷ったら、「ここを書かなかった場合、詳細設計や実装の担当者が利用者向けの振る舞いを自分で決めることになるか」と考えます。
- 画面に表示する条件を実装者が決める → 基本設計で合意したい
- 権限なし時の振る舞いを実装者が決める → 基本設計で合意したい
- エラー時の利用者向けメッセージ方針を実装者が決める → 基本設計で合意したい
- 外部仕様を変えない内部クラスの分割を実装者が決める → 詳細設計・実装側で扱える場合が多い
「詳細設計へ渡したあと、仕様の意思決定を追加しなくても実装へ進めるか」は、粒度を見る実務的な目安です。ただし、どこまでを基本設計に含めるかは現場の標準を優先します。
レビューは画面・API・データを横断する
設計レビューでは、文書を一枚ずつ読むだけでは見つけにくい不整合があります。画面仕様だけ正しくても、APIやデータ定義と食い違えば実装時に判断が発生します。
- 要件：この仕様がどの要件を満たすか追えるか
- 用語：画面・API・データで同じ項目を同じ意味で呼んでいるか
- 権限：画面表示とAPI側の許可条件が一致しているか
- 状態：正常・0件・対象なし・入力エラー・連携失敗を確認したか
- 値：必須、上限、形式、日付・時刻などの条件が矛盾していないか
- 外部I/F：送受信する項目と失敗時の扱いがそろっているか
- 未決事項：誰がいつ判断するか残っているか
レビューで「画面はこうなっています。ではAPI側は？ データ側は？」と横へたどるだけでも、単体の誤字チェックでは見えない抜けを見つけやすくなります。
よくある4つのNGと直し方
1. テンプレートを埋めることが目的になる
項目は埋まっていても、「別途検討」「適切に制御」「必要に応じて」といった表現ばかりなら判断は残ったままです。判断できない理由があるなら、未決事項として確認先を明記します。
2. 内部実装へ早く入りすぎる
クラス名やフレームワークの実装方式を細かく決めても、利用者向けのエラーや権限が未定なら順番が逆です。まず外部仕様の判断を閉じます。
3. 正常系しか書かない
データがない、権限がない、入力が不正、外部システムが応答しない。実務ではこの境界で仕様差が出ます。正常系を書いたら、同じ操作の失敗側を一度たどります。
4. 成果物同士で用語がずれる
画面では「会員ID」、APIでは「userId」、データでは別の識別子を指している。こうしたズレは後工程で確認コストになります。名称が違う必要があるなら対応関係を明示します。
フリーランスは設計経験を責任範囲で説明する
案件面談やスキルシートでは、「基本設計を担当」とだけ書いても、どこまで自分で判断したのか伝わりにくいことがあります。
伝わりにくい例
基本設計書を作成。画面・APIの設計を担当。
責任範囲が見える例
変更要件から影響する画面・API・データを整理し、入力条件・権限・エラー時の振る舞いを基本設計へ反映。開発チームのレビュー指摘を調整し、実装へ引き渡した。
これは説明方法の例です。実際に担当していない要件整理や合意形成を足してはいけません。自分が「何を受け取り、何を決め、誰とレビューし、どこまで渡したか」で振り返ると、設計経験の深さを説明しやすくなります。
設計書を埋めるより判断をつなぐ
- 要件と利用者・権限・既存仕様を確認してから書き始める
- 画面・API・データ・例外を別々に作らず、同じ判断としてつなぐ
- 粒度は「後工程が製品仕様を勝手に決めるか」で確認する
- レビューでは成果物を横断して、要件・用語・権限・状態の整合性を見る
まずは担当中の機能を一つ選び、「要件 → 画面 → API → データ → 権限・例外」の順に1本の線で追ってみてください。途中で説明できない場所があれば、そこが次に確認すべき設計ポイントです。
