構築ドキュメントの設計 — 何を残し、何をコード化するか

構築ドキュメントは「書けば終わり」ではなく、何を書き、何を書かないかの設計が肝心です。手順を網羅するほど陳腐化が早まり、引き継いだ担当者を混乱させます。手順書に残すべき情報・コード化すべき情報・判断として記録する情報を分離する設計、そして重くなりすぎたドキュメント運用を止める判断軸を本記事で整理します。

ドキュメントが「書いた瞬間から腐る」構造的な理由

変化の速さと記述粒度のミスマッチ

インフラ構成は変化します。バージョンアップ、スケールアウト、クラウドリソースの追加——変更が加わるたびに手順書の記述は現実から離れていきます。10台規模の環境でも、半年で設定ファイルが20か所以上変わっていたという話は珍しくありません。問題の核心は「変化する情報」と「変化しにくい情報」を同一文書に混在させていることにあります。変わりやすい手順と変わりにくい設計意図を分離しないまま書くと、どちらも信頼できなくなります。ドキュメントが腐る根本原因は、更新頻度の異なる情報を同じ粒度で管理しようとする構造的なミスマッチです。

「現状維持バイアス」がドキュメントを増殖させる

構築が完了したあと、ドキュメントを削除・統廃合する判断は難しいです。「念のため残しておく」という心理が働き、古い手順書と新しい手順書が並立したまま放置されます。複数環境を担当するチームでは、環境ごとのドキュメントが独立して増殖し、3〜4環境で10本以上のWikiページが乱立するケースが見られます。参照する側は「どれが正しいか」を判断できなくなり、結局本番環境を直接確認するという本末転倒な事態につながります。ドキュメントが多いほど安心、という感覚がチームに根付いているなら、それ自体がリスクのサインです。

陳腐化のスピードは構造で決まる

ドキュメントが腐る速さは、書き方の構造によって決まります。手順を細かく書くほど変更発生時の更新コストが上がり、更新が先延ばしされ、最終的に放棄されます。一方で粗すぎる記述は、経験の浅い担当者には機能しません。どの粒度で何を書くかという「粒度の設計」が、ドキュメントの寿命を左右します。手順の細かさとメンテナンスコストはトレードオフであり、このバランスをプロジェクト開始時に意識して設計しなければ、ドキュメントはいずれ形骸化します。

手順書に残すべきもの・コード化すべきものの境界

「再現性」で判断する

コード化すべき情報の基準は「再現性」です。同じ操作を繰り返す可能性があるなら、手順書ではなくスクリプトやIaCで管理すべきです。ミドルウェアのインストール手順、設定ファイルの配置、サービスの起動設定——これらは何度でも実行される性質を持つため、コード化の恩恵が大きいです。逆に、一度だけ行う判断（「このアーキテクチャを選んだ理由」など）はコードに書けないため、文書として残す意味があります。「繰り返し実行するか」という問いが、コード化と文書化の境界線を引く最も実用的な判断軸になります。

情報の種類ごとの管理方法

情報の種類	特性	推奨する管理方法
インストール・設定の手順	繰り返し実行・変更が発生しやすい	IaC / スクリプト化
環境変数・パラメータ値	環境ごとに異なる・頻繁に変わる	変数ファイル / パラメータストア
構成図・依存関係	変更が少ない・視覚的理解が必要	図として文書化（自動生成が望ましい）
設計判断の経緯・背景	一度決まれば変わりにくい・文脈が重要	ADR（決定記録）として文書化
運用手順・例外対応フロー	判断が必要・自動化困難なケースを含む	手順書として文書化

コード化できない「判断文脈」の落とし穴

IaCやスクリプトが整備されていても、「なぜこの構成にしたか」は伝わりません。コードは「何を」実行するかは記述できますが、「なぜそう決めたか」は書けません。後任の担当者がコードだけを引き継いだ場合、変更の影響範囲を判断できず、慎重になりすぎて必要な改修が遅れることがあります。構築を任されたある担当者が前任者のTerraformコードを引き継いだものの、設計意図がわからず変更に踏み切れず、3か月間環境が凍結状態になったという話は珍しくありません。コードと判断記録は補完関係にあり、どちらかだけでは不完全です。

