詳細設計書のサンプル・記入例 記載項目と書き方、基本設計書との違いとどこまで書くかを解説

「詳細設計書を書くことになったが、基本設計書と何が違うのか、どこまで細かく書けばよいのかわからない」「テンプレートはあるが、処理仕様やAPI仕様の具体的な記入例が見たい」という声は、設計工程を初めて担当するエンジニアや、開発会社から納品された設計書を確認する発注側の担当者からよく聞かれます。

この記事では、詳細設計書の役割と基本設計書との違いを整理したうえで、架空のプロジェクトを題材にした記入例を項目ごとに掲載し、「どこまで書くか」の判断基準、テンプレートの活用方法、作成時の注意点までを解説します。まずは、この記事の要点を表で確認してください。

確認したいポイント	結論	詳細
詳細設計書と基本設計書の違いは？	基本設計は「何を」、詳細設計は「どのように」	基本設計は発注者が承認する外から見える設計。詳細設計は処理手順・データ物理定義・API仕様など実装者向けの内部設計
記載項目は？	設計方針から単体テスト仕様まで9項目	文書概要、モジュール構成、画面処理仕様、処理仕様、DB物理設計、API仕様、バッチ仕様、共通・エラー・ログ設計、単体テスト
どこまで書けばよい？	コードでわかることは書かず判断が分かれる点は必ず書く	入力チェック・エラー時動作・処理順序・境界値など実装者の解釈が分かれる部分を明文化。理由と業務ルールを残す
サンプルで何がわかる？	処理仕様・API・テーブル・バッチ・AI処理の記入粒度	問い合わせ対応支援システムを題材に、回答送信処理やAI回答案生成の手順、エラーコード体系、テストケースを掲載

この記事でわかること

• 詳細設計書の役割と、基本設計書・ソースコードとの違い
• 詳細設計書に含める9の記載項目と、それぞれに書く内容
• 架空の問い合わせ対応支援システムを題材にした、処理仕様・API仕様・テーブル定義などの記入例
• 「どこまで書くか」を判断する基準と、書き方のコツ
• テンプレートの活用方法と、作成・確認時の注意点

詳細設計書とは

詳細設計書とは、基本設計で定めた画面・データ・機能の構成を、プログラムとして実装できる粒度まで具体化した文書です。内部設計書やプログラム設計書と呼ばれることもあります。ここでは、詳細設計書の役割、基本設計書との違い、公的な枠組みでの位置づけ、読み手について整理します。

詳細設計書の役割

詳細設計書は、実装を担当するエンジニアが迷わずにコードを書けるようにするための指示書です。処理の流れ、データの加工方法、入力チェックの条件、エラー時の動作、外部との通信仕様などを具体的に定めます。

また、実装後の単体テストの根拠になり、運用開始後の保守・改修の際にシステムの内部を理解するための資料にもなります。実装の指示書であると同時に、将来の保守担当者への引き継ぎ資料でもあるという2つの役割を意識すると、書くべき内容が見えてきます。

基本設計書との違い

• 基本設計書：利用者や発注者から見えるシステムの姿（画面・帳票・データ・外部連携・構成）を設計する。発注者が承認する文書
• 詳細設計書：システムの内部の仕組み（モジュール構成・処理ロジック・データの物理定義・API仕様）を設計する。開発チーム内で使う文書

たとえば基本設計書では「送信ボタンを押すと回答が顧客にメールで送られ、状態が回答済みになる」と書きますが、詳細設計書では「送信ボタン押下時に入力チェック→回答テーブル更新→メール送信処理呼び出し→状態更新→履歴登録の順に処理し、メール送信に失敗した場合は状態を更新せずエラーコードE-201を返す」というレベルまで書きます。基本設計が「何を」、詳細設計が「どのように」を定めるという違いです。

基本設計書の役割や記載項目、記入例については、基本設計書のサンプル・記入例の記事で詳しく解説しています。本記事のサンプルは、その記事と同じプロジェクトを題材にしています。

公的な開発プロセスの枠組みにおける位置づけ

独立行政法人情報処理推進機構（IPA）が公開している「共通フレーム2013」では、詳細設計に相当する工程が「ソフトウェア詳細設計プロセス」として定義されています。ソフトウェア方式設計（基本設計に相当）で定めた構造をもとに、各コンポーネントをソフトウェアユニットのレベルまで詳細化し、インターフェースやデータベースの詳細設計、ユニットテストの要求事項を定義する工程です。

