詳細設計書のテンプレートと書き方 記載項目8つと基本設計との違い、粒度の決め方を解説

詳細設計書を作ることになったものの、テンプレートを開いた時点で手が止まる。項目名は並んでいるが、そこに何をどこまで書けばいいのかが分からない。設計工程を初めて担当する方から、繰り返しいただくご相談です。

詳細設計書は、実装するエンジニアに向けて、システムの内部構造を具体的に示す文書です。読み手が開発者である点が、発注者やユーザーに向けた基本設計書と大きく異なります。

そして最も判断が難しいのが粒度です。書きすぎればコードと二重管理になって更新されなくなり、書かなすぎれば実装者ごとに解釈が分かれます。テンプレートを埋めるだけでは、この線引きは決まりません。

本記事では、詳細設計書テンプレートの基本構成、必ず入れる8つの記載項目、どこまで書くかの判断基準、作成手順5ステップ、そして陳腐化させないための運用までを順に整理します。

確認したいポイント	結論	詳細
詳細設計書とは何を書く文書？	実装者向けにシステムの内部構造を示す	基本設計書が外から見た動きを書くのに対し、内部の処理や構造を具体化する文書。
テンプレートの構成は？	共通部と機能ごとの個別部の2層	表紙と改訂履歴などの共通部に、機能単位の設計シートを追加していく形が基本になる。
最低限そろえる項目は？	概要・処理フロー・I/F・データ・例外	この5領域があれば実装に着手できる。画面や帳票は該当する機能のみ追加する。
どこまで詳しく書くべき？	コードを読めば分かることは書かない	判断基準は読み手が誰か。仕様の意図や例外条件など、コードに残らない情報を優先する。

この記事でわかること

• 詳細設計書と基本設計書の違いと、それぞれの読み手
• テンプレートの基本構成と、Excel・Word・Markdownの使い分け
• 詳細設計書に入れる8つの記載項目と、それぞれに書く内容
• 「どこまで書くか」を決める判断基準と、書かなくてよいものの見分け方
• 作成手順5ステップと、更新されず陳腐化させないための運用ルール

システム開発やAI導入の進め方を、支援内容とあわせて資料にまとめています。 ＞＞ 資料請求はこちら

詳細設計書とは実装者に向けて内部構造を示す文書

テンプレートの話に入る前に、この文書が誰のために存在するのかを押さえておく必要があります。読み手を取り違えると、書く内容も粒度もずれます。

ここでは基本設計書との違い、詳細設計書が担う役割、そしてテンプレートを使う理由を順に整理します。

基本設計書との違いは読み手と視点にある

基本設計書は、システムを外から見たときの動きを書く文書です。どんな画面があり、何を入力すると何が返ってくるのかを、専門知識のない発注者やユーザーが読んでも分かる形で記述します。外部設計書とも呼ばれます。

詳細設計書は、その動きを実現するための内部構造を書きます。処理をどう分割するのか、データをどう受け渡すのか、例外が起きたときにどう振る舞うのかを、実装するエンジニアに向けて具体化します。内部設計書という呼び方もされます。

同じ機能を扱っていても、答える問いが違います。基本設計書は「何ができるのか」に答え、詳細設計書は「どう作るのか」に答えます。この違いを意識しないと、詳細設計書に画面の説明ばかりが並び、実装に必要な情報が抜けます。

詳細設計書が担う3つの役割

詳細設計書は、書いて終わりの文書ではありません。開発の各段階で参照されます。

• 実装の指示書：担当者が変わっても同じものが作られる状態にする
• レビューの対象：コードを書く前に設計の誤りを見つける
• 保守の資料：数年後に改修する人が既存の仕組みを理解する

とくに3つ目の保守での利用は見落とされがちです。作った本人が異動や退職でいなくなった後、この文書だけが手がかりになります。

3つの役割のうち、どれを重視するかで書く内容が変わります。外部委託の実装指示書として使うなら細かく、社内の少人数チームで保守資料として残すなら要点だけ、という判断になります。

テンプレートを使うと判断の回数が減る