「なぜそう決めたか」を残す設計

ADR（アーキテクチャ決定記録）の導入判断

Architecture Decision Record（ADR）は、設計判断の経緯を軽量なフォーマットで記録する手法です。「背景・選択肢・決定・影響」という4項目を1ページ以内にまとめます。導入の敷居は低く、Markdownファイル1本から始められます。50台以上のサーバーを管理する環境では、ADRが10〜20本蓄積されるだけでも、後任者が設計判断の文脈を追いやすくなるという効果が出ます。ドキュメント全体の量を増やさずに、判断の履歴だけを積み上げられる点がADRの強みです。

判断記録に書くべき内容・書かなくてよい内容

判断記録には「選ばなかった選択肢とその理由」が特に重要です。採用した構成だけを書いても、「なぜ他の選択肢を捨てたか」は伝わりません。例えばNginxではなくHAProxyを選んだ場合、当時の要件（接続数の上限・SSL終端の方針・既存運用チームのスキルセット）を合わせて残します。一方、実装の詳細（設定ファイルの具体的な値）はコードに委ね、判断記録には書きません。この区別を徹底することで、判断記録が「手順書の劣化コピー」になるのを防げます。

判断記録が陳腐化しにくい理由

判断の背景は、手順や設定値ほど頻繁には変わりません。要件が変われば判断は更新されますが、「なぜ変えたか」を追記するだけで済みます。手順書のように「全体を書き直す」必要がないため、更新コストが低く、長期間にわたって参照価値を保ちやすいです。設計判断の文書は「塗り替える」ものではなく「積み重ねる」ものと捉えると、メンテナンスへの心理的負荷が大幅に下がります。

自動生成できる情報と人が書くべき情報の分離

自動生成に向く情報の種類

構成図、ホスト一覧、ポート開放状況、依存サービスの接続関係——これらはツールが自動生成できる情報です。TerraformのplanやAnsibleのインベントリファイルから構成情報を抽出するアプローチは、ドキュメントの鮮度を維持するうえで有効です。人間が手動で更新するより、コードと同期して生成される仕組みのほうが信頼性が高いです。ただし自動生成ツールの導入コストも無視できないため、環境規模が一定以上（目安として20台以上）を超えてから検討するのが現実的です。小規模なうちは手書きの構成図のほうが維持コストが低い場合もあります。

人が書くべき情報の特性

自動生成できない情報は「文脈・背景・意図」を持つものです。なぜこのサブネット設計を選んだか、なぜこのミドルウェアを採用したか、将来的な拡張でどこが変わる想定か——こうした情報はコードやツールから抽出できません。人が書くべき情報に集中することで、ドキュメント作成の工数を「判断の言語化」に振り向けられます。構築工数全体の5〜10%を判断の言語化に充てることが、中長期の引き継ぎコストを下げる投資として機能します。

自動生成と手書きの境界を設計で決める

「ここまでは自動、ここから先は手書き」という境界を明示しないと、どちらの情報も中途半端になります。プロジェクト開始時に「自動生成ドキュメント」と「判断記録」を別リポジトリまたは別ディレクトリに分けておくと、管理の責任が明確になります。構成情報は自動生成ツールが管理し、判断情報は人が管理するという役割分担を最初に決めます。この設計を後から変えるのは難しいため、プロジェクト初期の判断として押さえておく価値があります。

引き継ぎで壊れない最小限のドキュメント設計

引き継ぎ時に本当に必要な情報

引き継ぎの場面で「ドキュメントが多いほど安心」という認識は誤りです。現場では、引き継ぎ後に担当者が最初に参照するのは「環境の全体像」と「触ってはいけない箇所の注意書き」だという声が多いです。詳細な手順書よりも、「このシステムの構造と地雷」を1枚で俯瞰できるドキュメントのほうが価値が高い場合があります。大量のドキュメントを渡されると、後任者は何から読むべきかわからず、読むこと自体を諦めてしまうケースも珍しくありません。