（出典：独立行政法人情報処理推進機構（IPA）「共通フレーム2013」 https://www.ipa.go.jp/publish/secbooks20130304.html）

共通フレームは、発注者と開発者が「同じ言葉で話す」ための枠組みであり、会社ごとに異なる工程名や成果物の呼び方を照らし合わせる基準になります。「詳細設計」という言葉が指す範囲が、自社と開発会社で一致しているかを確認する際に活用できます。

誰が作成し、誰が読むのか

詳細設計書は、開発チームの設計担当者や実装担当者が作成します。読み手は、実装を行うエンジニア、単体テストを行う担当者、レビューを行う上位のエンジニア、そして運用開始後の保守担当者です。発注者が直接読むことは少ないものの、納品物として受け取り、保守や改修の際に参照することになります。

読み手が技術者であるため、業務的な説明よりも、処理の正確さと曖昧さのなさが求められます。「この文書を読めば、誰が実装しても同じ動作のプログラムになる」状態が、詳細設計書の目指すところです。

詳細設計書の構成と記載項目

詳細設計書の様式は会社やプロジェクトによって異なりますが、記載する項目はおおむね共通しています。ここでは、一般的な詳細設計書に含める9の項目と、それぞれに書く内容を解説します。次章のサンプルも、この構成に沿って記載しています。

1. 文書概要と設計方針

文書の目的、対象読者、参照する基本設計書のバージョン、改訂履歴を記載します。あわせて、実装に関わる共通方針（採用するフレームワークの使い方、コーディング規約、命名規則、共通部品の使い方、ログやエラーの扱い方）を冒頭に示し、個々の設計の一貫性を保ちます。

2. モジュール構成

システムを構成するプログラムの単位（モジュール、クラス、関数など）とその関係を記載します。どの機能がどのモジュールで実現され、モジュール間でどのように呼び出し合うかを、構成図や一覧で示します。

3. 画面の処理仕様

基本設計の画面設計をもとに、各画面で発生する操作（ボタン押下、項目の変更、画面表示など）ごとに、実行する処理の内容、入力チェックの条件とエラーメッセージ、呼び出す共通処理やAPI、更新するデータ、画面遷移の条件を記載します。

4. 処理仕様（ロジック設計）

業務上の判断や計算を含む処理について、処理の手順、条件分岐、計算式、例外的なケースの扱いを記載します。処理の流れは、フローチャートや疑似コード、シーケンス図などを使って表現します。

5. データベース物理設計

基本設計のテーブル定義をもとに、物理的なデータ型、桁数、インデックス、制約（主キー・外部キー・一意制約・NOT NULL）、初期データを確定します。あわせて、各処理がどのテーブルを参照・更新するかの対応（CRUD図）を記載すると、影響範囲の把握に役立ちます。

6. API・インターフェース仕様

画面とサーバー間、モジュール間、外部システムとの通信について、エンドポイント、メソッド、リクエストとレスポンスの項目・型・必須条件、認証方式、エラー時のレスポンス、タイムアウトや再試行の方針を記載します。

7. バッチ処理仕様

基本設計のバッチ一覧をもとに、各バッチの起動条件、入力データ、処理手順、出力データ、処理件数の上限、異常終了時の扱い（再実行の可否、途中まで処理したデータの扱い）、実行ログの内容を記載します。

8. 共通処理・エラー処理・ログ設計

複数の機能で共通して使う処理（認証、権限チェック、日付変換、メール送信など）の仕様と、エラーコードの体系、エラー発生時の画面表示・ログ出力・通知の方針、ログの出力項目と保存先を記載します。

9. 単体テスト仕様

各モジュールや処理について、テストの観点（正常系・異常系・境界値）、テストケース、期待する結果を記載します。詳細設計書に書いた条件分岐やエラー処理が、そのままテストケースの根拠になります。

すべての項目を同じ深さで書く必要はなく、プロジェクトの規模と開発チームの習熟度に応じて、書くべき粒度を決めることが重要です。その判断基準は、後の章で解説します。

【無料資料のご案内】 要件定義から基本設計・詳細設計・実装・運用までを一貫して支援するサービスの内容や、設計工程の進め方をまとめた資料を無料でご用意しています。まずは概要を確認したい方は、以下から資料をご請求ください。 ▶ 資料請求はこちら（https://nextscale.co.jp/service-document/）

