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

日本企業の IT 現場では、長い間「設計書」が重視されてきました。基本設計書、詳細設計書、パラメータシート、運用設計書、試験仕様書。これらは成果物として作成され、レビューされ、承認され、納品されます。

設計書という名前そのものが悪いわけではありません。問題は、その文書が何を残すために存在しているのかが曖昧になることです。文書が存在していても、判断の理由が残っていなければ、後から読む人は変更してよいのか判断できません。

設計書で本当に残すべきなのは、単なる項目の記入結果ではありません。何を決めたのか。どの粒度で決めたのか。なぜそう判断したのか。実際の構成や設定はどこにあるのか。この記事では、設計書を「納品物としての帳票」ではなく、判断と実体をつなぐ文書として整理します。

設計書を成果物ではなく、判断の記録として扱う

従来の設計書文化では、文書は「埋めるもの」として扱われがちです。認証、認可、ネットワーク、バックアップ、監視、ログ、セキュリティ、可用性、運用、障害対応。こうした論点は多くのシステムで共通します。

もちろん、それらの論点は重要です。しかし、共通部分を毎回ゼロから文章で書く必要はありません。共通部分は、チェックリスト、設計パターン、標準構成、IaC モジュール、テンプレート、ガイドラインに寄せる方が自然です。

一方で、人間が考えて書くべきなのは、案件固有の部分です。このシステムでは何が難しいのか。どの制約が設計を決めているのか。何を優先し、何を捨てたのか。なぜその構成にしたのか。将来どこが変わりそうなのか。失敗すると、どこから壊れるのか。ここに設計があります。

世界標準は巨大な設計書テンプレートではない

設計ドキュメントには、世界的に参照される考え方があります。ISO / IEC / IEEE 42010 はアーキテクチャ記述の標準であり、ステークホルダー、関心事、視点といった考え方を扱います。IEEE 1016 は Software Design Description、つまりソフトウェア設計記述の標準です。TOGAF や ArchiMate は、エンタープライズアーキテクチャ領域で使われます。

一方で、実務では C4 Model、arc42、ADR、Diataxis、Docs as Code のような軽量な体系もよく使われます。C4 Model は設計をズームレベルで表現し、ADR は重要な設計判断を短く記録します。Docs as Code は、文書を Markdown や Asciidoc で書き、Git、レビュー、CI の流れに乗せる考え方です。

ここで重要なのは、標準やフレームワークをそのまま巨大なテンプレートとして持ち込むことではありません。誰のための文書か、どの関心事に答える文書か、どの粒度の設計か、どの判断を記録するのか、実体はコードや設定のどこにあるのかを明確にすることです。

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

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

この分類は今でも有効です。ただし、HLD と LLD を文書名として固定すると、重要な点を見失いやすくなります。HLD / LLD は文書名ではなく、設計の粒度です。

同じ Network Design でも、責任境界や接続方針を扱えば HLD です。CIDR、FW ルール、LB VIP、DNS レコードを扱えば LLD です。同じ Application Design でも、主要コンポーネントの責務を扱えば HLD であり、API のリクエスト、レスポンス、エラーコードを扱えば LLD です。

重要なのは「基本設計書か詳細設計書か」という名前ではありません。何を、どの粒度で、どの判断として固定しているのかです。

インフラ設計とアプリケーション設計は重心が違う

設計書で扱う内容は、大きくインフラとアプリケーションに分けて考えることができます。インフラ設計は、場を作る設計です。どこに配置するか、どう接続するか、どう守るか、どう監視するか、壊れたときにどう戻すか、どこまで自動化するかを扱います。

一方で、アプリケーション設計は、意味を作る設計です。何を扱うのか。どの概念が存在するのか。どの状態を持つのか。どの操作を許すのか。どのデータ構造で表すのか。どの振る舞いを実装するのかを扱います。

両者は分離できますが、完全には切り離せません。Kubernetes、認証認可、監視、CI / CD、DB、キャッシュ、メッセージング、SLO、オブザーバビリティは、インフラとアプリケーションの境界にあります。だからこそ、現代的な設計書では、ADR と IaC が重要になります。ADR は判断をつなぎ、IaC は実体をつなぎます。

共通ドキュメント

まず、インフラとアプリケーションのどちらにも関係する共通ドキュメントがあります。

