ADRの書き方｜設計判断の背景・選択肢・見直し条件を残す

ADRは、重要な設計判断について「何を選んだか」と「なぜその条件で選んだか」を残す記録です。構成図だけでは読み取れない制約や不採用案を残すと、後から参加した人も判断の前提を確認できます。

この記事では、クラウドや業務システムの設計に関わるエンジニア向けに、短いADRを作るための項目と記入例を紹介します。特定の方式を正解とするものではなく、選択の理由を共有するための書き方です。

記録するのは、後で理由を問われる判断

AWSのガイダンスでは、ADRはアーキテクチャ上の重要な選択を記述し、その背景、決定、結果を含むと説明しています。AWSのADRプロセス

すべての小さな実装変更を同じ重さで記録する必要はありません。チームで、どのような判断を対象にするかを決めましょう。次のような問いを使うと、記録すべき理由を整理できます。

ADRは詳細設計書の代わりではありません。実装方法は設計書へリンクし、ADRにはその方法を選ぶことになった条件を残します。

以下は、チームで使う項目の提案です。AWSのテンプレートをそのまま転載したものではありません。

不明な点は事実と分けて書きます。「今後増えるはず」ではなく、「増加量は未確認。担当部署へ確認し、回答まで現行の範囲を前提とする」とすれば、判断が依存する情報を追えます。

ここでは、利用者が依頼した帳票を別処理で作成する架空のシステムを考えます。実施済みの設計や性能検証ではありません。

判断する問いは「依頼した画面で帳票完成まで待つか、受付後に別途完成を知らせるか」です。前提として、利用者には即時の完成が必須ではなく、受付状況を確認できることが必要だとします。

案	この仮例で確認する利点	追加で解決すること
完成まで待つ	画面上の流れを一度で説明しやすい	待機時間、失敗時の再依頼
受付と完成を分ける	完成を待たず受付結果を返せる	状態表示、重複依頼、失敗通知

「非同期の方が優れている」で終えず、「この機能では受付と完成を分ける。受付状態の表示と失敗時の対応を実装範囲に含める」と決定を書きます。技術方式だけを選び、必要な運用を後回しにしないためです。

見直し条件には、即時の結果が必要な別用途へ広がる場合や、受付後の状態管理を運用で維持できない場合などを挙げます。すべての連携を同じ方式にする判断とは区別してください。

レビュー担当は、自分の好む技術かどうかより、背景と決定がつながっているかを確認します。不採用案の説明が不公平なら、比較条件をそろえます。性能や費用の実測が必要な判断では、未検証であることと確認方法を残します。

合意前は提案中として扱い、決定日と判断者を記録します。AWSのプロセスでは、受け入れたADRの判断を変える場合、新しいADRを作り、以前の記録を置き換えた関係を残します。過去の理由を消して書き直すより、どの前提が変わったかを追える形にします。

ADRを作っても、設計書や変更のレビューから辿れなければ使われにくくなります。構成資料や対象機能の説明からリンクし、判断が影響する範囲を明示しましょう。運用手順に影響する決定なら、運用手順書の更新対象も確認します。

まずは最近議論した一つの設計判断を選び、問い、制約、不採用案、受け入れた不利益を書いてみてください。それを読んだ別の担当者が「当時の条件なら、その選択になった理由」を説明できるかが、見直しの出発点になります。