【サンプル】問い合わせ対応支援システムの詳細設計書

ここからは、架空のプロジェクトを題材にした詳細設計書の記入例を紹介します。題材は、中堅のBtoB企業が顧客からの問い合わせを一元管理し、過去の対応履歴やFAQをもとにAIが回答案を作成する「問い合わせ対応支援システム」です。基本設計書の記事で定めた画面ID（SCR-）、バッチID（BAT-）、連携ID（IF-）をそのまま使い、詳細設計でどのように具体化されるかを示します。

1. 文書概要と設計方針（記入例）

• 文書の目的：本書は、問い合わせ対応支援システム 基本設計書（第1.1版）に基づき、各機能の処理仕様・データの物理定義・API仕様・バッチ仕様・共通処理を、実装可能な粒度で定めるものである
• 対象読者：開発会社の実装担当者、単体テスト担当者、レビュー担当者。運用開始後は保守担当者
• 共通方針1：画面からの操作はすべてサーバー側のAPIを経由し、画面側では業務ロジックを持たない
• 共通方針2：データベースの更新は1操作1トランザクションとし、途中で失敗した場合はすべて取り消す
• 共通方針3：外部サービス（基幹システム、メール、AIサービス）との通信は共通部品を経由し、タイムアウトと再試行の方針は共通処理設計に従う
• 共通方針4：エラーは「E-」で始まるエラーコードで管理し、利用者向けメッセージと開発者向けログを分けて出力する

設計方針は、個々の処理設計の判断基準になります。「画面にロジックを持たない」「1操作1トランザクション」といった原則を最初に決めておくことで、実装者ごとの書き方のばらつきを防げます。

2. モジュール構成（記入例）

• 画面層：SCR-020 案件詳細・回答画面 → CaseDetailView（表示・入力制御のみ）
• API層：CaseController（案件の取得・更新）、AnswerController（回答の送信）、AiDraftController（回答案の取得）
• 業務層：CaseService（案件の状態管理）、AnswerService（回答送信と履歴登録）、AiDraftService（参照情報の抽出と回答案生成の呼び出し）、SimilarSearchService（類似案件の検索）
• データアクセス層：CaseRepository、CaseHistoryRepository、FaqRepository、CustomerRepository
• 共通部品：AuthGuard（認証・権限）、MailClient（メール送受信）、AiClient（AIサービス通信）、MaskingUtil（個人情報の除去）、AppLogger（ログ出力）

モジュール構成は、機能ごとの責任範囲を明確にするために記載します。どの層が何を担当し、何をしてはいけないかを示すことで、ロジックが画面側に散らばるといった問題を防げます。

3. 画面の処理仕様：SCR-020 案件詳細・回答画面（記入例）

画面表示時の処理は次のとおりです。

• 1. AuthGuard で認証状態と閲覧権限を確認する。権限がない場合はE-001を返し、ログイン画面へ遷移する
• 2. CaseController.get(case_id) を呼び出し、案件情報・顧客情報・過去履歴を取得する
• 3. 案件の状態が「未着手」の場合、AiDraftController.get(case_id) を非同期で呼び出し、回答案の取得を開始する。取得中は「回答案を作成中」と表示する
• 4. 回答案の取得が完了したら、回答案・参照情報・確信度を表示する。60秒以内に取得できない場合は「回答案なし」と表示し、E-301をログに記録する

送信ボタン押下時の処理は次のとおりです。

• 1. 入力チェック：回答本文が空の場合はE-101「回答本文を入力してください」を表示し、処理を中断する。5,000文字を超える場合はE-102を表示する
• 2. 確認ダイアログ「顧客に回答を送信します。よろしいですか」を表示し、キャンセルの場合は処理を中断する
• 3. AnswerController.send(case_id, answer_body, draft_evaluation) を呼び出す
• 4. 正常に完了した場合、案件一覧画面（SCR-010）へ遷移し、「回答を送信しました」と表示する
• 5. E-201（メール送信失敗）が返された場合、「メールの送信に失敗しました。時間をおいて再度お試しください」と表示し、画面に留まる。入力内容は保持する

入力チェックの条件、エラー時の動作、入力内容の保持といった細部まで書くことで、実装者が「この場合はどうするか」を自分で判断しなくてよい状態にします。

