「書けばいい」だけの設計書は通らない
詳細設計書を書き始めた頃、毎回レビューで大量の赤字が入ってきた。
「前提条件が書かれていない」「この設定の根拠は何か」「他システムへの影響は検討したか」。
書いた内容が技術的に間違っているわけではない。でも「読んだ人が迷わず作業できる」かどうかが足りなかった。
3つのことを意識するようになってから、レビューの指摘が激減した。
①「誰が読むか」を先に決める
設計書を書き始める前に「この設計書を誰が読むか」を確認する。
構築担当者（自分以外）が読む場合
- コマンドの一字一句まで書く
- 確認コマンドと期待する出力も書く
- 判断が必要な場面には「〇〇の場合は△△すること」を添える
上流のPM・顧客が読む場合
- 技術的な詳細は補足に回す
- 変更の理由・効果・リスクを先に書く
- 専門用語には括弧書きで説明を添える
自分自身が後で使う場合
- なぜその設計にしたかの背景を書いておく
- 他の案と比較した記録を残しておく
読む人が変われば、同じ内容でも書き方が変わる。「誰に向けて書くか」を決めずに書き始めると、どちらにも向いていない中途半端な設計書になる。
②前提条件と制約を最初に書く
設計書の本文より先に「前提条件」と「制約」を書く。これが後で一番効いてくる。
前提条件の例（サーバー構築の場合）
- OSはRHEL 8.6を使用する
- ネットワーク設定は別紙「NW設計書」の通りとする
- 作業は〇〇サーバーから踏み台経由で実施する
- sudo権限付きの作業用アカウントが事前に払い出される
制約の例
- 作業窓口は第2・第4土曜日の22:00〜翌3:00に限る
- 再起動を伴う作業は顧客への事前連絡が必要
- 本番環境への直接ログインは禁止
前提条件と制約を最初に書いておくと、レビュアーが「この状況を踏まえた設計かどうか」を判断しやすくなる。また、後からトラブルになったときに「書いてある通りにやった」という根拠になる。
③設定の根拠を1行添える
設計書にコマンドや設定値を書くとき、「なぜその値か」を1行添える。
根拠なし（よくある書き方）
[/etc/ssh/sshd_config]
PermitRootLogin no
ClientAliveInterval 300
MaxStartups 10:30:60
根拠あり（意識した書き方）
[/etc/ssh/sshd_config]
PermitRootLogin no # セキュリティ要件に基づきroot直接ログインを禁止
ClientAliveInterval 300 # 無操作状態が5分続いた場合にセッションを切断
MaxStartups 10:30:60 # 同時接続試行数の上限（標準値のまま）
根拠があると、レビュアーが「値が妥当かどうか」を判断できる。また数か月後に自分が見返したときに、なぜこの設定にしたかを思い出せる。
「標準値のまま」も立派な根拠だ。迷って決めた設定は、迷った理由と選んだ理由を書いておく。
実際のレビュー指摘で多かった項目
上記3つとは別に、レビューでよく指摘された内容を書いておく。
確認コマンドが書かれていない 設定変更後に「確認する方法」が書かれていないと、作業者が設定できたかどうかを確かめられない。変更手順の後に確認コマンドとその期待出力を書く。
リカバリ手順がない 作業が失敗したときにどう戻すかが書かれていない。特に本番環境の設定変更では「元の状態に戻す方法」を必ず書く。変更前の設定値のバックアップ取得手順も含める。
影響範囲の確認が抜けている 「この設定変更で何が影響を受けるか」の検討が書かれていない。関連サービスへの影響・ユーザーへの影響・監視ツールへの影響などを記載する。
AIで設計書の質を上げる使い方
最近は設計書のレビューにAIを活用している。
書いた設計書をコピーして「セキュリティの観点で問題がないか確認して」「抜けている観点がないか指摘して」と聞く。人間のレビューの前にAIに通しておくと、明らかな抜けを事前に潰せる。
AIが見落とすのは「現場固有の制約」だ。だからAIのレビュー結果をそのまま信じるのではなく、「抜けているかもしれない視点」として参考にする使い方が良い。
まとめ
詳細設計書を書くときに意識している3つのこと：
- 「誰が読むか」を先に決める（読む人によって書き方が変わる）
- 前提条件と制約を最初に書く（後からのトラブル防止・レビューの質向上）
- 設定の根拠を1行添える（値の妥当性の根拠・後から見返せる）
「書けばいい」から「読んだ人が迷わず動ける」設計書にする。そのための3つだ。