詳細設計書の書き方 成果物の種類と図の使い分け、伝わる記述のコツを例文つきで解説

詳細設計書を書き上げて提出したのに、実装が始まると仕様の問い合わせが次々と届く。項目は埋めたはずなのに、読んだ人が同じものを思い浮かべていない。設計工程で最もよく起きる状態です。

原因は項目の抜けではなく、多くの場合、記述の仕方にあります。条件が省略されている、主語が書かれていない、図はあるが分岐の条件がない。どれも「書いた本人には分かる」記述です。

詳細設計書の読み手は、業務背景を知らない実装者です。書き手の頭の中を前提にした記述は、そのまま解釈のずれになります。

本記事では、詳細設計で作る成果物の種類、クラス図やシーケンス図といった図法の使い分け、そして伝わる記述に直すための書き方を、悪い例と良い例を並べながら整理します。あわせて手順とレビュー観点も解説します。

確認したいポイント	結論	詳細
詳細設計書は何を書く文書？	実装者に向けて内部の作り方を示す	基本設計が「何を作るか」に答えるのに対し、詳細設計は「どう作るか」に答える。
どんな成果物を作る？	構造・振る舞い・画面/データの3系統	クラス図やシーケンス図、画面設計書、データベース設計書などから必要なものを選ぶ。
図はどう使い分ける？	構造系と振る舞い系で目的が違う	静的な関係はクラス図、時間の流れはシーケンス図、状態の変化は状態遷移図で表す。
伝わらない記述の原因は？	条件・主語・例外の省略	「エラー時は中断」では判断できない。条件と動作と結果の3点をそろえて書く。

この記事でわかること

• 詳細設計書が答えるべき問いと、基本設計書・コーディング仕様書との違い
• 詳細設計で作成する成果物の種類と、案件に応じた取捨選択の考え方
• クラス図・シーケンス図・状態遷移図など、図法の使い分けの基準
• 伝わらない記述を直す5つの書き方（悪い例と良い例の対比つき）
• 作成手順5ステップと、実装者・テスト・保守の3観点によるレビューの進め方

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

詳細設計書の書き方は「読み手が実装者」から逆算する

書き方の話に入る前に、この文書が答えるべき問いを確認しておきます。ここがずれていると、どれだけ丁寧に書いても実装の役に立ちません。

ここでは基本設計書との違い、詳細設計に含まれる2種類の作業、そして混同されがちなコーディング仕様書との線引きを整理します。

基本設計書との違いは答える問いにある

基本設計書は、システムを外から見たときの振る舞いを書きます。どんな画面があり、何を入力すると何が返ってくるのか。読み手は発注者やユーザーであり、専門知識がなくても理解できる記述が求められます。

詳細設計書は、それを実現するための内部の作り方を書きます。処理をどう分割し、データをどう受け渡し、異常時にどう振る舞うのか。読み手は実装するエンジニアです。

基本設計が「何を（What）作るか」に答え、詳細設計が「どのように（How）作るか」に答える。この違いを押さえると、詳細設計書に画面の説明ばかりが並ぶ状態を避けられます。

詳細設計には「決める作業」と「書く作業」がある

詳細設計と一言で呼ばれていますが、実際には性質の異なる2つの作業が含まれています。

1つ目は決める作業です。処理をどの単位に分割するか、どのデータ構造を使うか、例外が起きたときにどう扱うかを検討して決定します。設計そのものにあたる部分です。

2つ目は書く作業です。決めた内容を、他人が読んで同じものを作れる形に記述します。図を選び、条件を言葉にする作業です。

書き方でつまずいていると思っている場面の多くは、実は決めきれていないことが原因です。書けない箇所が出てきたら、記述の巧拙を疑う前に、その点が決まっているかを確認してください。

コーディング仕様書とは目的が違う

詳細設計書と混同されやすいのが、コーディング仕様書です。こちらはプログラムの処理を1行単位で日本語に置き換えたもので、実装者の裁量をほとんど残しません。

海外への開発委託などで使われてきた形式ですが、作成コストが高いわりに得られる品質が見合わないため、現在は作られる場面が限られています。

詳細設計書はコードの日本語訳ではありません。変数名や1行単位のロジックは実装者に任せ、分割の方針や例外の扱いといった判断が必要な部分を記述します。

詳細設計で作成する成果物の種類