4. 処理仕様：回答送信処理 AnswerService.send（記入例）

処理の手順は次のとおりです。すべて1トランザクション内で実行し、途中で失敗した場合はデータベースの更新を取り消します。

• 1. CaseRepository から案件を取得し、状態が「未着手」または「対応中」であることを確認する。それ以外の場合はE-202「この案件はすでに回答済みです」を返す
• 2. 顧客のメールアドレスを CustomerRepository から取得する。取得できない場合はE-203を返す
• 3. MailClient.send(宛先、件名「【回答】案件番号：{case_id}」、本文＝回答本文＋署名テンプレート) を呼び出す。送信に失敗した場合はE-201を返し、以降の処理を行わない
• 4. CaseRepository を更新する：status＝3（回答済み）、answered_at＝現在日時、updated_at＝現在日時
• 5. CaseHistoryRepository に履歴を登録する：種別＝回答送信、担当者ID、回答本文、回答案の評価（採用・修正採用・不採用）
• 6. 処理結果を AppLogger に出力する（案件ID、担当者ID、処理時間）

処理の順序には理由があります。メール送信に失敗したら状態を更新しない、という業務上の要求を「メール送信を状態更新より先に行う」という処理順序で実現していることがわかるよう、順序の根拠も設計書に残しておくと保守時に役立ちます。

5. 処理仕様：AI回答案生成 AiDraftService.generate（記入例）

AIを含む処理は、参照情報の作り方と出力の扱いを特に丁寧に設計します。

• 1. 案件の問い合わせ本文を取得し、MaskingUtil で顧客名・メールアドレス・電話番号を除去する（正規表現と顧客マスタとの照合で判定）
• 2. SimilarSearchService で、問い合わせ本文と類似度0.7以上の過去案件を類似度の高い順に最大5件取得する。取得対象は状態＝完了の案件に限る
• 3. FaqRepository から、案件の分類と一致するFAQを更新日の新しい順に最大5件取得する
• 4. 本文に含まれる製品コード（形式：英字2桁＋数字6桁）を抽出し、対応する製品情報を取得する
• 5. 上記の参照情報と、回答案の生成指示（別紙：プロンプト定義書 v1.0）を AiClient.generate に渡す。タイムアウトは60秒、再試行は行わない
• 6. 応答から回答案本文を取得し、5,000文字を超える場合は5,000文字で切り詰める
• 7. 確信度を判定する：類似案件の最高類似度が0.9以上かつFAQ一致あり→高、0.8以上→中、それ以外→低
• 8. 回答案・参照した案件IDとFAQ ID・確信度を CaseRepository の ai_draft、ai_refs、ai_confidence に保存する
• 9. 手順2〜5でエラーが発生した場合は回答案を生成せず、E-301〜E-304をログに記録して「回答案なし」を返す。画面には影響させない

AIサービスへの指示文（プロンプト）は変更が頻繁に発生するため、別紙として管理し、版数で参照する形にしています。個人情報の除去、参照情報の条件、確信度の判定基準、失敗時の扱いを数値と条件で明文化することが、AI処理の詳細設計の要点です。

6. データベース物理設計：T_CASE（記入例）

• case_id：VARCHAR(12)、主キー、NOT NULL。形式はYYYYMMDD＋4桁連番。採番は採番テーブル T_SEQ を排他制御して行う
• received_at：DATETIME、NOT NULL
• channel：CHAR(1)、NOT NULL、CHECK制約（1・2・3のいずれか）
• customer_id：VARCHAR(10)、NOT NULL、外部キー（T_CUSTOMER.customer_id）
• category：CHAR(1)、NOT NULL、CHECK制約（1・2・3・4・9のいずれか）
• body：TEXT、NOT NULL
• assignee_id：VARCHAR(8)、NULL可、外部キー（T_USER.user_id）
• status：CHAR(1)、NOT NULL、初期値1
• ai_draft：TEXT、NULL可
• ai_refs：VARCHAR(500)、NULL可。参照した案件IDとFAQ IDをカンマ区切りで保持
• ai_confidence：CHAR(1)、NULL可（H・M・L）
• answered_at：DATETIME、NULL可
• updated_at：DATETIME、NOT NULL、更新のたびに現在日時を設定
• インデックス：IDX_CASE_STATUS（status, received_at）を案件一覧の絞り込み用に作成。IDX_CASE_ASSIGNEE（assignee_id, status）を担当者別表示用に作成