白紙から書き始めると、まず何を書く項目として立てるかを考えることになります。この作業自体に時間がかかり、担当者ごとに構成もばらつきます。

テンプレートがあれば、考えるのは中身だけです。項目が並んでいるため、埋められない箇所が空欄として残り、決まっていないことが可視化されます。

複数人で分担する場合、テンプレートの効果はさらに大きくなります。構成がそろっていれば、レビューする側も同じ順序で確認でき、見落としが減ります。

詳細設計書テンプレートの基本構成

詳細設計書のテンプレートは、案件全体で1つだけ使うものではありません。全体で共通する部分と、機能ごとに繰り返す部分の2層で考えると整理しやすくなります。

ここでは2層の中身と、ファイル形式の選び方を説明します。

共通部｜表紙・改訂履歴・用語定義

文書全体で1回だけ用意する部分です。文書名、対象システム、版数、作成者、承認者を表紙にまとめます。

改訂履歴は、日付、版数、変更内容、変更者を並べた表にします。詳細設計書は開発中に何度も更新されるため、いつ何が変わったのかを追えないと、古い版を見て実装するという事故が起きます。

用語定義には、社内独自の呼び方や略語をまとめます。同じ対象を業務部門と開発部門で違う名前で呼んでいることは珍しくありません。

個別部｜機能単位で繰り返す設計シート

機能ごとに同じ構成のシートを用意し、それを機能の数だけ複製していく部分です。ここが詳細設計書の本体になります。

1シートに複数の機能を詰め込むと、後から特定の機能を探しにくくなり、変更時の影響範囲も追いにくくなります。機能IDを振って1機能1シートを原則にすると、保守の段階で効いてきます。

画面、バッチ処理、外部連携インターフェースなど、種類ごとに必要な項目が変わります。種類別のシートを用意しておき、該当するものだけを使う形にすると無駄がありません。

Excel・Word・Markdownの使い分け

ファイル形式によって、書きやすさと管理のしやすさが変わります。3つの選択肢を比較すると次のようになります。

形式	得意な領域	向いている場面
Excel	項目の一覧管理、テーブル定義、I/F定義	機能数が多い、複数人で分担、SIの標準様式がある
Word	処理の意図や背景の説明、図の貼り込み	文章での説明が多い、納品物として提出する
Markdown	変更履歴の追跡、コードとの近接管理	内製開発、Gitでソースと一緒に管理したい

内製開発であればMarkdownをリポジトリに置き、コードの変更と同じ流れで更新する方法が有力です。設計書だけ別の場所にあると、更新が後回しになりやすくなります。

一方、発注先への納品物として提出する場合は、先方の指定様式に従うのが前提です。着手前に様式の有無を確認しておいてください。

設計工程の進め方や体制づくりについて、現状を伺ったうえでお手伝いします。 ＞＞ 相談予約はこちら

詳細設計書に入れる8つの記載項目

ここからは、個別部のシートに用意する項目を具体的に見ていきます。項目名だけでは何を書くか迷うため、それぞれ記入の観点をあわせて示します。

すべての機能に8項目すべてが必要なわけではありません。該当しない項目は削って構いません。

項目1｜機能概要と処理方式

この機能が何をするものかを数行でまとめます。あわせて、オンライン処理なのかバッチ処理なのか、同期か非同期かといった処理方式を明記します。

基本設計書のどの機能に対応するのかを、機能IDで示しておきます。対応関係が書かれていないと、基本設計が変わったときに影響範囲を特定できません。

項目2｜モジュール構成

機能をどの単位に分割するかを示します。クラス、関数、コンポーネントなど、使う言語や設計方針に応じた単位で並べます。

それぞれについて、責務、呼び出し関係、公開する引数と戻り値を書きます。オブジェクト指向言語であればクラス図、手続き型であればモジュール構造図といった形で図示すると理解が早くなります。

ここで書くべきは分割の結果ではなく、分割の方針です。なぜこの単位で分けたのかが1行あるだけで、後から改修する人が判断できます。

項目3｜処理フロー