モダンなドキュメント名	よくある日本語名	HLD / LLD 分類	主な役割
Vision / Concept	企画書、構想書、システム化構想	Pre-HLD	何を作るか、なぜ作るか
Requirements	要件定義書	Pre-HLD	機能要件、非機能要件、制約
Architecture Overview	基本設計書、概要設計書、アーキテクチャ設計書	HLD	全体構造、責任境界、主要方針
System Context Diagram	システム関連図、外部接続図、コンテキスト図	HLD	利用者、外部システム、責任境界
ADR	設計判断記録、アーキテクチャ決定記録	Cross-cutting	なぜその設計にしたか

ここで特に重要なのは ADR です。従来の設計書は、最終形だけを書こうとします。しかし、実際の設計では、最終形よりも「なぜそうなったのか」が重要になることがあります。

ここでいう判断とは、単に「A を採用した」という決定だけではありません。どの制約を前提にし、どの選択肢を比較し、何を優先し、何を捨てたのかまで含めた設計上の判断です。

理由が分からなければ、変更してよいのか判断できません。判断できないから触れない。触れないからシステムは硬直化します。

アプリケーション系ドキュメント

アプリケーション設計では、概念、データ、API、状態、処理、画面を固定します。

モダンなドキュメント名	よくある日本語名	HLD / LLD 分類	主な役割
Domain Model	業務モデル、概念モデル、ドメインモデル	HLD〜LLD	業務概念、状態、ルール
Container Diagram	アプリケーション構成図、システム構成図	HLD	Web、API、DB、ジョブ、キューなどの関係
Component Diagram	コンポーネント設計書、機能構成図	HLD〜LLD	内部モジュール、責務、依存関係
API Specification	API 仕様書、インターフェース仕様書	LLD	エンドポイント、リクエスト、レスポンス
Data Model / ERD	DB 設計書、テーブル定義書、ER 図	LLD	エンティティ、テーブル、リレーション
Sequence / Flow	シーケンス図、処理フロー、業務フロー	LLD	処理順序、状態遷移、例外処理
State Machine	状態遷移図、状態設計書	LLD	状態、イベント、遷移条件
UI Flow / Wireframe	画面設計書、画面遷移図、ワイヤーフレーム	LLD	画面、操作、遷移

アプリケーション設計では、業務概念や状態を曖昧にしたまま API や DB だけを決めると、後から破綻しやすくなります。API 仕様や DB 設計は重要ですが、それらはドメインの理解を写像した結果です。

何をエンティティとして扱うのか。どの状態を許すのか。どの操作で状態が変わるのか。どの例外を業務上の例外として扱い、どれをシステムエラーとして扱うのか。この整理がないまま詳細設計に入ると、実装はできても設計としては弱くなります。

インフラ系ドキュメント

インフラ設計では、配置、接続、可用性、性能、セキュリティ、運用を固定します。

モダンなドキュメント名	よくある日本語名	HLD / LLD 分類	主な役割
Deployment Design	配置設計書、デプロイメント設計書、環境設計書	HLD〜LLD	実行環境、配置、クラスタ
Network Design	ネットワーク設計書、NW 構成図、外部接続設計書	HLD〜LLD	IP、DNS、FW、LB、経路
Platform Design	基盤設計書、プラットフォーム設計書	HLD〜LLD	OS、Kubernetes、VM、ミドルウェア基盤
Security Design	セキュリティ設計書、認証認可設計書	HLD〜LLD	権限、認証、秘密情報、脅威対策
Availability Design	可用性設計書、冗長化設計書	HLD〜LLD	冗長化、フェイルオーバー、単一障害点
Capacity / Performance Design	性能設計書、サイジング資料	HLD〜LLD	CPU、メモリ、ストレージ、スループット
Backup / DR Design	バックアップ設計書、DR 設計書、BCP 設計書	Ops Design	RPO / RTO、バックアップ、復旧
Observability Design	監視設計書、ログ設計書、アラート設計書	Ops Design	メトリクス、ログ、トレース、通知

インフラ設計では、構成図だけでは足りません。どの障害を許容するのか。どこを冗長化するのか。どこを単一障害点として受け入れるのか。どのメトリクスを見れば異常を検知できるのか。どのログが原因調査に必要なのか。どのバックアップから、どの時間まで戻せるのか。こうした問いに答えることがインフラ設計です。

サーバー名、IP アドレス、ポート番号の一覧は設計の一部ではありますが、それだけでは設計そのものにはなりません。設定情報と設計判断は分けて扱う必要があります。

運用・移行系ドキュメント

運用や移行に関する情報は、設計書の中に埋め込むより、使われる場面に合わせて分けた方が読みやすくなります。