詳細設計書は1つのファイルとは限りません。実際には複数の成果物の集まりであり、案件の性質によって必要なものが変わります。

ここでは成果物を3系統に分けて整理し、最後に一覧としてまとめます。

構造を示す成果物

システムを構成する部品と、その関係を示すものです。クラス図、モジュール構成図、パッケージ図、コンポーネント図などがこれにあたります。

どの単位で処理を分割し、それぞれがどんな責務を持ち、どこから呼ばれるのかを表現します。実装に入る前に、全体の見取り図として共有します。

構造系の成果物は、後から変えると影響が広い部分です。振る舞いの記述より先に固めておくと、手戻りを減らせます。

振る舞いを示す成果物

処理がどう進むかを示すものです。シーケンス図、アクティビティ図、フローチャート、状態遷移図が代表的です。

構造が「何があるか」を示すのに対し、振る舞いは「どう動くか」を示します。同じ機能でも、複数のモジュールをまたぐやり取りと、条件分岐の多い処理とでは、適した図が変わります。

振る舞いの成果物には、必ず異常時の経路も含めてください。正常系だけを描いた図は、実装時にそのまま質問の山になります。

画面・データ・外部連携の成果物

画面設計書には、レイアウト、表示項目、入力項目、入力チェックの条件、ボタンの動作を記載します。基本設計にレイアウトがある場合は、詳細設計では動作条件に絞ります。

データベース設計書には、テーブル定義、カラムの型と制約、インデックス、更新のタイミングを書きます。インターフェース定義書には、連携方式、データ形式、項目仕様、通信条件を記載します。

外部連携の仕様は、相手方との合意が必要なため最初に着手します。自分たちだけで決められない項目を後回しにすると、日程が崩れます。

成果物の一覧と選び方

代表的な成果物を整理すると次のようになります。すべてを作る必要はなく、案件に応じて選びます。

系統	主な成果物	作成すべき場面
構造	クラス図、モジュール構成図	処理の分割方針を共有したいとき
振る舞い	シーケンス図、フローチャート	複数処理の連携や分岐が複雑なとき
振る舞い	状態遷移図	ステータスが変化する対象を扱うとき
画面	画面設計書、画面遷移図	利用者が操作する機能があるとき
データ	データベース設計書、CRUD図	データの読み書きが複数機能にまたがるとき
連携	インターフェース定義書	外部システムや他チームと接続するとき

判断の基準は「この図がないと実装者が確認しに来るか」です。来ないなら作りません。成果物の数を増やすことが目的ではありません。

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

図の使い分けは「構造」と「振る舞い」で判断する

詳細設計で使える図は多く、どれを選ぶかで迷いがちです。ただし、選択の軸は単純で、示したいものが構造か振る舞いかで大きく分かれます。

ここでは代表的な4種類の図について、向いている場面と書くときの注意点を説明します。

図法は標準として体系が定められている

ソフトウェア設計で使われる図の多くは、UML（統一モデリング言語）として体系化されています。標準化団体であるOMGが仕様を管理しており、最新の正式版はUML 2.5.1（2017年12月公開）です。

UMLの図は、構造を表す図と振る舞いを表す図に大きく分類されています。全部を覚える必要はなく、実務で使うのは数種類に限られます。

重要なのは、社内で使う図法をそろえることです。同じ内容が案件ごとに違う書き方をされていると、読む側の負担が増えます。

クラス図｜静的な関係と責務を示す

クラスやモジュールと、その間の関係を示す図です。属性、メソッド、継承や参照の関係を表現します。

オブジェクト指向言語で開発する場合の中心的な成果物になります。手続き型の言語であれば、モジュール構造図で同じ役割を果たします。

クラス図では、関連線に多重度を必ず書いてください。1対1なのか1対多なのかが書かれていないと、データ構造の実装が分かれます。

シーケンス図｜時間の流れに沿った呼び出しを示す

複数のモジュールやシステムが、どの順番でやり取りするかを示す図です。縦軸が時間、横軸が登場する要素になります。

外部システムとの連携、非同期処理、複数の画面をまたぐ処理など、関係する要素が3つ以上ある処理で効果を発揮します。登場人物が2つしかない処理には過剰です。

エラー応答が返るケースも別の経路として描きます。正常系だけの図は、異常時の設計が未検討であるサインでもあります。

アクティビティ図・フローチャート｜分岐の多い処理を示す