処理の流れを順に示します。フローチャート、アクティビティ図、シーケンス図など、伝えたい内容に合う図法を選びます。

複数のモジュールやシステムをまたぐ処理はシーケンス図、条件分岐が多い処理はフローチャートが向いています。バッチ処理では、入力・処理・出力を並べた形式で書かれることもあります。

図だけで完結させず、判断が必要な分岐には文章で条件を添えてください。図の矢印だけでは、どういう場合にその経路を通るのかが読み取れません。

項目4｜入出力インターフェース定義

外部システムや他機能とやり取りするデータの仕様です。連携方式、データ形式、通信プロトコル、リクエストとレスポンスの項目を記載します。

項目ごとに、名称、型、桁数、必須か任意か、初期値を並べた表にします。文字コードや日付の形式といった細かな条件も、ここに書いておかないと実装時に確認が発生します。

インターフェース定義は、認識のずれが最も高くつく箇所です。連携先が別のチームや別の会社である場合は、この項目だけ先に合意を取っておく進め方が有効です。

項目5｜データ項目とテーブル定義

機能が読み書きするテーブルと、その項目を示します。テーブル名、カラム名、型、制約、インデックスを並べます。

更新系の処理では、どのタイミングで何を更新するのか、トランザクションの範囲はどこまでかを明記します。同時に複数の処理が走ったときの整合性は、コードを読んでも意図が分からない代表例です。

テーブル定義そのものは別のデータベース設計書にまとめ、詳細設計書からは参照する形にすると二重管理を避けられます。

項目6｜画面と帳票の詳細

画面を持つ機能では、レイアウト、表示項目、入力項目、ボタンの動作、入力チェックの条件を書きます。項目ごとに、必須か、桁数はいくつか、エラー時に何を表示するかを定義します。

帳票がある場合は、出力形式、レイアウト、印刷条件、改ページの規則を記載します。

基本設計書に画面レイアウトがある場合、詳細設計書ではそれを再掲せず、入力チェックや動作条件に絞ります。同じ図を2か所に置くと、片方だけが更新される事態になります。

項目7｜例外処理とエラー

異常が起きたときの振る舞いを書きます。想定するエラーの種類、判定条件、エラーコード、利用者への表示内容、ログに出す内容を定義します。

処理を中断するのか、続行して後で通知するのか、リトライするのかという方針も明記します。リトライする場合は回数と間隔まで決めておきます。

例外処理は、詳細設計書で最も抜けやすく、抜けた場合の影響が大きい項目です。正常系だけ書かれた設計書をもとに実装すると、異常時の挙動が担当者ごとにばらつきます。

項目8｜非機能に関わる実装条件

性能、セキュリティ、ログ、権限といった条件のうち、この機能の実装に関わるものを書きます。応答時間の目標、扱うデータ件数の上限、アクセス権限の判定方法などです。

全体の非機能要件は別文書にあるはずですが、機能ごとに落とし込まれていないと、実装者は自分が何を満たすべきか分かりません。該当する条件だけをここに転記します。

8項目の一覧と記載の観点

ここまでの項目を整理すると次のようになります。自社テンプレートの骨格として使えます。

項目	書く内容	記載の観点
1. 機能概要・処理方式	機能の目的、オンラインかバッチか	基本設計のIDと対応づける
2. モジュール構成	分割単位、責務、呼び出し関係	分割の方針を1行添える
3. 処理フロー	処理の順序と分岐	図と条件の文章を併記する
4. I/F定義	連携方式、データ形式、項目仕様	連携先と先に合意する
5. データ項目	読み書きするテーブルと更新範囲	整合性の意図を書く
6. 画面・帳票	表示項目、入力チェック、動作	基本設計と重複させない
7. 例外処理	エラー種別、判定条件、表示とログ	中断かリトライかを決める
8. 非機能条件	応答時間、権限、ログの要件	機能単位に落とし込む

「どこまで書くか」粒度の決め方

詳細設計書で最も判断に迷うのが、この粒度です。項目は埋まっているのに実装できない設計書も、細かすぎて誰も更新しない設計書も、原因は同じところにあります。

