基本設計書の書き方｜項目・記入例とレビューの観点

基本設計書とは、システムが「外から見てどう動くか」――画面・帳票・データ・外部システムとの連携・性能やセキュリティなどの要件――を、発注者と開発者が合意できる形でまとめた設計書です。「外部設計書」とも呼ばれます。

要件定義で決めた「何を実現するか」を、利用者やお客様が確認できる具体的な形に落とし込み、詳細設計（内部の作り方）へ引き継ぐのが役割です。この記事では、要件定義・詳細設計との違い、作成する成果物と目次のテンプレート、各項目の記入例、どこまで細かく書くかの目安、そしてよくある失敗とレビューのチェックリストまでを、現場の視点で解説します。

要件定義・基本設計・詳細設計の違い

最も大切な違いは、基本設計書はお客様が読んで承認する文書だという点です。プログラムの内部の話ではなく、「この画面でこの項目を入力すると、こうなる」という、利用者から見える振る舞いを書きます。

基本設計で作成する成果物

プロジェクトの規模や種類によって必要なものは変わりますが、代表的な成果物は次のとおりです。

すべてを作ることが目的ではありません。「お客様と合意しておかないと、後で揉めるもの」「開発者が迷うもの」を優先して作ります。

目次のテンプレート

1. はじめに
   1.1 本書の目的と対象読者
   1.2 対象範囲（スコープ）と対象外
   1.3 用語集
   1.4 関連資料（要件定義書など）
2. システム概要
   2.1 システム構成図
   2.2 システム化後の業務フロー
   2.3 機能一覧（要件IDとの対応）
3. 画面設計
   3.1 画面一覧・画面遷移図
   3.2 各画面の設計（レイアウト・項目定義・アクション定義）
4. 帳票設計
5. バッチ設計
6. データ設計
   6.1 ER図
   6.2 テーブル定義
   6.3 CRUD図
7. 外部インターフェース設計
8. メッセージ・コード定義
9. 非機能要件
   9.1 性能  9.2 可用性  9.3 セキュリティ  9.4 運用・保守  9.5 移行
10. 変更履歴

「対象範囲と対象外」「用語集」「変更履歴」は見落とされがちですが、後のトラブルを防ぐうえで効果の大きい項目です。

各項目の書き方と記入例

ここでは、「会員が商品を注文するECサイト」を例に、記入例を示します。

機能一覧：要件との対応を書く

すべての機能に、要件定義書の要件IDを対応させます。これにより、「要件の漏れ」と「要件にない機能の追加」の両方を防げます（トレーサビリティ）。

画面遷移図

画面遷移図は、図を描くツールのほか、テキストで管理できる形式でも書けます。

flowchart LR
  A[商品一覧] --> B[商品詳細]
  B --> C[カート]
  C --> D{ログイン済み?}
  D -- いいえ --> E[ログイン]
  E --> C
  D -- はい --> F[注文確認]
  F --> G[注文完了]

画面項目定義

画面の各項目について、型・桁・必須・入力チェック・初期値を表で定義します。

「桁数」は、全角・半角のどちらで数えるのか、文字数かバイト数かまで決めておくと、画面とデータベースの間での食い違いを防げます。

画面アクション定義

ボタンを押したとき、何が起きるかを書きます。正常時だけでなく、エラー時の動きまで書くのがポイントです。

「ボタンを2回押したら」「通信が途中で切れたら」といった場面を書いておくと、二重登録などの不具合を設計の段階で防げます。

バッチ処理概要

「異常時の動き」と「再実行できるか」は、運用に入ってから最も問題になる部分です。必ず書きます。

テーブル定義

テーブルの設計は、正規化（同じデータを複数の場所に持たない設計）を基本にします。「注文時点の単価」のように、時点によって変わる値を注文側に持つかどうかも、この段階で決めておきます。

外部インターフェース定義

外部連携では、タイムアウト・再試行・二重実行の防止を決めておかないと、「決済されたのに注文が失敗扱いになる」といった深刻な不具合につながります。

非機能要件

非機能要件は、数値で書くのが原則です。「高速に」「安全に」では、満たしているかを判定できません。IPA（情報処理推進機構）の「非機能要求グレード」は、可用性・性能拡張性・運用保守性・移行性・セキュリティ・システム環境の6つの観点で整理されており、項目の洗い出しに役立ちます。

パスワードの保存は、特に注意が必要な項目です。SHA-256のような汎用のハッシュ関数は、計算が高速なぶん、漏えいしたハッシュ値から総当たりで元のパスワードを推測されやすくなります。bcryptやArgon2のような、パスワード保存用に設計された関数を指定するのが、現在の一般的な推奨です。

どこまで細かく書くか：粒度の目安

基本設計書で最も迷うのが、書く細かさです。次の2つを基準にすると判断しやすくなります。

• お客様が、その内容を見て「これでよい」と判断できるか
• 詳細設計を担当する人が、仕様について質問せずに作業を始められるか