処理の流れと条件分岐を示す図です。バッチ処理や、判定条件が複数ある業務ロジックに向いています。

分岐の矢印には必ず条件を書き添えてください。「はい／いいえ」だけでは、何を判定しているのかが読み取れません。

条件が3つ以上組み合わさる場合は、図では表現しきれなくなります。その場合は次に挙げる表形式に切り替えます。

状態遷移図｜ステータスが変わる対象を示す

申請、注文、契約など、状態を持つ対象の変化を示す図です。どの状態からどの状態へ、どんな操作で移るのかを表現します。

状態の数だけでなく、遷移しない組み合わせを明示することが重要です。「却下から承認済みへは戻せない」といった制約が書かれていないと、実装で許可されてしまいます。

状態と操作を縦横に並べた表にすると、抜けを機械的に確認できます。図と表の両方を用意する価値がある領域です。

図の選び方の目安

判断に迷ったときは、示したい内容から逆算します。

示したいこと	適した図	書くときの注意
部品の関係と責務	クラス図、モジュール構成図	多重度と責務を明記する
やり取りの順序	シーケンス図	異常応答の経路も描く
処理の流れと分岐	アクティビティ図、フローチャート	分岐に条件を書き添える
状態の変化	状態遷移図、遷移表	遷移しない組み合わせを示す
複雑な条件の組み合わせ	条件と結果の対応表	条件の全組み合わせを埋める

伝わる記述にするための5つの書き方

ここからが本題です。図と項目がそろっていても、文章の書き方次第で解釈は分かれます。実装時の問い合わせが多い設計書には、共通する記述の癖があります。

悪い例と良い例を並べながら、5つのポイントを見ていきます。

書き方1｜条件・動作・結果の3点をそろえる

最も多い問題が、この3点のどれかが欠けている記述です。

悪い例：エラーの場合は処理を中断する。

この記述では、何のエラーなのか、中断した後どうなるのか、利用者に何が見えるのかが分かりません。実装者は必ず確認しに来ます。

良い例：登録ボタン押下時、必須項目が未入力の場合は登録処理を実行せず、該当項目の直下にエラーメッセージ「入力してください」を赤字で表示する。入力内容は保持する。

条件（いつ）、動作（何をする／しない）、結果（どうなる）の3点がそろっていれば、解釈は分かれません。書き終えたら、この3点が含まれているかを確認する習慣をつけてください。

書き方2｜主語を省略しない

日本語は主語を省略できるため、設計書でも自然に消えます。しかし誰が実行するのかは、実装では必ず決める必要があります。

悪い例：承認された後、通知を送信する。

承認するのは人なのかシステムなのか、通知を送るのはどのモジュールなのかが不明です。

良い例：部門長が承認画面で承認すると、通知バッチが翌営業日9時に申請者へメールを送信する。

主語が書けない箇所は、運用が決まっていない可能性があります。書けないと気づいた時点で、確認事項として記録してください。

書き方3｜形容詞を数値と条件に置き換える

「速い」「大量の」「適切に」といった形容詞は、人によって基準が異なります。設計書に残ると、完成したかどうかの判定ができません。

悪い例：大量データの場合は分割して処理する。

良い例：対象件数が10,000件を超える場合、1,000件単位に分割して処理する。分割単位は設定ファイルで変更可能とする。

判定できない記述は、テスト項目も作れません。テスト担当者がその記述から検証手順を書けるかどうかを、判断の目安にしてください。

書き方4｜複雑な条件は文章ではなく表で書く

条件が3つ以上組み合わさると、文章では正確に表現できなくなります。「かつ」「または」が混ざった長文は、読み手ごとに解釈が変わります。

この場合は、条件を列に、結果を行に並べた表に切り替えます。条件の組み合わせをすべて行として書き出せば、考慮していない組み合わせが空欄として浮かび上がります。

文章で書いていたときには気づかなかった抜けが、表にした途端に見つかることは珍しくありません。

書き方5｜例外を正常系と同じ密度で書く

正常系は具体的に書かれているのに、異常系は「エラー処理を行う」の1行で終わっている。詳細設計書で最もよく見る不均衡です。

想定するエラーごとに、判定条件、エラーコード、利用者への表示、ログに残す内容、処理を続行するか中断するかを書きます。リトライする場合は回数と間隔まで決めます。

実装で判断に迷う場面のほとんどは異常系です。正常系を1行削ってでも、異常系に記述を割く価値があります。

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