ここでは、判断の軸と具体的な線引きを示します。

判断の基準は「読み手が誰か」

粒度に唯一の正解はありません。決まるのは、この文書を誰が読んで実装するかによってです。

対象業務を知らない外部の開発者に渡すなら、前提や背景まで含めて書く必要があります。業務も既存システムも把握しているチーム内で使うなら、その説明は不要です。

着手前に「この設計書を読んで実装するのは誰か」を一度言語化してください。ここが決まれば、個々の項目で迷う場面は大きく減ります。

書かなくてよいもの

次のような内容は、詳細設計書に書く価値が低いと判断できます。

• ソースコードを読めばすぐ分かる処理の逐語的な説明
• 言語やフレームワークの標準的な作法
• 基本設計書に書かれている内容の再掲
• 変数名や1行単位のロジックなど、実装者の裁量に任せてよい部分

これらを書き込むと、文書量が増えるだけでなく、コードを変更するたびに設計書も直す必要が出てきます。二重管理になった文書は、遅かれ早かれ更新が止まります。

必ず書くべきもの

逆に、次の内容はコードに残らないため、文書で残す価値があります。

• なぜその設計を選んだのかという判断の理由
• 検討して採用しなかった案と、見送った理由
• 例外時の振る舞いと、その判断基準
• 他機能や外部システムへの影響範囲
• 暫定対応である箇所と、いつ見直すか

数年後に改修する担当者が知りたいのは、何をしているかではなく、なぜそうしたかです。コードを読めば動作は分かりますが、意図は書き残さない限り失われます。

粒度を決める3つの質問

判断に迷ったときは、次の3点を自問すると整理できます。

1つ目は「この記述がないと、実装者が確認しに来るか」です。来るなら書き、来ないなら不要です。

2つ目は「コードを見れば同じことが分かるか」です。分かるなら書きません。

3つ目は「変更されたとき、この記述も直す運用が回るか」です。回らないなら、そもそも書かないほうが安全です。更新されない設計書は、誤った情報として害になります。

設計から実装、社内定着まで、開発工程の伴走支援を行っています。 ＞＞ 相談予約はこちら

詳細設計書の作成手順5ステップ

テンプレートと項目がそろったら、次は作る順序です。いきなり個別部を埋め始めると、全体の抜けに気づけません。

ここでは、無理なく品質を保つための手順を5つに分けて説明します。

ステップ1｜基本設計書との対応を確認する

最初に、基本設計書の機能一覧をもとに、詳細設計が必要な機能を洗い出します。機能IDを振り、対応表を作ります。

この段階で、基本設計書に曖昧な記述が残っていれば、詳細設計に入る前に確認します。曖昧なまま詳細化すると、実装後に基本設計から作り直すことになります。

ステップ2｜テンプレートを案件に合わせて削る

汎用のテンプレートには、その案件に不要な項目が含まれています。バッチ処理がないのにバッチ設計の欄がある、帳票がないのに帳票の欄がある、といった状態です。

使わない項目は先に削ります。空欄が並んでいると、決まっていないのか不要なのかが判別できず、レビューで毎回確認が発生します。

逆に、その案件で特に重要な観点があれば項目を追加します。テンプレートは出発点であり、そのまま使うものではありません。

ステップ3｜機能単位で埋めていく

難易度の高い機能や、他機能への影響が大きい機能から着手します。ここで見つかる問題は、他の機能の設計にも波及するためです。

書きながら判断できない点が出てきたら、空欄にせず「未決」と理由を記入します。空欄は見落とされますが、未決と書かれていれば確認対象として残ります。

ステップ4｜レビューで確認する観点を決める

書き上がったら、実装担当者とテスト担当者にレビューしてもらいます。それぞれ見る観点が異なります。

実装担当者は「これで作れるか」、テスト担当者は「これで検証項目を作れるか」を見ます。テスト担当者が確認できない設計書は、例外条件や境界値の記述が不足しているサインです。