あわせて、各処理とテーブルの対応（CRUD図）として、「AnswerService.send はT_CASEを更新（U）、T_CASE_HISTORYを作成（C）、T_CUSTOMERを参照（R）する」といった対応表を記載します。どの処理がどのデータを触るかを一覧化しておくと、改修時の影響調査が容易になります。

7. API仕様：POST /api/cases/{case_id}/answer（記入例）

• 概要：案件に対する回答を送信し、状態を回答済みに更新する
• 認証：セッショントークン必須。権限は「担当者」または「管理者」
• リクエスト（JSON）：answer_body（文字列、必須、1〜5,000文字）、draft_evaluation（文字列、必須、adopted・modified・rejected のいずれか）
• レスポンス（成功時 200）：case_id、status（3）、answered_at
• レスポンス（失敗時）：400＝E-101/E-102（入力不正）、403＝E-001（権限なし）、409＝E-202（状態不整合）、502＝E-201（メール送信失敗）。いずれも error_code と message を含む
• 処理：AnswerService.send を呼び出す。処理時間の目標は3秒以内
• 冪等性：同一案件への2回目以降の送信はE-202を返し、重複送信を防ぐ

8. バッチ処理仕様：BAT-001 メール取り込み・割り当て（記入例）

• 起動：5分間隔でスケジューラーから起動する。前回の実行が終了していない場合は起動しない（排他制御）
• 処理手順：(1) MailClient で未読メールを最大200件取得する。(2) メールIDが T_MAIL_LOG に存在する場合は重複としてスキップする。(3) 件名と本文から分類を判定する（分類判定ルール：別紙 v1.0）。(4) T_ASSIGN_RULE から分類に対応する担当者を取得し、対象が複数の場合は担当中の案件数が最少の担当者を選ぶ。(5) T_CASE に登録し、T_MAIL_LOG にメールIDを記録する。(6) メールを既読にする
• 1件ごとのトランザクション：1通の処理が失敗しても他の処理は継続し、失敗したメールIDとエラーコードをログに記録する
• 異常終了：メールサーバーに接続できない場合はE-401を記録して終了し、次回起動時に再試行する。管理者への通知は3回連続で失敗した場合に行う
• 実行ログ：開始・終了日時、取得件数、登録件数、スキップ件数、失敗件数

9. エラーコード体系と単体テスト仕様（記入例）

エラーコードの体系は次のとおりです。

• E-0xx：認証・権限（E-001 権限なし）
• E-1xx：入力チェック（E-101 必須未入力、E-102 文字数超過）
• E-2xx：業務エラー（E-201 メール送信失敗、E-202 状態不整合、E-203 顧客情報なし）
• E-3xx：AI処理（E-301 タイムアウト、E-302 類似検索失敗、E-303 FAQ取得失敗、E-304 AIサービス応答異常）
• E-4xx：バッチ・外部連携（E-401 メールサーバー接続失敗、E-402 基幹連携ファイル不正）

単体テスト仕様の例として、AnswerService.send のテストケースを示します。

• TC-001（正常系）：状態＝未着手、回答本文あり → 状態が回答済みになり、履歴が1件登録され、メールが1通送信される
• TC-002（異常系）：状態＝回答済み → E-202が返り、データは更新されない
• TC-003（異常系）：メール送信が失敗 → E-201が返り、状態・履歴は更新されない
• TC-004（境界値）：回答本文が5,000文字 → 正常に処理される。5,001文字 → E-102が返る
• TC-005（異常系）：顧客のメールアドレスが未登録 → E-203が返る

設計書に書いた条件分岐とエラー処理が、そのままテストケースになることがわかります。設計とテストを対応付けることで、テストの抜け漏れも防げます。

詳細設計書はどこまで書くべきか

詳細設計書で最も判断に迷うのが「どこまで細かく書くか」です。書きすぎれば作成と保守の負担が増え、書かなければ実装者の判断がばらつきます。ここでは、記述の深さを判断するための考え方を解説します。

ソースコードを読めばわかることは書かない

