アプリの設計書は、決まったページ数を埋めるための資料ではありません。
要件、画面、データ、外部連携、例外、テストの対応関係を残し、変更時に影響する場所を追えるようにする道具です。
テンプレートは項目漏れの確認に使い、案件に存在しない章を形式だけで増やさないでください。
アプリ開発の目的に合う相談先は、外注と学習を目的別に分けた相談ガイドにまとめています。
| 設計資料 | 主な読者 | 答える問い |
|---|---|---|
| 全体構成図 | 発注者、開発、運用 | 端末、API、DB、外部サービスはどうつながるか |
| 画面、遷移 | デザイン、開発、テスト | 利用者はどの順で操作するか |
| データ設計 | 開発、分析、運用 | 何を一件として保存するか |
| API、連携 | 開発、連携先 | 認証、入出力、失敗は何か |
| 運用設計 | 運用、保守 | 監視、権限、復旧、更新は誰が行うか |
| テスト対応 | 発注者、品質担当 | 何をもって要件を満たすか |
設計資料を読者と判断目的で使い分ける
同じ情報をPowerPoint、表計算、文章へ重複して書くと、更新時に内容がずれます。
一つの正本を決め、別資料では要件IDや画面IDで参照してください。
| 資料 | 正本にする情報 | 他資料からの参照 |
|---|---|---|
| 要件一覧 | 目的、優先度、受け入れ条件 | 要件ID |
| 画面一覧 | 画面名、利用者、主操作 | 画面ID |
| データ辞書 | 項目名、型、制約、保持 | データID |
| API仕様 | 認証、入出力、エラー | API ID |
| テスト一覧 | 前提、操作、期待結果 | 要件IDと画面ID |
ISO/IEC/IEEE 29148の規格案内は、要求工学のプロセスと要求情報項目を扱っています。
要件と設計を混同せず、設計判断がどの要求を満たすのか追跡できる形にします。
プレゼン資料は意思決定に必要な全体像へ絞り、詳細仕様は更新しやすい正本へ置きます。
図を見ただけで不明な矢印には、通信の向き、データ、認証、失敗時の扱いを追記してください。
最小の設計書を七段階で組み立てる
最初から大きなテンプレートを複製せず、中心となる利用者操作から設計を広げます。
- 要件IDと受け入れ条件を固定する
- 端末、サーバー、DB、外部サービスの構成図を描く
- 主要操作の画面一覧と遷移図を作る
- 保存するデータ、ID、制約、保持期間を定義する
- APIの認証、入出力、エラー、再試行を定義する
- 権限、ログ、監視、バックアップ、復旧を定義する
- 要件IDからテストまでの対応表を作る
文書内の「必須」「推奨」「任意」は意味を定義します。
RFC 2119とRFC 8174を参考に、規範語を強調して使う条件をチーム内でそろえられます。
未決事項は空欄にせず、選択肢、決定者、期限、決定によって変わる設計を記録します。
「後で相談」という文言だけでは、実装開始の可否を判断できません。
一項目の変更が届く資料数を数える計算例
次の数字は、重複記載の負担を把握するための仮定です。
会員の電話番号を要件一覧、画面仕様、データ辞書、API仕様、テスト一覧の5資料へ直接書いているとします。
形式を変更するたびに5か所を更新する必要があります。
データ辞書を正本にし、ほかの4資料がデータIDを参照する形なら、定義変更は1か所で済むでしょう。
| 管理方法 | 定義を書く場所 | 変更対象 |
|---|---|---|
| 五資料へ重複 | 5 | 5か所 |
| 正本と参照 | 1 | 1か所 |
| 差 | 4 | 4か所削減 |
参照方式でも、画面の入力制限やAPIの互換性など各資料固有の影響は確認します。
正本化は影響分析を不要にする仕組みではなく、定義の食い違いを減らす仕組みです。
設計書をコードと同じ変更単位でレビューする
大規模な設計書を月末にまとめてレビューすると、どの判断で変わったか追いにくくなります。
一つの要件変更ごとに、関連する図、仕様、テストを同じ変更として提出してください。
GitHubのPull Requestレビュー資料は、コメント、承認、変更要求を変更内容へ結び付ける仕組みを説明しています。
設計資料も履歴管理できる形式なら、コード変更と同じレビューへ含められます。
重要な正本は、承認なしで直接書き換えないようにします。
GitHubの保護ブランチ資料を参考に、レビュー数やテスト成功を更新条件にしてください。
設計判断には「なぜ」を短く残します。
採用案、却下案、判断日、前提を記録すると、担当者が変わった後の再議論を減らせます。
運用と安全性の設計を公開前へ先送りしない
設計書が画面とAPIだけで終わると、公開後の監視、問い合わせ、権限変更、障害復旧が担当者の記憶へ残ります。
ログ項目、通知条件、一次対応、復旧順、データ削除を開発中に決めてください。
NIST Secure Software Development Frameworkは、安全な開発の準備、ソフトウェアの保護、安全な成果物、脆弱性対応を工程として扱っています。
秘密情報の保管、依存関係、ビルド環境、脆弱性連絡先も設計資料の対象です。
運用図では正常な通信だけでなく、外部API停止、DB復旧、管理者不在を描きます。
誰がどの権限で何分以内に判断するかを、実際の当番体制へ合わせてください。
アプリ開発の設計書でよくある質問
設計書は一つのファイルにまとめますか？
小規模なら一つでも構いませんが、更新頻度と読者が異なる情報を無理にまとめる必要はありません。
要件、画面、データ、API、運用の正本を決め、IDで相互参照できることを優先します。
設計書のテンプレートはそのまま使えますか？
項目漏れの確認には使えますが、案件にない章を埋めることが目的ではありません。
要求情報を扱う国際規格の案内も参考に、利用者、制約、検証方法へつながる項目だけを残します。
設計書はいつ更新しますか？
要件、画面、データ、API、運用の判断が変わった変更と同時に更新します。
後でまとめて転記せず、変更単位のレビュー手順へ設計差分とテスト差分を含めてください。
正本と参照IDで変更に追従できる設計書を作る
良い設計書は情報量が多い文書ではなく、現在の判断と変更の影響を追える資料です。
要件からテストまでをIDで結び、定義の正本と各資料固有の説明を分けます。
- 設計資料を分ける基準は読者、判断目的、更新頻度
- 最小構成に必要な全体、画面、データ、API、運用、テストの対応
- 重複記載を減らす正本と要件ID、画面ID、データIDによる参照
- 変更履歴へ残す採用案、却下案、判断日、前提
設計と要件の対応ができたら、アプリ開発のテスト工程と確認項目で各受け入れ条件を実行可能なテストへ変換できます。
