基本設計書と詳細設計書の書き方|既存システムから起こす手順も

2026.11.10


基本設計書は「システムが外から見て何をするか」を、詳細設計書は「それを中でどう実現するか」を決める文書です。名前は知っていても、どこまでを基本設計に書き、どこからを詳細設計に回すかは、現場ごとに揺れがちです。この記事では、2つの違い、書く項目、書き方の手順を整理したうえで、同じ機能を両方の設計書で書いた見本を示します。後半では、設計書が残っていない既存システムから設計書を起こす手順も扱います。


基本設計書と詳細設計書の違い

基本設計書と詳細設計書の違いは、決める対象と読み手にあります。

観点基本設計書詳細設計書
別名外部設計書内部設計書
決めること外から見た仕様(画面・帳票・入出力・業務ルール)中での実現方法(処理手順・計算式・データ更新・例外処理)
主な読み手業務部門・発注者・開発者開発者・テスト担当・保守担当
単位機能・画面ごと処理・モジュールごと
対応するテスト結合テスト単体テスト

開発の流れで見ると、要件定義で「何が必要か」を決め、基本設計で「システムとして何をするか」に落とし、詳細設計で「どう作るか」まで具体化します。テストはこの逆順に確かめていきます。詳細設計に対して単体テスト、基本設計に対して結合テスト、要件定義に対してシステムテストを行う、いわゆるV字モデルの対応です。

ただし、外部と内部の境界はプロジェクトによって違います。業務ルールの計算式を基本設計に書く現場もあれば、詳細設計に回す現場もあります。迷ったときは「業務部門が確認すべき内容か」で分けると、判断がぶれにくくなります。

基本設計書に書く項目

項目書く内容
システム概要・構成目的、範囲、システム構成図、他システムとの関係
業務フロー誰が、いつ、どの機能を使うか
機能一覧機能ID、機能名、画面・バッチ・連携の区分
画面設計画面一覧、レイアウト、入力項目、画面遷移
帳票設計帳票一覧、レイアウト、出力条件
バッチ設計バッチ一覧、起動条件、実行タイミング
データ設計ER図、テーブル一覧
外部インターフェース連携先、方式、タイミング、データ項目
業務ルール・メッセージ判定条件、計算の考え方、エラー時の表示
非機能性能、セキュリティ、運用・バックアップ

ER図やフローチャートなど、図ごとの役割の違いは「フローチャート・シーケンス図・ER図——誰のために書くドキュメントか」で詳しく整理しています。

詳細設計書に書く項目

項目書く内容
モジュール構成機能を実現するクラス・関数・バッチの分担
処理フロー処理の順番、分岐、呼び出し関係(フローチャート、シーケンス図)
計算式・判定条件金額や日付の計算、端数処理、境界値の扱い
テーブル定義項目、型、桁、制約、どの処理がどのテーブルを更新するか
入出力の詳細ファイルや電文のレイアウト、文字コード
例外処理想定する異常、エラー時の戻し方、再実行の可否
ログ・トランザクション記録する内容、更新をまとめる範囲

書き方の手順