ミニマム構成の設計

最小限のドキュメントとして機能するセットは3点に絞られます。（1）構成の全体図（自動生成でも手書きでも可）、（2）設計判断の記録（ADR）、（3）運用上の注意点（変更してはいけない設定・依存関係の注意・過去のインシデント概要）。この3点があれば、後任者は環境を把握し、安全に作業を開始できます。手順の詳細はコードから読み取れるため、手順書は最低限で構いません。ドキュメントの量ではなく、「判断と地雷の地図」として機能するかどうかが評価軸になります。

ドキュメントを「育てる」仕組みの設計

引き継ぎ後に担当者が「これが書いてなかった」と気づいた内容を追記できる仕組みを用意します。Gitで管理しPull Requestベースで更新する運用にすると、誰がいつ何を追記したかの履歴が残ります。ドキュメントの初版を完璧にしようとするのではなく、「不足を発見したら追加する」という運用文化を設計段階から組み込みます。この文化が根付くと、ドキュメントは担当者が交代するたびに少しずつ充実していきます。

重すぎるドキュメント運用を止める判断

「ドキュメント負債」が生まれるサイン

ドキュメント負債が積み上がっているサインは明確です。「最新の手順書がどれかわからない」「更新されていないドキュメントが参照され続けている」「新しい構成変更のたびにドキュメント更新が後回しになる」——こうした状態が日常化していれば、ドキュメントの設計を見直す時期です。更新されないドキュメントは、ない状態より悪い場合があります。誤った情報を信じて作業した担当者が障害を引き起こすリスクを生みます。現場でよく聞く話として、古い手順書通りに操作して本番環境に影響が出た、という事例があります。

削減判断の基準

どのドキュメントを廃止・統廃合するかの判断基準は3点が目安になります。「最終更新から6か月以上経過しているか」「直近3か月で参照された形跡があるか」「コードやツールで代替できるか」——この3点で整理すると、廃止・統廃合の対象が見えてきます。廃止の際は即削除ではなく、アーカイブとして別ディレクトリに移動させます。誤って必要なものを削除するリスクを避けつつ、日常的な参照から外します。半年後に誰も開いていなければ、削除を判断できます。

「書くのを止める」判断をチームで合意する

ドキュメント削減は個人の判断では動かしにくいです。「この種の情報は手順書に書かない」「コードをソースオブトゥルースとする」という方針をチームで明示的に合意し、文書化します。合意なく削減すると「誰かが消した」という摩擦が生まれ、ドキュメント整理の取り組み自体が停滞します。ドキュメント設計の方針そのものを文書化しておくことで、判断の根拠を共有でき、次に同じ議論を繰り返さずに済みます。

構築ドキュメント設計チェックリスト

構築ドキュメントの設計を見直す際、以下の観点で現状を確認してください。

1. 変化しやすい情報（手順・設定値）と変化しにくい情報（設計判断）を別の形式で管理しているか
2. 繰り返し実行する手順はIaCまたはスクリプトとして管理されているか
3. 「なぜそう決めたか」を記録するADRまたは同等の仕組みが存在するか
4. 採用しなかった選択肢とその理由が記録されているか
5. 自動生成できる情報（構成図・ホスト一覧）と人が書く情報（判断・意図）の境界が明示されているか
6. 引き継ぎに必要な最小セット（全体図・判断記録・注意点）が1か所にまとまっているか
7. 最終更新から6か月以上経過したドキュメントを定期的に見直す仕組みがあるか
8. 「書かない情報の範囲」をチームで合意・文書化しているか
9. 環境規模が20台以上に達したあと、自動生成ツールの導入を検討したか
10. ドキュメント更新の運用コストが、構築・変更工数全体の10%以内に収まっているか