変数名の一覧や、コードをそのまま日本語にしたような処理の記述は、ソースコードと重複するうえ、コードが変わるたびに設計書も直す必要が生じます。設計書に書くべきなのは、「なぜそうするのか」という判断の根拠と、コードからは読み取りにくい業務上のルールです。

たとえば「メール送信を状態更新より先に行う」という順序は、コードを読めばわかりますが、「メール送信に失敗したら状態を更新しないため」という理由はコードからは読み取れません。コードが「何をしているか」を示し、設計書が「なぜそうしているか」を示すという分担を意識しましょう。

実装者の判断が分かれる部分は必ず書く

入力チェックの条件、エラー時の動作、境界値の扱い、処理の順序、外部サービスの失敗時の扱いなど、実装者によって解釈が分かれうる部分は、必ず明文化します。これらが曖昧だと、同じ機能でも実装者ごとに動作が変わり、テストで問題が発覚します。

判断の目安は、「この記述がなかったら、実装者は何を決めなければならないか」を考えることです。決めるべきことがすべて決まっている状態が、詳細設計書の完成の基準です。

チームの習熟度と開発手法に合わせる

経験豊富なチームで、コーディング規約や共通部品が整備されている場合は、設計書の記述を薄くしても品質を保てます。一方、経験の浅いメンバーが多い場合や、複数の会社が実装を分担する場合は、詳細に書く必要があります。

アジャイル開発では、詳細設計書を事前にすべて作成するのではなく、共通方針・API仕様・データ物理設計といった「後から変えにくい部分」を先に定め、個々の処理仕様は実装と並行して必要な範囲で記録する進め方が取られます。開発手法とチームの状況に応じて、記述の深さと作成のタイミングを決めることが現実的です。

図と表を活用する

処理の流れはシーケンス図やフローチャート、データの関係はER図、モジュールの関係は構成図で示すと、文章より正確に伝わります。項目の定義や条件の一覧は表形式にすると、抜け漏れの確認がしやすくなります。

文章で長く説明するより、図と表で構造を示し、文章は補足に使うことが、読みやすく保守しやすい設計書の作り方です。

【無料相談のご案内】 「開発会社から納品された詳細設計書の品質をどう確認すればよいか」「AIを含むシステムの設計・実装をどう進めるべきか」といった具体的なご相談は、無料の相談予約からお気軽にお問い合わせください。 ▶ 相談予約はこちら（https://nextscale.co.jp/consultation/）

テンプレートの活用とカスタマイズの方法

詳細設計書のテンプレートは、無料で公開されているものも多く、項目の抜け漏れを防ぐうえで役立ちます。ここでは、テンプレートの選び方と、プロジェクトの性質に合わせたカスタマイズの考え方、近年広がっている生成AIの活用について解説します。

公開されているテンプレート・サンプルの活用

詳細設計書のテンプレートは、Excelの表形式で処理仕様・テーブル定義・API仕様を管理するものが多く公開されています。また、IPAが教育用に公開しているソフトウェア設計の演習コンテンツには、ユースケース記述・シーケンス図・クラス図・画面レイアウトなどの記述例が含まれており、図の書き方の参考になります。

テンプレートを使う際は、自社のプロジェクトに不要な項目を削り、必要な項目を追加します。テンプレートの項目を埋めることが目的にならないよう、「実装者が必要とする情報は何か」から逆算することが大切です。

プロジェクトの種類に応じて重点を変える

• 業務システムの新規開発：画面の処理仕様・データ物理設計・バッチ仕様を中心に記載する。業務ルールの条件分岐を漏れなく書く
• 既存システムの改修：変更するモジュールと影響範囲（CRUD図で確認）を明確にし、変更前後の差分がわかる形式にする
• Webサービス・API開発：API仕様を中心に据え、リクエスト・レスポンス・エラー・認証・冪等性を詳細に定義する
• AIを含むシステム：参照データの抽出条件、AIサービスへの入出力、プロンプトの管理方法、個人情報の除去、失敗時の扱い、精度評価のためのログ項目を独立した項目として設計する

AIを含むシステムでは、処理の結果が確率的に変わるため、入力の作り方と出力の扱いを厳密に定め、評価のためのデータを記録する設計が必要です。サンプルの「AI回答案生成」の記入例を参考にしてください。

AI開発における設計の考え方や、開発会社の選び方については、AI受託開発の費用相場と開発会社の選び方の記事でも解説しています。

生成AIを設計書作成に活用する

