詳細設計書、どこまで書けば十分か
「詳細設計書は、どこまで細かく書けばいいですか？」——これは、要件定義や設計を担当するようになったメンバーから、非常によく受ける質問です。
書きすぎれば時間がかかりすぎて開発に着手できず、書かなさすぎれば実装者の解釈がばらつき、あとで手戻りが発生する。25年以上、要件定義から設計・開発・運用までを一貫して担当してきた経験から、詳細設計書の「ちょうど良い粒度」をどう見極めるかについてお伝えします。
「詳細設計書は完璧であるべき」という思い込みを捨てる
詳細設計書について悩む方の多くは、「抜け漏れなく、完璧な設計書を作らなければならない」という前提を持っています。しかし、この前提こそが、設計フェーズを不必要に長引かせる原因になっていることが少なくありません。
詳細設計書は、それ自体が成果物ではなく、実装者が迷わずコードを書けるようにするための手段です。この目的に立ち返ると、「完璧かどうか」ではなく、「実装者が迷わず作業に着手できるかどうか」が判断基準になります。
詳細設計書に「必ず」書くべきこと
粒度を決める前に、省略してはいけない要素を明確にしておきます。これらが抜けていると、実装者の解釈がばらつき、手戻りの原因になります。
- 入力と出力：画面のどの項目から、どんなデータを受け取り、どんな処理をして、何を返す・表示するのか
- 正常系の処理の流れ：想定通りにデータが来たときに、どういう順序で処理が行われるか
- 異常系・例外処理：想定外の入力（空欄、不正な形式など）が来たときに、どう振る舞うべきか
- データの持ち方との対応：どのテーブルの、どのカラムに、何が保存・参照されるか
- 他機能との連携ポイント：他の画面や機能と、どこでどうつながっているか
この5つは、書く量の多寡にかかわらず、必ず設計書の中で言語化しておくべき項目です。逆に言えば、この5つさえ押さえられていれば、書き方の体裁や細かさは、プロジェクトの状況に応じて柔軟に調整して構いません。
詳細さの基準は「誰が実装するか」で変える
詳細設計書の粒度で最も重要なのが、「誰がこの設計書をもとに実装するか」という視点です。
経験の浅いメンバーが実装する場合
処理の順序、条件分岐のパターン、画面の細かい挙動まで、具体的に書き出す必要があります。「常識的に考えればこうだろう」という暗黙の前提を極力減らし、迷う余地を残さない設計書が求められます。
経験豊富なメンバーが実装する場合
すべてを事細かに書くと、逆に「読むのに時間がかかる」「自分で判断できる部分まで指定されて窮屈」といった弊害が出てきます。この場合は、5つの必須項目を押さえたうえで、実装の細部は担当者の裁量に委ねる書き方の方が、スピードも質も上がることが多いです。
外部のパートナー（委託先）が実装する場合
社内メンバーであれば口頭で補足できる前提知識も、外部のパートナーには伝わりません。70名規模のパートナーと協業してきた経験から言うと、外部委託の場合は、内部の暗黙知に頼らず、5つの必須項目に加えて、システム全体の前提や用語の定義まで含めて書いておく方が、後々の認識齟齬を防げます。
書きすぎることの弊害も理解しておく
「詳細に書けば書くほど安全」というのも誤解です。書きすぎには、次のような弊害があります。
- 設計フェーズに時間がかかりすぎ、開発着手が遅れる
- 仕様変更のたびに、大量のドキュメントを修正する必要が生じ、変更に弱くなる
- 実装者が設計書を読み切れず、結局重要な部分を読み飛ばしてしまう
- 実装者の工夫や改善の余地を奪い、指示待ちの姿勢を助長してしまう
特に、変化の多い新規事業のプロジェクトでは、仕様が固まりきっていない段階で詳細設計書を作り込みすぎると、その後の仕様変更のたびに大きな手戻りコストが発生します。事業の不確実性が高いフェーズでは、あえて詳細さを抑え、実装しながら調整していく進め方の方が合理的な場合もあります。
実務での判断の仕方：3段階で考える
実際のプロジェクトでは、次のように機能ごとに詳細度を変える判断をしています。
1. 影響範囲が大きい機能（決済、会員情報など）
不具合が起きたときの影響が大きい機能は、時間をかけてでも詳細に書きます。異常系の網羅性を特に重視します。
2. 一般的な機能（一覧表示、簡単な入力フォームなど）
パターンが決まっている機能は、5つの必須項目を押さえた最小限の記載にとどめ、実装のスピードを優先します。
3. 仕様が固まりきっていない、試行錯誤中の機能
あえて詳細設計書を作り込まず、簡単な処理フローの図やメモ程度にとどめ、実装しながら仕様を固めていくアプローチを取ります。ここで無理に詳細化しようとすると、実態と合わない設計書が出来上がり、かえって混乱を招きます。
詳細設計書を書いた後、必ずやっていること
書き終えたら、実装を担当する本人に、設計書の内容を「自分の言葉で」説明してもらう時間を必ず作ります。読んだだけでは気づけない疑問点や解釈のズレが、説明させることで初めて表に出てきます。
この確認作業を省略すると、実装が始まってから「ここ、どう処理すればいいですか」という質問が頻発し、結局は設計書を書いた意味が薄れてしまいます。書く量を増やすよりも、この確認作業を挟む方が、手戻りの防止には効果的だと感じています。
まとめ
詳細設計書の「どこまで書けば十分か」という問いに、絶対的な正解はありません。ただし、判断のための基準は次のように整理できます。
- 入力・出力、正常系、異常系、データとの対応、他機能との連携——この5つは必ず言語化する
- 実装する人の経験値（社内メンバーか、外部パートナーか）によって、詳細さを調整する
- 影響範囲の大きさ、仕様の確定度合いによって、機能ごとに詳細度を変える
- 書き終えたら、実装者に説明してもらい、解釈のズレがないかを確認する
「完璧な設計書」を目指すのではなく、「実装者が迷わず動ける最小限の情報」を見極める視点を持つことが、詳細設計書を書くうえで最も大切な考え方です。
