構成を決めて動かしたものの、数週間たつと「なぜこのサービスにしたのか」が自分でも思い出せない。人に聞かれて結論は答えられても、根拠がすぐに出てこない。そんな状態は、選んだ理由が頭の中にしか無いことから起きます。この記事は、理由を短い文書として残す ADR の最小の書き方を、学習中の構成にも使える形で整理します。
この記事の結論
- ADR は、設計上の重要な選択を「文脈・決定・結果」で残す短い文書です。
- 残すのは「どう作ったか」ではなく「なぜそうしたか」です。
- 全部の判断を書くのではなく、後で変えにくい・影響が大きい判断だけを書きます。
- 一度受け入れた ADR は書き換えず、変えるときは新しい ADR で置き換えます。
- 選択肢と捨てた理由まで書くと、後から同じ議論を蒸し返されにくくなります。
ADR とは何か
ADR（Architectural Decision Record、アーキテクチャ決定記録）は、設計上の重要な判断を1件ずつ記録する短い文書です。AWS の規範ガイダンスでは、ADR を「アーキテクチャ上の重要な決定を、その背景や結果とともに記録するもの」として扱っています。1件ずつ積み上がるので、全体としては決定ログになります。
ここで大事なのは、構成図や手順書とは役割が違うことです。構成図は「いまどうなっているか」を示します。手順書は「どう作るか」を示します。ADR が示すのは「なぜそうなっているか」です。構成図だけを見ても、なぜ別の選択肢ではなくそれだったのかは読み取れません。
STEPS VS WHY手順と判断
残すのは手順ではなく、判断の理由
手順の記録
どう作ったか
- 押した順番・設定値改定や環境で古くなる
- 後で分かること同じものを再現できる
判断の記録（ADR）
なぜそうしたか
- 背景・選択肢・引き受けたこと前提が変わっても読める
- 後で分かること今も成り立つか見直せる
なぜ「理由」を残すのか
理由を残す価値は、主に3つの場面で出ます。
- 担当が替わるとき。 後から入った人は、構成を見て「なぜこうしたのか」を聞ける相手がいないことがあります。理由が残っていれば、前提が今も成り立つかを自分で確かめられます。
- 数か月後の自分に説明するとき。 学習中の構成でも同じです。作った直後は覚えていても、別の学習に移ると根拠から忘れていきます。
- 同じ議論を蒸し返されたとき。 「なぜ EC2 ではないのか」と聞かれるたびに一から説明し直すのは負担です。検討した選択肢と、捨てた理由が書いてあれば、その文書を示せば済みます。
もうひとつ、書くこと自体の効果があります。理由を文章にしようとすると、自分の中で曖昧だった根拠が見つかります。「なんとなく」で選んでいたと気づけば、その時点で選び直せます。
最小の書き方｜文脈・決定・結果の3点
AWS の規範ガイダンスは、ADR に最低限含める内容を文脈・決定・結果としています。この3点だけで、ADR は成立します。
| 部品 | 書くこと | 後から分かること |
|---|---|---|
| 文脈 | 判断が必要になった背景、守りたい条件、制約 | その時点で何を前提にしていたか |
| 決定 | 何を選んだか。1〜2文で言い切る | 結局どうなっているか |
| 結果 | 選んだことで起きること。良い面も、引き受ける不便も | 何を引き受けたつもりだったか |
これに、検討した選択肢と捨てた理由を足すと強くなります。選んだものだけが書いてあると、「他は考えなかったのか」という疑問が残るからです。選択肢の比べ方には、Well-Architected フレームワークの6本の柱（運用上の優秀性・セキュリティ・信頼性・パフォーマンス効率・コスト最適化・持続可能性）が観点として使えます。柱の使い方の詳細はトレードオフの考え方の記事に譲ります。
THREE PARTSADR の部品
ADR は文脈・決定・結果の3点に、選択肢を足して書く
-
文脈
なぜ判断が要ったか
背景・守りたい条件・制約
-
決定
何を選んだか
1〜2文で言い切る
-
結果
何を引き受けるか
良い面も不便も書く
-
選択肢
他に何を考え、なぜ捨てたか
蒸し返しを防ぐ
書き方のコツは、結果の欄に不便なことも書くことです。良い面だけの結果は宣伝文のようになり、後から読む人が前提を疑う手がかりになりません。「運用の手間が増える」「ある機能を諦める」のような引き受けたことを書いておくと、状況が変わったときに見直す合図になります。
CHECK 1ここまでの確認
ADR に最低限書くものとして挙げられている3点は、どれですか?
答えと解説
答え: 2. 文脈・決定・結果
ADR の最小形は、判断の背景（文脈）、選んだこと（決定）、選んだ結果として起きること（結果）の3点です。「最小の書き方」の章を読み直してください。
どの判断を ADR にするか
すべての判断を書く必要はありません。AWS の規範ガイダンスは、ADR の対象を構造、非機能要件、依存関係、インターフェース、構築技術に関わる重要な判断としています。言い換えると、後から変えにくく、影響が広い判断です。
| 向いている判断 | 向いていない判断 |
|---|---|
| 構成の骨格（サーバーを自分で持つか、マネージドに寄せるか） | インスタンスの名前の付け方 |
| 非機能要件に関わる選択（止まっても困るか、どこまで速くするか） | 画面の色や文言の微調整 |
| 外部サービスや他システムへの依存の持ち方 | 日々変わる細かな設定値 |
| 他の部分との接続の約束（インターフェース） | 一時的な試し打ち |
| 構築に使う技術やツールの選択 | 手順書に書けば足りる作業 |
線引きの目安は、「半年後に別の人がこれを変えようとしたとき、理由が分からないと困るか」です。困るなら ADR にします。困らないなら、手順書や設定ファイルのコメントで十分です。
ADR の状態と書き換えない決まり
ADR には状態があります。規範ガイダンスでは Proposed（提案中）、Accepted（受け入れ済み）、Rejected（却下）、Superseded（置き換え済み）が挙げられています。
LIFECYCLEADR の状態
受け入れた ADR は直さず、新しい ADR で置き換える
-
Proposed
提案中として書く
-
レビュー
議論して判断する
-
Accepted / Rejected
受け入れか却下
-
新しい ADR
判断が変わったら書く
-
Superseded
古い方は置き換え済み
流れは次のとおりです。まず Proposed として書き、レビューで議論します。通れば Accepted、通らなければ Rejected になります。却下された案も、なぜ通らなかったかが残る点で価値があります。
最も大事な決まりは、受け入れた ADR は書き換えないことです。判断が変わるときは、新しい ADR を書き、古い ADR を Superseded にします。元の本文を新しい決定に書き換えてしまうと、「昔はなぜそうだったか」が消えます。履歴が残っていれば、判断が変わった理由も、前提のどこが変わったのかも追えます。
CHECK 2ここまでの確認
ADR にするのに向いているのは、どちらの判断ですか?
答えと解説
答え: 1. 後から変えにくく、影響が広い構成の選択
ADR は、重要で後から変えにくい設計判断を残すものです。細かな調整まで書くと続かず、肝心の判断が埋もれます。「どの判断を ADR にするか」の章を確認してください。
学習者が自分の構成に使う小さな例
例として、学習用に静的なサイトを公開する場面を考えます。サーバーを自分で持つ EC2 にするか、ストレージだけで配る S3 にするかで迷ったとします。ここでは書き方を示すための仮の例です。
# ADR-001 静的サイトの置き場に S3 を選ぶ
状態: Accepted
【文脈】
個人の学習用に HTML と画像だけのサイトを公開したい。
更新は不定期で、アクセスは少ない。サーバーの管理に時間を割きたくない。
【決定】
ファイルの置き場として S3 を使い、サーバーは持たない。
【結果】
- OS やパッチの管理が要らなくなる。
- 動的な処理（ログイン、フォームの処理など）は自分では持てない。必要になったら別の仕組みを足す。
【検討した選択肢】
- EC2 で Web サーバーを動かす: 動的な処理もできるが、管理する範囲が増えるため見送った。
見てほしいのは、手順が1行も無いことです。どのボタンを押したかではなく、何を守り（管理の手間を減らす）、何を諦め（動的な処理）、他に何を考えたかが残っています。後で動的な機能が欲しくなったとき、この ADR を Superseded にして新しい判断を書けばよいと分かります。
よくある失敗
- 実装手順の書き写し。 手順は改定や環境の違いですぐ古くなります。ADR には書かず、公式ドキュメントや手順書に任せます。
- 結論だけで理由が無い。 「S3 を使う」だけでは、構成図に書いてあることの繰り返しです。文脈と結果が無いと、後から前提を確かめられません。
- 良い面しか書かない結果。 引き受けた不便が無いと、見直しの合図が分からなくなります。
- 選択肢を書かない。 他を検討していないように読まれ、蒸し返しの原因になります。
- 全部の判断を書こうとする。 続かなくなります。線引きの目安で絞ります。
- 受け入れた後に本文を直す。 履歴が消えます。変えるときは新しい ADR で置き換えます。
CHECK 3ここまでの確認
受け入れ済みの ADR の判断が後で変わりました。どう扱いますか?
答えと解説
答え: 2. 新しい ADR を書き、古い ADR は置き換え済みにする
受け入れた ADR は書き換えず、変えるときは新しい ADR で置き換えます。「なぜ昔はそうだったか」という履歴が残るからです。「状態と書き換えない決まり」の章を読み直してください。
まとめ
ADR は、文脈・決定・結果の3点で「なぜそうしたか」を残す短い文書です。後で変えにくい重要な判断だけを書き、検討した選択肢と捨てた理由、引き受ける不便まで添えます。受け入れた ADR は書き換えず、変えるときは新しい ADR で置き換えます。次は、選択肢を比べる観点をトレードオフの考え方で身につけると、ADR の選択肢の欄が書きやすくなります。
参照ソース
- AWS 規範ガイダンス: ADR プロセス — ADR の定義、対象範囲、最低限の内容（文脈・決定・結果）、状態、受け入れ後は変更せず新しい ADR で置き換える決まりの根拠
- AWS Well-Architected フレームワーク: 柱 — 選択肢を比べる観点として挙げた6本の柱の名前の根拠