基本設計書との整合も確認します。機能IDの対応表があれば、この確認は短時間で終わります。

ステップ5｜版数と変更履歴を管理する

レビューを通過したら版数を確定し、改訂履歴に記録します。以降の変更は、日付・変更内容・理由・変更者をセットで残します。

理由を書く欄を必ず設けてください。何を変えたかだけでは、後から見たときに戻してよい変更かどうかを判断できません。

品質を上げる書き方の4つのポイント

同じ項目を埋めていても、書き方によって伝わり方は大きく変わります。実装時の問い合わせが多い設計書には、共通する特徴があります。

ここでは、解釈のずれを減らす具体的な書き方を4つ挙げます。

主語と条件を省略しない

「エラーの場合は処理を中断する」という記述では、何のエラーで、誰が中断を判断し、中断後にどうなるのかが読み取れません。

「入力チェックで必須項目が未入力の場合、登録処理を実行せず、該当項目の横にエラーメッセージを表示する」まで書きます。条件と動作と結果の3点がそろっていれば、解釈は分かれません。

図と文章の役割を分ける

図は全体の流れや構造を示すのに向いていますが、条件や例外を表すのは苦手です。逆に文章は、細かな条件を正確に伝えられますが、全体像は伝わりにくくなります。

図で流れを示し、分岐の条件と例外時の扱いは文章で補う。この役割分担にすると、どちらか一方に無理をさせずに済みます。

IDで基本設計とテストをつなぐ

機能、モジュール、インターフェース、エラーコードにIDを振ります。基本設計書の機能IDと、テスト仕様書のテストIDを対応づけられる状態にします。

要件が変わったときに、影響する設計書とテスト項目をIDで特定できることが、この管理の目的です。文書名や見出しで探す運用は、規模が大きくなると成立しません。

判断の理由を1行残す

設計上の選択をした箇所には、なぜそうしたのかを1行添えます。「性能要件を満たすため一括取得としている」「既存システムの制約により非同期にできない」といった内容です。

この1行があるかどうかで、数年後の改修時にかかる調査時間が変わります。理由が分からない実装は、触ってよいのか判断できず、そのまま残り続けます。

設計書の標準化や社内ドキュメント運用の見直しも支援しています。資料でご確認いただけます。 ＞＞ 資料請求はこちら

詳細設計書を陳腐化させないための運用

作った時点では正確だった設計書が、半年後には実物と合わなくなっている。多くの現場で起きている状態です。

原因は書き方ではなく運用にあります。ここでは、更新され続ける状態を保つための4点を挙げます。

更新のタイミングをルール化する

「気づいたときに直す」という運用では更新されません。仕様変更が確定した時点、実装が完了した時点など、更新するタイミングを決めておきます。

変更作業の完了条件に、設計書の更新を含めるのが確実な方法です。コードの修正と設計書の更新をセットで扱えば、片方だけが進む状態を防げます。

コードと二重管理になる部分を減らす

更新が止まる最大の要因は、書きすぎです。コードを変えるたびに設計書も直す必要がある構成にしていると、いずれ追いつかなくなります。

粒度を見直し、コードから自動生成できる部分は生成に任せます。設計書に残すのは、生成できない情報、つまり判断の理由と例外の扱いに絞ります。

外部の基準と照らして妥当性を確認する

自社の設計品質や工数が妥当な水準にあるかは、社内のデータだけでは判断できません。比較対象がないためです。

IPA（情報処理推進機構）は、5,546プロジェクトの定量データをもとに工数・工期・規模・生産性・信頼性などを分析した「ソフトウェア開発分析データ集2022」を公開しています。自社のプロジェクト計画が妥当かを確認する外部の比較材料として使えます。

なお同資料では、2020年版と比べて信頼性と生産性がともに低下する傾向が示されています。設計工程にかける時間を削ることが、後工程の品質にどう影響するかを考える材料になります。

検収と契約上の扱いを先に決めておく

外部委託の場合、詳細設計書が納品物に含まれるのか、含まれるとしてどの粒度で合格とするのかを、契約時に決めておきます。

