設計書に残すべきは項目ではなく判断である – 粒度、理由、実体をつなぐ文書設計

日本企業の IT 現場では、長い間「設計書」が重視されてきました。

基本設計書、詳細設計書、パラメーターシート、運用設計書、試験仕様書。これらは成果物として作成され、レビューされ、承認され、納品されます。

設計書という形式そのものが悪いわけではありません。問題は、設計書が「項目を埋めた帳票」になり、何を判断したのか、なぜそう判断したのか、どの範囲で正しいのかが残らないことです。

設計書で本当に残すべきなのは、単なる記入結果ではありません。判断、理由、制約、責任分界、そして実際の構成や設定との接続です。

設計書は成果物ではなく判断の記録である

設計書は、納品物として存在することがあります。レビューの対象になり、承認の証跡になり、契約上の成果物になることもあります。

しかし、文書が存在することと、設計判断が残っていることは同じではありません。

たとえば、監視間隔が 5 分と書かれていても、なぜ 5 分なのかが分からなければ、変更してよいのか判断できません。バックアップ保持期間が 30 日と書かれていても、業務要件、法的要件、コスト制約、復旧要件のどれに基づく判断なのかが分からなければ、設計としては弱いままです。

設計書の価値は、項目が埋まっていることではありません。後から読む人が、その判断を再評価できることにあります。

設計書にありがちな記載	本当に残すべきこと
監視間隔は 5 分	なぜ 5 分でよいのか、何を検知したいのか
バックアップ保持期間は 30 日	復旧要件、法的要件、コスト制約との関係
冗長構成にする	どの障害を許容し、どの障害は許容しないのか
認証は SSO を使う	IdP、権限、例外運用、障害時の責任分界
ログを保管する	何のために、誰が、どの期間、どの粒度で使うのか

プロセスは妥当性そのものではない

設計書は、レビューされ、承認されることがあります。

しかし、レビューしたこと、会議で合意したこと、表にまとめたことは、それだけで設計の妥当性を保証しません。

重要なのは、そのプロセスが何を確認し、何を確認していないのかです。可用性の観点は見たのか。セキュリティの責任分界は見たのか。運用時の変更権限は見たのか。障害時の切り分けは見たのか。

プロセスは判断を支えるために存在します。プロセスを踏んだこと自体を、判断の代用品にしてはいけません。

HLD / LLD は文書名ではなく粒度である

設計書では、HLD と LLD という分け方があります。

HLD、High Level Design は、全体構造、主要コンポーネント、責任境界、外部連携、非機能要件、技術方針を扱う粒度です。LLD、Low Level Design は、API、DB スキーマ、設定値、処理フロー、バリデーション、エラー処理など、実装に近い粒度です。

ここで重要なのは、HLD / LLD を文書名として固定しないことです。HLD / LLD は、文書の名前ではなく設計の粒度です。

同じネットワーク設計でも、責任分界や接続方針を扱えば HLD です。CIDR、Firewall rule、LB VIP、DNS record を扱えば LLD です。

粒度	扱うもの	残すべき判断
HLD	全体構造、責任境界、主要方針	なぜその構造にしたのか、何を優先したのか
LLD	設定値、API、DB、具体的な処理	なぜその値、その仕様、その条件にしたのか
ADR	重要な設計判断	選択肢、採用理由、受け入れた制約
IaC / Config	実際の構成や設定	文書上の判断と実体が対応していること

設計書は実体と接続されていなければならない

設計書が弱くなる理由の一つは、実体から切り離されることです。

設計書には「冗長化する」と書いてある。しかし、実際の Terraform module、Kubernetes manifest、Firewall rule、監視設定、Runbook とつながっていない。その場合、設計書は現実を説明しているようで、実際には現実を保証していません。

設計書は、すべての設定値を複製する場所ではありません。むしろ、実体がどこにあり、その実体がどの判断に基づいているのかをつなぐ場所です。

設定値そのものは IaC や設定管理に置く。判断理由は ADR や設計書に置く。運用手順は Runbook に置く。監視の実体は監視設定に置く。重要なのは、それらがばらばらに存在するのではなく、相互に参照できることです。

ADR は判断を残すための道具である

ADR、Architecture Decision Record は、設計判断を短く記録するための方法です。

ADR の価値は、結論だけではなく、当時の前提、選択肢、採用理由、受け入れた制約を残せることにあります。

設計は常に、制約の中で行われます。予算、納期、既存システム、組織のスキル、運用体制、将来の拡張性、セキュリティ要件。これらを無視した理想論は設計ではありません。

だからこそ、後から見た時に「なぜこの判断をしたのか」が分かるようにしておく必要があります。

ADR に残す項目	意味
背景	何が問題で、なぜ判断が必要になったのか
選択肢	検討した案と、それぞれの長所・短所
決定	採用した案
理由	なぜその案を選んだのか
影響	受け入れる制約、将来の変更可能性、運用上の注意

言葉の粒度が設計の粒度を決める

設計書では、言葉の粒度が重要です。

「冗長化する」「セキュリティを考慮する」「運用しやすくする」「必要に応じて対応する」といった表現は、一見もっともらしく見えます。しかし、そのままでは設計判断として弱いです。

どの障害を想定するのか。どの攻撃面を減らすのか。誰がどの操作を行うのか。何をもって運用しやすいと判断するのか。どの条件なら例外を認めるのか。

言葉が曖昧なままだと、責任分界も曖昧になります。責任分界が曖昧になると、障害時、変更時、レビュー時に判断できなくなります。

文書品質は設計品質の一部である

設計書は、システムの外側にある付属物ではありません。

設計、運用、保守、引き継ぎ、レビュー、障害対応、変更判断を支えるインターフェースです。

設定ファイルの変数名に一貫性が必要なように、API の責任分界に明確さが必要なように、文書にも一貫性と粒度の設計が必要です。

設計書に判断が残っていなければ、後から読む人は安全に変更できません。安全に変更できなければ、システムは硬直化します。硬直化したシステムは、やがて運用負荷や技術的負債として戻ってきます。

まとめ

設計書に残すべきなのは、項目を埋めた結果だけではありません。

何を決めたのか。なぜそう判断したのか。どの制約を受け入れたのか。どの範囲で正しいのか。実体はどこにあるのか。変更すると何に影響するのか。

設計書は、現実を単純化して安心するためのものではありません。複雑なシステムを、後から判断可能な形で扱うためのものです。

だからこそ、設計書は項目の集まりではなく、判断と実体をつなぐ文書として設計する必要があります。