モダンなドキュメント名	よくある日本語名	HLD / LLD 分類	主な役割
Runbook	運用手順書、障害対応手順書	Ops	操作、復旧、切り戻し
Incident Response Plan	障害対応計画、インシデント対応手順	Ops	検知、判断、連絡、復旧、報告
Migration Plan	移行計画書、移行設計書	Transition	データ移行、環境移行、切替条件
Rollout / Rollback Plan	リリース計画書、切替計画書、切り戻し手順	Transition	段階展開、ロールバック

設計書は、なぜその運用方式なのかを書きます。Runbook は、実際にどう操作するのかを書きます。障害時に必要なのは思想ではなく手順です。一方で、設計レビューで必要なのは手順ではなく判断です。文書は、使われる場面ごとに分けるべきです。

実体・一次情報

現代的な設計書では、実体を文書に書きすぎないことも重要です。

モダンなドキュメント名	よくある日本語名	HLD / LLD 分類	主な役割
IaC	Terraform、Ansible、Manifest、Helm values	Source of Truth	インフラ構成の一次情報
Config	設定ファイル、パラメータシート	Source of Truth	実際の設定値
README	README、構築メモ、開発者向け手順	Source of Truth / Guide	開発・構築・利用の入口
OpenAPI / Schema	API 定義、スキーマ定義	Source of Truth	API 仕様の一次情報
Test Specification	試験仕様書、テストケース	Verification	要件・設計が満たされることの確認

パラメータ、構成値、デプロイ定義、ネットワーク設定、ミドルウェア設定は、可能な限りコードや設定ファイルとして管理する方が安定します。Terraform、Ansible、Kubernetes Manifest、Helm values、Docker Compose のように、実際にシステムを構成するものがあるなら、それが一次情報です。

設計書に書かれた値と実際の設定がずれた瞬間、その設計書は信用しにくくなります。だから、設計書は実体を複製するのではなく、実体への参照と意味を書くべきです。何がどこに定義されているのか。なぜその値なのか。変更すると、どこに影響するのか。これが設計書の役割です。

設計書の体系

ここまでをまとめると、現代的な設計書は次のように整理できます。

分類	主なドキュメント	固定するもの
共通	Vision、Requirements、Architecture Overview、System Context、ADR	目的、要件、全体構造、責任境界、判断理由
アプリケーション	Domain Model、API Specification、Data Model、Sequence、State Machine、UI Flow	概念、データ、API、状態、処理、画面
インフラ	Deployment、Network、Platform、Security、Availability、Capacity、Backup / DR、Observability	配置、接続、基盤、可用性、性能、保護、監視、復旧
運用・移行	Runbook、Incident Response、Migration、Rollout / Rollback	操作、障害対応、移行、展開、切り戻し
実体・一次情報	IaC、Config、README、OpenAPI、Schema、Test Specification	実際の構成、設定、仕様、検証

この体系にすれば、文書は軽くなります。軽くなっても、情報量が減るわけではありません。むしろ、読むべき場所が明確になります。全体を知りたいなら Architecture Overview を見る。外部システムとの関係を知りたいなら System Context を見る。判断理由を知りたいなら ADR を見る。実装したいなら API Specification や Data Model を見る。現在の実体を知りたいなら IaC や Config を見る。障害対応したいなら Runbook を見る。このように役割を分けられます。

問題は設計書という名前ではない

基本設計書という名前を使ってもよいと思います。詳細設計書という名前を使ってもよいです。パラメータシートという名前を使う場面もあります。問題は名前ではありません。

その文書が何のために存在するのか。どの関心事に答えるのか。どの粒度の設計を固定するのか。どの判断理由を残すのか。どの実体を参照するのか。ここが曖昧なまま文書を作ると、後から読む人の判断を助けられない文書になります。

基本設計書という名前を使うなら、それは Architecture Overview として機能している必要があります。詳細設計書という名前を使うなら、それは実装可能な仕様、または実体への参照になっている必要があります。パラメータシートという名前を使うなら、IaC や Config と二重管理にならないようにする必要があります。

設計書の名前を変えるだけでは意味がありません。文書の役割を変える必要があります。

設計とは、判断の輪郭を固定することである

設計とは、項目を埋めることではありません。条件の中で判断し、その判断の輪郭を固定することです。

• 共通部分は標準化する
• 固有部分は論点化する
• 決定理由は ADR に残す
• 実体はコードと設定に寄せる
• 運用は Runbook に落とす
• 図は理解のために使う
• 読まれない文章は書かない

設計書を見直すことは、文書を捨てることではありません。むしろ逆です。本当に意味のある文書だけを残すために、設計書が何を残すべきかを再設計するということです。

参考書籍

関連する記事