ここが曖昧だと、検収の段階で「この内容では受け取れない」という議論が発生します。IPAが公開している情報システム・モデル取引・契約書（第二版）は、工程ごとの成果物や責任分担を整理する際の参考になります。

粒度の合意は、着手前に見本を1機能分だけ作って確認する方法が確実です。文章で条件を決めるより、実物を見せたほうが認識がそろいます。

生成AIで詳細設計書の作成を効率化する

詳細設計書の作成は、機能の数だけ同じ構成のシートを埋める繰り返し作業です。この性質は生成AIと相性がよく、下書きと点検の工程で時間を削減できます。

ここでは実務で効果が出やすい3つの使い方と、任せてはいけない範囲を整理します。

基本設計書から草案を作る

基本設計書の該当箇所とテンプレートの項目一覧を渡し、詳細設計の草案を作らせます。処理フローの叩き台や、入力チェック項目の候補を出させる使い方です。

指示文には、出力する項目、記述の粒度、そして「基本設計書に書かれていない仕様を追加しない」という条件を入れます。この条件を省くと、確認していない仕様がもっともらしく書かれます。

担当者の作業は、草案を読んで判断し、設計方針を反映することになります。白紙から書くより着手が早くなります。

抜け漏れと矛盾を点検する

書き上げた設計書を渡し、「例外処理が書かれていない機能を挙げる」「入力チェックの条件が定義されていない項目を指摘する」といった点検を依頼します。

複数の機能シート間で、同じテーブルへの更新方針が食い違っていないかといった横断的な確認にも使えます。書いた本人には前提が入るため、機械的な照合のほうが見落としを拾えます。

既存コードから設計書を起こす

設計書が残っていない既存システムを改修する場合、ソースコードを渡して処理の流れやモジュール構成を文書化させる使い方があります。

ただし、出てきた内容は動作の説明であり、なぜそうなっているかという意図は含まれません。当時の判断理由は、コードにも残っていないため復元できないと考えてください。現行仕様の把握までを目的にすると効果が出ます。

なお、ソースコードを外部サービスに入力してよいかは、契約と社内規程で事前に確認が必要です。

生成AIに任せてはいけない範囲

設計方針の決定は人が行います。どのモジュール分割にするか、性能とわかりやすさのどちらを優先するかは、システムの特性と運用体制を踏まえた判断であり、AIには材料がありません。

判断の理由を書く部分も同様です。この記事で挙げたとおり、理由の記述は詳細設計書で最も価値が高い部分であり、実際に検討した人にしか書けません。

業務での生成AI活用を広く整理した内容は、業務効率化アイデア55選｜部門別30＋AI15＋明日から3つで成果を出す方法でも紹介しています。他のコラム記事はネクストスケールのブログ一覧からご覧いただけます。

まとめ

詳細設計書は、実装するエンジニアに向けてシステムの内部構造を示す文書です。外から見た動きを書く基本設計書とは、読み手も答える問いも異なります。

テンプレートは、表紙や改訂履歴などの共通部と、機能ごとに繰り返す個別部の2層で構成します。記載項目は、機能概要、モジュール構成、処理フロー、I/F定義、データ項目、画面・帳票、例外処理、非機能条件の8つです。

最も判断が難しい粒度については、読み手が誰かを基準に決めます。コードを読めば分かることは書かず、判断の理由や例外の扱いといったコードに残らない情報を優先します。

作成手順は、基本設計との対応確認、テンプレートの削り込み、機能単位の記入、レビュー、版数管理の5ステップです。書き方では、条件と動作と結果をそろえること、図と文章の役割を分けること、IDでつなぐこと、理由を1行残すことが効きます。

そして、作った後に更新され続ける運用を設計してください。更新が止まった設計書は、参照されないだけでなく、誤った情報として判断を誤らせます。書きすぎないことが、結果として文書を生かします。

システム開発やAI導入を、どこから・どの順番で進めるべきか。現状を伺ったうえで、具体的な進め方をご提案します。 ＞＞ 相談予約はこちら