詳細設計書を書く手順5ステップ

書き方が分かっても、順序を間違えると手戻りが発生します。いきなり文章を書き始めると、構造が変わったときに書き直しになります。

ここでは、無駄なく進めるための手順を5つに分けて説明します。

ステップ1｜基本設計を読み込んで不明点を潰す

最初に基本設計書を読み、矛盾や曖昧な記述がないかを確認します。この段階で見つかった疑問は、詳細設計に入る前に解消します。

曖昧なまま詳細化すると、実装後に基本設計から作り直すことになります。手戻りの規模が段違いになるため、ここに時間をかける価値があります。

ステップ2｜作る成果物の種類を決める

機能ごとに、どの成果物が必要かを決めます。画面のない機能に画面設計書は不要ですし、単純な処理にシーケンス図は過剰です。

判断の基準は、前述のとおり「この成果物がないと実装者が確認しに来るか」です。成果物の種類を先に決めておくと、書きながら迷う時間がなくなります。

ステップ3｜構造から振る舞い、記述の順で作る

最初に処理の分割方針を決め、構造系の図を作ります。次にその構造をもとに、振る舞いの図を描きます。最後に、図で表現しきれない条件を文章で補います。

この順序を守ると、構造が変わったときの影響が下流に限定されます。逆に文章から書き始めると、分割方針が変わるたびに全文を直すことになります。

ステップ4｜例外と境界値を洗い出す

正常系が固まったら、異常系を検討します。入力が想定外だった場合、外部システムが応答しない場合、同時に更新された場合をそれぞれ検討します。

境界値もここで決めます。上限は何件か、その値を含むのか含まないのか、超えたときにどうするのかを明記します。

この工程を独立したステップとして立てることが重要です。正常系を書きながら思いついた分だけ書く進め方では、必ず抜けます。

異常時の観点を洗い出す材料として、公的資料を活用する方法もあります。IPA（情報処理推進機構）は、設計工程に関する公開資料をリンク集として整理しており、リスク分析手法や設計の見える化に関する資料を無償で参照できます。

ステップ5｜レビューを受けて確定する

書き上がったら、実装担当者とテスト担当者にレビューしてもらいます。指摘を反映し、版数を確定して改訂履歴に記録します。

レビューで出た確認事項のうち、その場で決まらなかったものは「未決」として理由とともに残します。空欄にすると見落とされますが、未決と書かれていれば追跡できます。

レビューで確認する3つの観点

レビューは、参加者が同じ目線で読むと効果が下がります。役割ごとに見る観点を分けると、見つかる問題の種類が増えます。

ここでは3つの観点と、指摘の出し方を整理します。

実装者の観点｜これで作れるか

実装担当者は、この記述で迷わず作れるかを見ます。確認したくなった箇所がそのまま指摘になります。

レビュー中に質問が出た箇所は、記述が不足している証拠です。その場で口頭で答えて終わりにせず、設計書に反映してください。口頭の回答は記録に残りません。

テスト担当者の観点｜これで検証項目を作れるか

テスト担当者は、記述から検証手順と期待結果を書けるかを見ます。判定できない記述はここで見つかります。

テスト担当者が検証項目を作れない設計書は、境界値や例外条件の記述が不足しています。この観点でのレビューは、書き方3と書き方5の点検になります。

保守担当者の観点｜数年後に読んで分かるか

将来の改修担当者を想定して読み、なぜその設計にしたのかが分かるかを見ます。動作は書かれていても、意図が書かれていない箇所は多くあります。

「性能要件を満たすため一括取得としている」「既存システムの制約により非同期にできない」といった1行を残してください。理由が分からない実装は、触ってよいか判断できず、そのまま残り続けます。

指摘は「どう直すか」まで書く

レビューの指摘が「分かりにくい」で止まると、書き手は直しようがありません。何が読み取れなかったのか、どう書けば伝わるかまで含めて指摘します。

指摘の型を決めておくと精度が上がります。「該当箇所」「読み取れなかった内容」「想定される解釈のずれ」の3点をそろえる形が使いやすい形式です。

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

書き方でつまずきやすい4つのパターン

実際の設計書を読んでいると、繰り返し現れる失敗の型があります。どれも書き手に悪意はなく、良かれと思って書いた結果です。

ここでは4つのパターンと、その対処を挙げます。

コードの日本語訳になっている

