設計書とは？目的と残すべき内容をわかりやすく解説

はじめに

設計書を作成しても、実装者から質問が続いたり、仕様変更の際に参照されなかったりすることがあります。

原因は、実装やテストに必要な判断が十分に残されていないことです。項目が埋まっていても、後の担当者が仕様や処理方法を推測しなければならない設計書は、十分に機能しません。

設計書は、設計上の判断を共有し、実装・テスト・変更を同じ前提で進めるための成果物です。

この記事で分かること

設計書を作る目的
設計書に残すべき内容
設計と設計書の違い
設計書をどこまで詳しく書くべきか

設計書とは

設計書とは、設計工程で決めた内容を、関係者が確認できる形で記録した成果物です。

設計では、要件を実現するための画面、処理、データ、権限、異常時の動作などを決めます。設計書には、その結果を実装やテストで利用できる形にして残します。

項目	役割
設計	要件を実現する方法を決める
設計書	設計で決めた内容を記録して共有する
設計レビュー	設計上の判断が妥当か確認する

設計書に残された判断が妥当かを確認する活動が設計レビューです。目的や確認観点は、「設計レビューとは？目的・進め方・確認観点をわかりやすく解説」で説明しています。

設計書を書くことと、設計することは同じではありません。
テンプレートへ情報を記入するだけではなく、必要な判断を行い、その内容を他の担当者が確認できる状態にすることが重要です。

設計書は何のために作るのか

設計書の目的は、大きく三つに整理できます。

関係者の認識を合わせる

システム開発には、設計者、実装者、テスト担当者、運用担当者など、複数の人が関わります。

画面の表示内容や処理条件を設計書で共有することで、担当者による認識の違いを防ぎます。

次の工程へ判断を引き継ぐ

実装者は設計書をもとにプログラムを作成し、テスト担当者は設計どおりに動作するかを確認します。

設計上の判断が残っていなければ、後の担当者が改めて仕様を推測しなければなりません。

設計書は、設計と実装・テストをつなぐ役割を持ちます。

変更時に影響を確認する

仕様変更は、対象の画面だけでなく、処理、データ、権限、テストにも影響します。

設計書に要素同士の関係が残されていれば、変更による影響範囲を確認しやすくなります。

設計書には何を残すべきか

設計書には、主に次の三つを残します。

設計で決めた内容

画面に表示する項目、処理の分担、使用するデータ、権限、正常時と異常時の動作など、実装やテストの基準となる決定を記録します。

検討中の案と決定事項を混在させず、採用した設計を明確にします。

判断の前提と制約

設計判断の前提となった条件を記録します。

検索できる期間、性能条件、外部システムの制約、利用者の権限など、後から変更するときに無視できない情報が対象です。

すべての検討過程を残す必要はありません。ただし、理由を知らずに変更すると問題が生じる設計については、採用した理由も簡潔に残します。

要素同士の関係

画面、処理、データなどを個別に記録するだけでは、システム全体のつながりが分かりません。

どの画面がどの処理を使用し、処理がどのデータを参照するのかを示すことで、実装や変更の影響を確認できるようにします。

注文履歴機能では何を残すのか

注文履歴機能を例にすると、設計書には次のような内容を残します。

対象	設計書へ残す内容	完成後の判定基準
閲覧権限	利用者、上司、管理者など、権限区分ごとの閲覧可能範囲	各権限で許可された注文履歴だけが表示される
検索期間	検索可能な期間と、範囲外を指定した場合の扱い	期間内は検索でき、範囲外は定義したエラーになる
検索結果	履歴が0件の場合と、データ取得に失敗した場合の扱い	0件とシステムエラーが異なる結果として表示される
表示項目	商品名、個数、注文日、金額の取得元と表示形式	指定したデータが指定した形式で表示される

設計書には、仕様を文章で繰り返すだけでなく、実装やテストの基準となる条件や関係を残します。

完成後の判定基準まで明確にすることで、設計どおりに実装されたかを確認しやすくなります。

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

設計書に必要な詳しさは、次の三つの観点で判断します。

必要な設計対象が網羅されているか

画面、処理、データ、権限、異常時の動作など、対象となる設計項目に抜け漏れがないことを確認します。

テンプレートやチェックリストは、抜け漏れを防ぐために有効です。

すべての項目を詳しく書く必要はありませんが、記載しない項目については、対象外であることが分かるようにします。

後工程の担当者が判断・確認できるか

実装者やテスト担当者が、仕様や処理方法を推測しなければならない状態では、設計内容が十分に具体化されていません。

権限の範囲、処理の責任分担、正常時と異常時の違いなど、担当者によって判断が分かれてはいけない内容を明確にします。

一方で、変数名や局所的なコードの書き方など、設計結果を変えない内容は実装者へ委ねます。

完成後に合否を判定できるか

設計書は、実装方法を伝えるだけでなく、完成したシステムが設計を満たしているか確認できる必要があります。

例えば「権限に応じて閲覧範囲を制限する」とだけ記載しても、どの利用者がどこまで閲覧できれば正しいのか判断できません。

権限区分ごとの閲覧範囲を定義することで、テスト時に設計どおりかを判定できます。

設計内容を読んでも完成後の合否を判断できない場合は、条件や期待する結果を追加する必要があります。

必要な項目を漏れなく扱い、後工程が判断でき、完成後に合否を確認できるところまで具体化することが重要です。

設計書を運用する際の注意点

テンプレートは抜け漏れ防止に使う

あらかじめ決められた項目を確認しながら記入する運用は、設計の抜け漏れを防ぐうえで有効です。

ただし、項目が埋まっていることだけで完了とは判断できません。

各項目について、実装やテストに必要な判断が明確になっているかを確認します。

設計判断と実装詳細を分ける

権限、処理の役割、データの関係、異常時の方針などは設計書へ残します。

変数名や一行ごとの処理など、実装者が設計の範囲内で選べる内容はコードへ委ねます。

後工程の担当者が勝手に決めてはいけない内容は設計書へ残し、局所的に選んでよい内容は実装へ委ねる、という区別が必要です。

設計上の判断を変更したら設計書も更新する

実装だけを変更すると、設計書が現在のシステムを表さなくなることがあります。

仕様、制約、処理構成などの設計判断を変更した場合は、関連する設計書を更新し、テストへの影響も確認します。

まとめ

設計書とは、設計工程で決めた内容を記録し、関係者へ共有するための成果物です。

関係者の認識を合わせ、設計上の判断を実装やテストへ引き継ぎ、変更時の影響を確認するために使用します。

設計書では、テンプレートやチェックリストによって必要な設計対象の抜け漏れを防ぎます。そのうえで、後工程の担当者が判断でき、完成後に設計どおりか判定できるところまで内容を具体化します。

細かく書くこと自体が目的ではありません。

設計として共有すべき判断と、実装者へ委ねる内容を区別し、後の工程で利用できる状態を作ることが重要です。

【テーマ一覧】