近年は、生成AIを使って詳細設計書の下書きを作成したり、ソースコードから設計書を逆生成したりする取り組みが広がっています。基本設計書やAPI仕様を入力として処理仕様の草案を作らせる、既存コードを読み込ませて処理の流れを文書化させる、といった使い方です。

ただし、生成AIの出力には誤りや抜けが含まれるため、設計者による確認と修正は欠かせません。下書きの作成や整合性チェックを生成AIに任せ、判断と責任は設計者が持つという役割分担で活用すると、設計工程の効率を高められます。

詳細設計書の作成・確認で注意したいこと

詳細設計書は、作成にも確認にも専門知識が必要な文書です。ここでは、作成側と発注側の双方が押さえておきたい4つの注意点を解説します。

基本設計書との整合性を確認する

詳細設計を進めるなかで、基本設計では想定していなかった条件や制約が見つかることがあります。その場合、詳細設計書だけを修正して基本設計書との整合性が失われると、発注者が承認した内容と実際の動作がずれてしまいます。

対策は、詳細設計で判明した基本設計の変更点を一覧にし、発注側と合意したうえで基本設計書も更新することです。画面ID・テーブル名・要件IDで上位文書と対応付け、変更の影響を追跡できる状態を保ちましょう。

発注側は「確認すべき部分」を絞って確認する

発注側の担当者が詳細設計書のすべてを理解する必要はありませんが、業務ルールに関わる部分（入力チェックの条件、状態遷移、計算式、例外時の扱い）は、業務担当者でなければ正しさを判断できません。

開発会社に「業務判断が含まれる箇所」を明示してもらい、その部分を業務担当者が確認する体制をつくりましょう。技術的な妥当性は開発会社が、業務的な正しさは発注側が確認するという分担が、納品物の品質を高めます。

エラー処理と例外ケースを軽視しない

正常な流れの設計は丁寧に書かれていても、エラー時や例外ケースの設計が薄い設計書は少なくありません。しかし、運用開始後のトラブルの多くは、想定していなかった例外ケースで発生します。

外部サービスの失敗、同時操作、データの不整合、上限を超える入力など、「うまくいかない場合」の動作を正常系と同じ丁寧さで設計することが、品質の高いシステムにつながります。

実装後も設計書を更新し、資産として管理する

実装中の変更が設計書に反映されないと、運用開始後に設計書が信頼できない資料になり、保守や改修のたびにコードを読み解く必要が生じます。特にAIを含むシステムでは、プロンプトや参照条件の変更が頻繁に発生するため、更新の仕組みが重要です。

変更管理の手順に設計書の更新を組み込み、改訂履歴を残しましょう。詳細設計書を「実装のための一時的な文書」ではなく「システムを理解するための資産」として管理することで、内製化や将来の改修にも生かせます。

システム開発やAI活用の進め方については、NextScaleのコラム一覧でも関連記事を公開しています。

【無料相談のご案内】 詳細設計書の作成や確認に不安がある方、AIを組み込んだシステムの設計・開発を検討している方は、以下から無料の相談予約をご利用ください。要件定義から設計・実装・運用までを一貫してご支援します。 ▶ 相談予約はこちら（https://nextscale.co.jp/consultation/）

まとめ

詳細設計書は、基本設計で定めた画面・データ・機能を、プログラムとして実装できる粒度まで具体化した文書です。実装者への指示書であると同時に、単体テストの根拠、そして将来の保守担当者への引き継ぎ資料という役割を持ちます。基本設計が「何を」、詳細設計が「どのように」を定める、という違いを意識することが出発点です。

記載項目は、文書概要と設計方針、モジュール構成、画面の処理仕様、処理仕様、データベース物理設計、API仕様、バッチ処理仕様、共通処理・エラー処理・ログ設計、単体テスト仕様の9項目が柱になります。本記事では、問い合わせ対応支援システムを題材に、AI回答案生成の処理仕様を含む記入例を紹介しました。

「どこまで書くか」は、ソースコードを読めばわかることは書かず、実装者の判断が分かれる部分は必ず書くことを基準に、チームの習熟度と開発手法に合わせて決めます。エラー処理と例外ケースを正常系と同じ丁寧さで設計し、実装後も設計書を更新して資産として管理することで、品質の高いシステムと、内製化や将来の改修に耐える文書を残していきましょう。