はじめに
SESエンジニアとして3年間、設計書を「読む側」でした。先輩が作った設計書を見ながら手順書通りに構築する。それ自体は普通にできていた。
でも「設計書を書いてください」と言われたことはなかった。だから書いたこともなかった。
あるプロジェクトで初めて、小規模なインフラ構成の設計書を担当することになりました。「大丈夫かな」という不安がありながらも、「読んだことはあるし、なんとかなるだろう」と思っていた。
なんとかなりませんでした。
この記事は、初めて設計書を書いたときにやらかしたことを全部さらして、「同じ失敗をしないための視点」を伝えるものです。
この記事を読むと、以下のことができるようになります。
- 設計書を書く前に確認すべき「目的と読み手」の考え方が分かる
- インフラ設計書でよく出てくるドキュメントの種類と役割が整理できる
- 初めて書くときに陥りやすい失敗パターンとその対策が分かる
やらかし①：「誰が読むか」を考えていなかった
最初の失敗は、設計書を書き始める前に「誰が読むのか」を確認しなかったことです。
私は「詳しい人が読む」と思い込んで書きました。専門用語を説明なしに使い、構成図も「分かる人には分かる」レベルで描いた。
レビューで返ってきたのは「これ、構築担当が見ても手を動かせないですよ」というフィードバックでした。
設計書には複数の読み手がいます。
| 読み手 | 何を求めているか |
|---|---|
| 承認者（上長・PM） | 構成の妥当性・リスク・コストが判断できるか |
| 構築担当者 | この通りに作れるか。手順の根拠が分かるか |
| 運用担当者 | 後から見て構成を理解できるか。変更時に参照できるか |
| レビュアー | 抜け・漏れ・矛盾がないか |
「誰に何のために書くか」を最初に確認することが、設計書の第一歩です。
やらかし②：「構成図」と「設計書」の区別がついていなかった
設計書を書いてと言われたとき、私は「AWSの構成図を作ればいい」と思っていました。
Draw.ioでEC2・RDS・VPCを繋いだ図を作って、「できました」と持っていったら「これは構成図ですね。設計書はどこですか？」と言われました。
設計書は複数のドキュメントの集合です。インフラ系でよく使われるものを整理します。
インフラ設計書の種類
基本設計書（方式設計書）
「何をどのような方針で作るか」を決めるドキュメントです。AWSを使う理由、リージョンの選定理由、可用性をどのように担保するか、セキュリティの方針など、全体の方向性を記します。
詳細設計書
「具体的にどう作るか」を決めるドキュメントです。EC2のインスタンスタイプ・AMI・セキュリティグループのルール・RDSのパラメータなど、実際に構築するときの仕様を詳細に記します。
ネットワーク設計書
VPCのCIDR、サブネットのアドレス帯、ルートテーブルの設定、セキュリティグループのルール一覧などを記します。
構成図
上記の設計を視覚的に表現したものです。設計書の一部として添付されることが多い。
やらかし③：「なぜそうしたか」が書かれていなかった
詳細設計書に「EC2インスタンスタイプ：t3.medium」と書きました。
レビューで「なぜt3.mediumにしたのですか？」と聞かれて、「なんとなくそのくらいかなと思って」と答えてしまいました。
設計書には「何を選んだか」だけでなく「なぜそれを選んだか」を書く必要があります。
【良くない記述】
EC2インスタンスタイプ：t3.medium
【良い記述】
EC2インスタンスタイプ：t3.medium
選定理由：想定同時接続数100、メモリ使用量目安2GB程度。
t3.smallではメモリ不足のリスクがあり、t3.largeはコスト過剰と判断。
負荷試験後に再評価する。
「なぜ」が書かれていない設計書は、後から「なぜこの設定なのか分からない」という状態を生みます。設計者が現場を離れたあと、誰も変更できなくなる。
やらかし④：前提条件と制約が書かれていなかった
設計書を書いた後、「この設計って、〇〇という前提で成り立ってますよね？」と指摘を受けました。
言われてみれば確かにそうなのですが、その前提を明記していなかった。
設計書には「前提条件」と「制約事項」を必ず書きます。
前提条件の例：
- AWSアカウントが既に作成済みであること
- 特定のリージョン（ap-northeast-1）を使用すること
- アクセス制御はSSO・IAMで管理されていること
- 本番・検証・開発の3環境を構築すること
制約事項の例：
- 予算上限：月額〇万円
- 既存システムとの連携のため、特定のIPアドレス範囲を使用すること
- コンプライアンス要件により、特定のサービスは使用不可
これが書かれていないと、後から「あの前提は変わったけど設計はそのまま」という齟齬が起きます。
初めて書くときの進め方
失敗経験を踏まえて、初めて設計書を書くときに役立つ進め方を整理します。
Step 1：読み手と目的を確認する
「誰が何のために読む設計書か」を担当者・PMに確認します。承認用なのか、構築用なのか、引き継ぎ用なのかで記述レベルが変わります。
Step 2：既存の設計書を参考にする
社内に過去のプロジェクトの設計書があれば、まずそれを読みます。フォーマット・記述レベル・どこまで詳細に書くかの基準が分かります。フォーマットは一から作らず、テンプレートを使います。
Step 3：目次（アウトライン）を先に作る
全文を書き始める前に、どんなセクションを書くかを先に作ります。
1. 概要
1.1 目的
1.2 前提条件・制約事項
1.3 用語定義
2. システム構成
2.1 全体構成図
2.2 AWSサービス一覧
3. ネットワーク設計
3.1 VPC設計
3.2 サブネット設計
3.3 セキュリティグループ設計
4. サーバー設計
4.1 EC2設計
4.2 RDS設計
5. 運用設計
5.1 バックアップ方針
5.2 監視設計
目次を作ってレビューしてもらうだけで、「この項目が漏れている」という指摘をもらえます。全文を書いた後に構成から変えるより、ずっと楽です。
Step 4：「なぜ」を意識して書く
各設計項目に「選定理由・採用根拠」を書く習慣をつけます。
まとめ
この記事では以下のことを解説しました。
- 設計書を書く前に「誰が何のために読むか」を確認することが最初の一歩
- 設計書は構成図だけでなく、基本設計・詳細設計・ネットワーク設計などの複数のドキュメントの集合
- 「何を選んだか」だけでなく「なぜそれを選んだか」を記述することが重要
- 前提条件と制約事項を明記しないと、設計の根拠が後から追えなくなる
- まず目次を作ってレビューを受けることで、構成の漏れを早期に発見できる
設計書は「完璧に書かなければいけない」というものではありません。読み手が必要な情報を得られるかどうかが基準です。最初から完璧を目指さず、レビューを受けながら育てる意識で書き始めてみてください。
ハンズオンラボでは、未経験からでも「作って覚える」をモットーにしたITハンズオンイベントを定期開催しています。
面白かったら
「👇いいね」で応援