利用者やお客様から見て違いがあることは基本設計に、見て違いがないこと（作り方）は詳細設計に書く、と考えると整理しやすくなります。

よくある失敗と対策

レビューのチェックリスト

基本設計書のレビューでは、次の観点を確認します。

▶ 要件との対応

• □ すべての要件が、いずれかの機能に対応しているか
• □ 要件にない機能や仕様が追加されていないか
• □ 対象範囲と対象外が明記されているか

▶ 正しさと網羅性

• □ 正常時だけでなく、エラー時・境界値（0件、上限、空欄）の動きが書かれているか
• □ 二重送信、通信エラー、タイムアウト時の動きが決まっているか
• □ 画面・帳票・テーブル・外部連携の間で、項目名・型・桁数が一致しているか
• □ 日付・時刻のタイムゾーンや、締め日の扱いが決まっているか

▶ 非機能要件

• □ 性能・可用性・セキュリティの要件が、数値や具体的な方法で書かれているか
• □ 個人情報の扱い（保存・表示・ログへの出力）が決まっているか
• □ バックアップ、障害時の復旧、運用の手順が考慮されているか

▶ わかりやすさ

• □ お客様が読んで理解できる言葉で書かれているか
• □ あいまいな表現（適切に、速やかに、など）がないか
• □ 用語が統一され、用語集と一致しているか
• □ 版番号と変更履歴が記録されているか

書き方のコツ

• 文章より表と図：項目の定義は表、流れは図にすると、読み手が確認しやすく、漏れにも気づきやすい
• 1つの情報は1か所に：同じ定義を複数の資料に書くと、変更時に食い違う。参照する形にする
• 決まっていないことは「未決」と書く：空欄や推測で埋めず、課題として管理する
• お客様と一緒に確認する：画面のモックアップやプロトタイプを見せながらレビューすると、認識のずれを早く見つけられる

アジャイル開発やAI活用の時代の基本設計

アジャイル開発では、最初にすべての設計書を作り込むのではなく、開発しながら必要な設計を書き足していく進め方が一般的です。それでも、非機能要件・データ設計・外部連携のように、後から変えるのが難しく、関係者の合意が必要なものは、早い段階で文書にしておく価値があります。

また、設計書をExcelやWordではなく、Markdownなどのテキストで書いてGitで管理するチームも増えています。変更履歴が自動で残り、レビューもプルリクエストで行えます。前述の画面遷移図のように、図もテキスト（Mermaidなど）で書けます。

AIのコーディング支援を使う場合、基本設計書はAIへの指示書にもなります。画面項目定義や入力チェック、エラー時の動きが明確に書かれているほど、AIが生成するコードの精度は上がります。AIに設計書の下書きを作らせることもできますが、要件との対応や非機能要件の数値は、人が必ず確認します。また、お客様の機密情報を、許可されていないAIサービスに入力しないよう注意が必要です。

よくある質問

Q. 基本設計と外部設計は同じですか？ A. ほぼ同じ意味で使われます。利用者から見える部分（外部）を設計するため、外部設計と呼ばれます。会社やプロジェクトによって呼び方が違うだけで、内容は大きく変わりません。

Q. 基本設計書は誰が書きますか？ A. システムエンジニア（SE）が中心となって書くのが一般的です。業務の知識が必要な部分は、お客様や業務の担当者と相談しながら進めます。

Q. Excel・Word・Markdownのどれで書くべきですか？ A. お客様やチームの慣習に合わせるのが基本です。表が多い画面項目定義やテーブル定義はExcel、文章が中心の部分はWordがよく使われます。変更の管理を重視する場合は、Markdownで書いてGitで管理する方法もあります。

Q. 基本設計にはどれくらいの期間がかかりますか？ A. プロジェクトの規模によって大きく異なります。一般的には、要件定義と同じくらいか、やや長い期間を見込むことが多いです。後の工程で手戻りが起きるほど費用が大きくなるため、基本設計で認識をしっかり合わせておくことが、全体の期間の短縮につながります。

まとめ

• 基本設計書は、システムが外から見てどう動くかを、お客様と合意するための文書
• 要件定義は「何を」、基本設計は「外から見てどう動くか」、詳細設計は「内部でどう作るか」
• 成果物は、合意しておかないと揉めるもの、開発者が迷うものを優先して作る
• 画面・バッチ・外部連携は、正常時だけでなく、エラー時・二重操作・再実行まで書く
• 非機能要件は数値で。パスワードはbcryptやArgon2などの専用の関数で保存する
• 機能には要件IDを対応させ、用語集・対象外・変更履歴を忘れずに
• 詳しく書かれた設計書は、AIへの指示書としても力を発揮する

株式会社RJCでは、SI事業を通じて、お客様とともに要件を整理し、設計からシステムを形にしています。設計書を「伝わる」形で書く力を、仲間と一緒に高め合いながら、成長を楽しんでいます。

株式会社RJC ― SI事業・SES事業・AI駆動開発。未経験からエンジニアに育てるのが得意な会社です。