詳細設計書とは？
詳細設計書とは、要件定義書や基本設計書で決めた内容をもとに、システムを実際に開発するための具体的な仕様を整理した文書です。mysignプロジェクトでは、契約書ひな形ごとにSEO解説記事も作成する方針が定められています。
詳細設計書が必要となるケース
- Webシステムや業務システムを新規開発する場合
- スマートフォンアプリを開発する場合
- 既存システムを改修・機能追加する場合
- 複数の開発者や外注先が関与する場合
- 保守・運用を見据えて仕様を明文化したい場合
詳細設計書に記載すべき主な項目
詳細設計書には、開発者が迷わず実装できるよう、次のような項目を整理します。
- 対象システムの概要
- 開発環境
- 画面詳細設計
- 機能詳細設計
- 処理フロー
- 入力チェック
- データベース設計
- API設計
- 帳票・ファイル設計
- エラー処理
- ログ設計
- 権限設計
- テスト観点
詳細設計書と基本設計書の違い
基本設計書は、利用者や発注者にも分かるように、システム全体の仕様や画面構成、業務フローを整理する文書です。一方、詳細設計書は、開発者が実装するための具体的な処理内容、データ項目、入力チェック、エラー処理、API仕様などを細かく定める文書です。つまり、基本設計書が「何を作るか」を整理する文書であるのに対し、詳細設計書は「どのように作るか」を具体化する文書といえます。
詳細設計書の条項・項目ごとの解説
1. 対象システム
対象システムの名称、プロジェクト名、バージョン、作成日、作成者などを記載します。複数のシステムや機能を並行して開発する場合、どの範囲を対象とする設計書なのかを明確にすることが重要です。
2. 開発環境
OS、開発言語、フレームワーク、データベース、サーバー環境、ミドルウェアなどを記載します。開発環境が曖昧なままだと、実装者ごとに動作環境が異なり、不具合や手戻りが発生しやすくなります。
3. 画面詳細設計
画面ID、画面名称、表示項目、入力項目、ボタン、画面遷移などを整理します。特に入力項目については、必須・任意、文字数、入力形式、エラーメッセージまで記載しておくと、実装時の判断がぶれにくくなります。
4. 機能詳細設計
各機能について、処理開始条件、処理終了条件、入力値、出力値、使用テーブル、使用APIなどを記載します。機能単位で詳細を整理することで、開発担当者が分担して作業しやすくなります。
5. 処理フロー
通常処理と例外処理を分けて記載します。たとえば、ログイン処理であれば、ID・パスワード入力、認証、成功時の遷移、失敗時のエラー表示などを順番に整理します。
6. 入力チェック
必須チェック、文字数チェック、形式チェック、重複チェックなどを記載します。入力チェックは、システムの品質やセキュリティに直結するため、詳細設計書で明確にしておくべき重要項目です。
7. データベース設計
テーブル名、カラム名、データ型、主キー、NULL可否、初期値、説明などを記載します。データベース設計が不十分だと、後から仕様変更やデータ不整合が発生しやすくなります。
8. API設計
外部サービスや他システムと連携する場合は、API名称、URL、HTTPメソッド、認証方式、リクエスト、レスポンス、エラーコードなどを記載します。
9. エラー処理
エラーコード、エラー内容、利用者に表示するメッセージ、対応方法を整理します。エラー処理を明確にしておくことで、利用者への案内や保守対応がスムーズになります。
10. ログ設計
操作ログ、エラーログ、システムログ、APIログ、認証ログなど、取得するログの種類と項目を定めます。ログは、障害調査、不正アクセス対策、運用改善に役立ちます。
11. 権限設計
管理者、一般利用者、閲覧者などの権限ごとに、閲覧、登録、更新、削除の可否を整理します。権限設計は、情報漏えいや誤操作を防止するために欠かせません。
12. テスト観点
単体テスト、結合テスト、異常系テスト、性能テスト、セキュリティテストなど、確認すべき観点を記載します。詳細設計書の段階でテスト観点を整理しておくと、品質管理がしやすくなります。
詳細設計書を作成するメリット
- 開発者間の認識相違を防げる
- 実装内容が明確になり、手戻りを減らせる
- テスト項目を整理しやすくなる
- 保守・改修時に仕様を確認しやすくなる
- 外注先との責任範囲を明確にしやすい
詳細設計書を作成する際の注意点
- 要件定義書・基本設計書との整合性を確認する
- 実装担当者が理解できる粒度で記載する
- 画面・機能・データベースの対応関係を明確にする
- 例外処理やエラー処理を省略しない
- 変更履歴を残し、最新版を管理する
詳細設計書と契約実務上の関係
システム開発契約では、詳細設計書が成果物の内容や検収基準に関係することがあります。契約書上で「成果物」「納品物」「検収対象」として詳細設計書を位置付ける場合、完成基準や承認方法を明確にしておくことが重要です。また、詳細設計書の内容が曖昧なままだと、発注者は「想定していた機能と違う」と感じ、受注者は「仕様どおりに作った」と主張するなど、トラブルにつながる可能性があります。そのため、詳細設計書は単なる開発資料ではなく、開発範囲や責任分担を明確にするための重要な証拠資料としても機能します。
詳細設計書の作成時に確認すべきポイント
- 画面ごとの入力項目・表示項目が整理されているか
- 各機能の処理内容が具体的に記載されているか
- 正常系だけでなく異常系の処理も定められているか
- データベース項目と画面項目に矛盾がないか
- API連携時のエラー処理が明確か
- 権限ごとの操作範囲が整理されているか
- テストで確認すべき観点が反映されているか
まとめ
詳細設計書は、システム開発において実装内容を具体化するための重要な文書です。画面、機能、処理フロー、データベース、API、エラー処理、ログ、権限、テスト観点などを整理することで、開発者間の認識相違を防ぎ、品質の高いシステム開発につなげることができます。特に、外部の開発会社やフリーランスに開発を依頼する場合、詳細設計書を作成しておくことで、作業範囲や成果物の内容を明確にしやすくなります。詳細設計書は、開発現場のためだけでなく、契約上のトラブルを防ぐためにも役立つ実務的な文書です。