基本設計書は、業務部門と合意するための文書として書きます。

  1.要件定義書から機能を洗い出し、機能一覧を作る
  2.業務フローの各場面に機能を当てはめ、漏れを確かめる
  3.機能ごとに画面・帳票・バッチ・外部連携を決める
  4.業務ルールとエラー時のメッセージを書く
  5.性能やセキュリティなどの非機能を書く
  6.業務部門とレビューし、合意した版を固定する

    詳細設計書は、開発者が迷わず実装し、テスト担当がテストを作れる文書として書きます。

      1.基本設計の機能ごとに、担当するモジュールを決める
      2.処理の手順を、上から順に実行できる粒度で書く
      3.計算式と判定条件を、数式や表で書く
      4.更新するテーブルと、更新のタイミングを書く
      5.想定する例外を洗い出し、それぞれの扱いを書く
      6.単体テストの観点を書き出せるか確かめる。書き出せなければ、どこかが曖昧なままです

      目次のテンプレートは次のとおりです。コピーして、そのまま使えます。

      # 基本設計書:[機能名]
      1. 機能概要(目的・利用者・利用場面)
      2. 画面設計(レイアウト・入力項目・画面遷移)
      3. 業務ルール(判定条件・計算の考え方)
      4. メッセージ一覧
      5. 関連する帳票・バッチ・外部連携
      6. 非機能(性能・権限)
      
      # 詳細設計書:[機能名]
      1. モジュール構成
      2. 処理フロー
      3. 計算式・判定条件(境界値を含む)
      4. テーブル更新(テーブル・操作・タイミング)
      5. 例外処理
      6. トランザクションとログ
      
      
      

      見本:同じ機能を基本設計と詳細設計で書く

      ここでは、架空の卸売会社「サンプル商事」の販売管理システムを例にします。10年以上前に作られ、作った人はもう社内にいない、という設定のよくあるシステムです。題材は、営業担当が得意先の注文を登録する「受注登録」です。

      基本設計書(抜粋)

       ・機能概要:営業担当が得意先からの注文を登録する。登録時に、単価・送料・出荷予定日を決め、与信限度額を
        確かめる
       ・主な入力項目:得意先コード(必須)、納期(必須・当日以降)、商品コード(必須)、数量(必須・1〜9,999)
       ・自動で決まる項目:単価、金額、送料、出荷予定日
       ・業務ルール
        ・単価:特価が登録されていれば特価、なければ得意先のランクと商品の分類で決まる掛け率を標準単価にかける
        ・送料:1回の出荷が税抜1万円未満なら800円
        ・出荷予定日:物流センターごとの締め時刻までに確定すれば当日、過ぎれば翌営業日
        ・与信:未入金の残高と今回の受注額の合計が限度額を超えたら、承認待ちとして登録する
        ・メッセージ:「与信限度額を超えるため、承認待ちとして登録しました」

      詳細設計書(抜粋)

        1.入力チェック:得意先が取引停止なら登録しない。販売終了の商品が含まれていれば登録しない
        2.単価の決定:特価マスタに、受注日が有効期間内(開始日以上かつ終了日以下)の行があれば特価を使う。
          なければ「標準単価 × 掛け率」とし、1円未満は切り捨てる
        3.送料:明細の税抜合計が10,000円未満なら800円、10,000円ちょうどは無料
        4.出荷予定日:確定時刻が物流センターマスタの締め時刻以前で、かつ営業日カレンダー上の稼働日なら
          当日。それ以外は次の稼働日
        5.与信判定:判定用の税込額は、税率ごとの税抜合計に税率をかけて合算し、1円未満を切り捨てる
          (請求額の計算は請求締めの処理で別に行う)。「未入金残高 + 判定用税込額 > 与信限度額」なら状態を
          「与信保留」とする。限度額ちょうどは通す
        6.テーブル更新:受注ヘッダと受注明細を登録し、与信保留なら与信保留テーブルにも登録する。
          3つは1つのトランザクションで更新し、どれかが失敗したらすべて取り消す
        7.注意:在庫の引当は夜間バッチで行うため、受注登録の時点では在庫を確保しない

        並べると、違いがはっきりします。基本設計書は「何を決めるか」を業務の言葉で書き、業務部門が確認できる形にしています。詳細設計書は、同じルールを「どの順で、どの値を使い、境界をどう扱い、どのテーブルをどう更新するか」まで書き、そのまま実装とテストに使える形にしています。たとえば「1万円未満」の一言も、詳細設計では「1万円ちょうどは無料」まで決めておく必要があります。

        よくある失敗と、確認の観点

        レビューでは、次の5点を確かめると、後工程での手戻りを減らせます。

         ・曖昧な言葉が残っていないか:「適宜」「など」「速やかに」は、読む人によって解釈が変わります
         ・境界が決まっているか:「以上」と「超える」、締め時刻ちょうど、月末や2月末の扱い
         ・例外が書かれているか:取引停止の得意先、販売終了の商品、同じデータを2人が同時に更新した場合
         ・理由が残っているか:送料の基準額や締め時刻が「なぜその値なのか」は、数年後に変更を検討するときに
          必要になります
         ・実装と食い違ったまま放置されていないか:改修のたびに設計書を直さないと、数年で
          「設計書はあるが当てにならない」状態になります。

        設計書がない既存システムで起こすとき

        長く使われているシステムでは、設計書がそもそもない、あっても実装と食い違っている、ということが珍しくありません。保守の担当が替わる、外部の開発会社との契約が終わる、といった事情が重なると、仕様を知る手がかりはコードだけになります。その経緯は「日本のSIer文化とドキュメント問題」でも扱っています。

        設計書を起こすときは、次の順で進めると無駄が少なくなります。

          1.範囲を絞る:全部を起こそうとすると終わりません。改修の予定がある機能、障害の多い機能、
            移行の対象になる機能から始めます
          2.外から見える仕様を起こす:実際に画面を操作し、本番の帳票や連携ファイルを集めて、基本設計に
            当たる部分を書きます
          3.データ構造を起こす:データベースからテーブル定義を取り出します。外部キーが定義されていなければ、
            項目名や、コードの中の結合条件から関係を推定します
          4.処理を起こす:画面のイベント、コントローラ、バッチの起動点など、処理の入口から順に追います。
            コードの中のSQLを抜き出すと、どの処理がどのテーブルを読み書きしているかが見えてきます
          5.業務ルールの「なぜ」を聞き取る:コードを読めば「何をしているか」は分かりますが、
            「なぜそうしているか」は分かりません。業務部門に確かめ、理由を設計書に残します
          6.食い違いを仕分ける:起こした仕様と業務部門の認識が違う場合、それが不具合なのか、
            意図した例外なのかを決めます。判断がつくまでは、どちらとも決めつけずに記録しておきます

          手作業では2〜4に最も時間がかかります。ここを自動化する方法もあります。DigKnowが開発するCodeledgeは、GitHubなどのリポジトリを連携すると、既存のソースコードから詳細仕様書やフローチャート、シーケンス図を生成し、コードの更新に合わせて最新の状態に保ちます。自動で起こした設計書を土台にして、5の「なぜ」と6の仕分けを人が書き足していくのが、現実的な進め方です。

          AIで開発するときの設計書

          AIにコードを書かせる開発が広がり、設計書の役割は「後から読むための記録」から、「AIへの指示」と「AIが書いたコードを確かめる基準」へ広がっています。要件や設計を先に文書で固めてからAIに実装させる仕様駆動開発も、この流れの上にあります。設計書がないままAIに任せると、AIは決められていない部分をそれらしく補い、その判断はどこにも残りません。この点は「仕様駆動開発はなぜ「設計書」を必要とするのか」で詳しく扱っています。

          よくある質問

          アジャイル開発でも詳細設計書は必要ですか?

          短い周期で作って直すアジャイル開発では、詳細設計書を作らずに、コードとテストで代えることが多くあります。ただし、計算式・境界値・例外処理・データ更新の順序のように、コードを細かく読まないと分からない部分は、文書で残しておく価値が高い部分です。


          基本設計書と詳細設計書は、誰が書きますか?

          基本設計書は、要件をまとめたSEやプロジェクトの担当者が、業務部門と相談しながら書くのが一般的です。開発を外部に委託する場合は、開発会社が書いて発注側が確認する形が多く見られます。詳細設計書は、実装を担当する開発者やチームのリーダーが書きます。


          設計書はExcelとMarkdown、どちらで書くべきですか?

          項目定義を表で管理しやすいため、Excelで書く現場が多く見られます。変更の履歴を細かく追いたい場合や、コードと一緒に管理したい場合は、Markdownで書いてGitで管理する方法もあります。大切なのは形式より、実装が変わったときに設計書も直す運用を決めておくことです。


          要件定義書と基本設計書は、何が違いますか?

          要件定義書は、システムで何を実現したいか(業務上の要求、範囲、制約)を発注側と合意する文書です。基本設計書は、それを受けて、システムとして何をするか(画面、帳票、業務ルール、外部との連携)を具体的な形にした文書です。要件定義書が「何のために、何を」、基本設計書が「どんな形で」を決めます。


          基本設計書と外部設計書は同じものですか?

          ほぼ同じ意味で使われます。ただし、どこまでを含めるかは会社やプロジェクトで違うため、最初に目次を合意しておくと混乱を防げます。

          まとめ

          基本設計書は外から見た仕様を業務部門と合意するための文書、詳細設計書はそれをどう実現するかを開発者とテスト担当に伝える文書です。同じ業務ルールでも、詳細設計では境界値や例外、テーブル更新の順序まで決めておく必要があります。設計書のない既存システムでは、範囲を絞り、外から見える仕様、データ、処理の順に起こし、最後に業務ルールの「なぜ」を人が書き足していきます。

          設計書が残っていない古いシステムは、どこから手を付ければよいのでしょうか。次回は、いわゆるレガシーシステムが抱える問題と、可視化から始める進め方を取り上げます。

          ところで、AIがコードを書く時代ほど、「いまのコードが何をしているか」を把握し続けることが大切になります。私たちDigKnowが開発する「Codeledge(コードレッジ)」は、ソースコードから技術ドキュメントを自動生成するAIサービスです。GitHubなどのリポジトリを連携するだけで、AIが仕様書・設計書を作成し、コードの更新に合わせて最新の状態に保ちます。AIコードドキュメンテーションで、「コードは残るが、仕様は誰も知らない」という問題を解決します。→ Codeledgeについて詳しく見る



          桑原 脩(くわはら おさむ)|DigKnow株式会社 執行役員/CTO
           大阪大学大学院でシステム工学を専攻。大日本印刷(DNP)で、IoTによる医療分野の遠隔監視システムの構築や、データ分析による生産現場のDXに携わり、最適化システム構築のPMも務める。社内の引き継ぎで技術的負債に直面した経験から、2025年10月、創業メンバーとしてDigKnowに参画。Codeledgeのプロダクト開発と技術戦略を担う。