処理を1行ずつ日本語に置き換えた記述です。丁寧に見えますが、コードを読めば分かる内容であり、変更のたびに設計書も直す必要が生じます。

この形式は、二重管理になって更新が止まる典型例です。書くのは分割の方針と例外の扱いに絞り、処理の逐語的な説明は省きます。

基本設計の内容を再掲している

画面レイアウトや機能一覧を、基本設計書からそのまま転記している状態です。文書量は増えますが、実装に必要な情報は増えていません。

同じ内容が2か所にあると、片方だけが更新されて食い違います。参照する形にとどめ、詳細設計では動作条件や例外に記述を割いてください。

図はあるが条件が書かれていない

きれいなフローチャートが載っているのに、分岐の矢印に条件がない。図を描いた本人は分かっていますが、読み手には判定基準が伝わりません。

図は流れを示す道具であり、条件を表現するのは苦手です。分岐条件と例外時の扱いは、図に添える形で文章として書きます。

用語が文書内でぶれている

同じ対象を「申請」「リクエスト」「依頼」と書き分けてしまい、読み手が別のものと解釈する状態です。複数人で分担すると特に起きやすくなります。

対処は、用語集を先に作って共有することです。表記ゆれの確認は機械的にできる作業なので、レビュー前に一括で点検してください。

生成AIを使った下書きと記述の点検

詳細設計書の作成は、機能の数だけ同じ形式の記述を繰り返す作業です。この性質は生成AIと相性がよく、下書きと点検の工程で時間を削減できます。

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

基本設計から記述の草案を作る

基本設計書の該当箇所と、記述の型（条件・動作・結果の3点をそろえる形式）を指示して、詳細設計の草案を作らせます。入力チェック項目や画面の動作条件は、候補を出させると着手が早くなります。

指示文には「基本設計書に書かれていない仕様を追加しない」という条件を必ず入れてください。この条件を省くと、確認していない仕様がもっともらしく書かれます。

曖昧な表現を洗い出す

書き上げた設計書を渡し、「判定できない形容詞を含む記述を挙げる」「主語が書かれていない文を指摘する」といった点検を依頼します。

本記事で挙げた5つの書き方を指示文に含め、その観点で不足を挙げさせると精度が上がります。書いた本人には前提が入るため、機械的な照合のほうが見落としを拾えます。

表記ゆれの検出も同様に任せられます。用語集を渡して、そこから外れた表現を列挙させる使い方が有効です。

図をテキスト形式で下書きする

処理の説明を渡して、MermaidやPlantUMLといったテキスト記法でシーケンス図やフローチャートの下書きを生成させる方法があります。

テキストで管理できる形式にしておくと、変更履歴を追いやすく、レビューでの指摘も反映しやすくなります。作図ツールで一から描くより、修正のコストが下がります。

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

設計方針の決定は人が行います。どの単位で処理を分割するか、性能とわかりやすさのどちらを優先するかは、システムの特性と運用体制を踏まえた判断です。

判断の理由を書く部分も同様です。保守担当者にとって最も価値がある記述であり、実際に検討した人にしか書けません。

また、ソースコードや顧客情報を外部サービスに入力してよいかは、契約と社内規程で事前に確認が必要です。入力内容が学習に使われない契約かどうかもあわせて確認してください。

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

まとめ

詳細設計書の書き方は、読み手が実装者であることから逆算して決まります。基本設計が「何を作るか」に答えるのに対し、詳細設計は「どう作るか」に答える文書です。

作成する成果物は、構造を示すもの、振る舞いを示すもの、画面・データ・連携に関するものの3系統に分かれます。すべてを作るのではなく、それがないと実装者が確認しに来るかを基準に選びます。

図の使い分けは、部品の関係ならクラス図、やり取りの順序ならシーケンス図、分岐ならフローチャート、状態の変化なら状態遷移図が目安です。条件が3つ以上組み合わさる場合は、図ではなく表に切り替えます。

記述で押さえるのは、条件と動作と結果の3点をそろえる、主語を省略しない、形容詞を数値に置き換える、複雑な条件は表で書く、例外を正常系と同じ密度で書く、の5点です。

手順は、基本設計の読み込み、成果物の選定、構造から記述への展開、例外と境界値の洗い出し、レビューの5ステップ。レビューは実装・テスト・保守の3観点で分担すると、見つかる問題の種類が増えます。

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