ADRはいつ書く？設計判断を残す基準・レビュー手順・廃止方法

ADR（Architecture Decision Record）は、ソフトウェアアーキテクチャ上の重要な選択について、判断だけでなく背景と結果も残す文書です。AWSのADRガイドでは、構造、非機能要件、依存関係、インターフェース、構築技法に関わる判断を対象にしています。

ADRを書くかどうかの基準

判断に迷ったら、次の順序で対象を絞ると運用負荷を抑えやすくなります。

1. 構造や非機能要件など、アーキテクチャ上重要な判断か
2. 影響範囲、継続期間、リスク、費用が限定的ではないか
3. 判断と根拠が、別の文書ですでに扱われていないか

一方、範囲・期間・リスク・費用が限定された判断や、別の場所で記録済みの判断は、ADRを書かない候補です。architecture-decision-recordプロジェクトも、これらを書かない条件の例として挙げています。

つまり、短期間で戻せる低リスクな変更まで一律にADR化する必要はありません。判断を記録しない場合も、「影響が限定的」「既存文書に記載済み」のようにチーム内の除外基準をそろえておくと、作成漏れとの区別がしやすくなります。

最小構成は3項目

ADRに必要な最小項目は、次の3つです。

• 判断が必要になった背景
• 採用する判断
• プロジェクトや成果物への影響

これはAWSが示す最小構成に対応します。また、1件のADRでは1件のアーキテクチャ判断だけを扱うことが推奨されています。複数の判断を分ける考え方に従えば、後から一部だけを置き換える場合も関係を追いやすくなります。

費用、日程、スケーリングなど時間とともに変化し得る情報を書く場合は、その数値や前提がいつの時点のものかも明記します。同プロジェクトの指針でも、時点の記録が勧められています。

レビュー手順と状態遷移

AWSのプロセスでは、ADRはまずProposedとして作成され、レビュー後に承認、修正継続、却下のいずれかへ進みます。状態遷移の説明では、全メンバーがADRを作成できる一方、チームとして所有者を定めることも求めています。

レビュー会議は、次の流れにすると役割が明確です。

1. 所有者がProposedのADRを共有する
2. 会議の冒頭に読む時間を設ける
3. 承認、修正継続、却下を決める
4. 所有者が状態と必要情報を更新する

AWSは会議冒頭の読解時間について、平均10～15分を目安にしています。レビュー会議の例を採用する場合、事前に読んだ人がいることを前提にせず、同じ内容を確認してから議論できます。

承認時には、所有者がタイムスタンプ、バージョン、利害関係者一覧を追加してAcceptedへ更新します。承認時の更新項目を固定すれば、誰が関わった判断かを後から確認できます。却下時は、再び同じ議論を繰り返さないよう理由を追記し、Rejectedへ変更します。却下時の手順でも、却下理由を残すことが示されています。

変更・廃止は上書きか、新規ADRか

AWSは、承認または却下されたADRを不変の文書として扱い、変更が必要なら新しいADRを作ってレビューする方式を示しています。AWSの更新方針では、新しいADRが承認されて旧判断を置き換えたら、古いADRをSupersededへ変更します。

ただし、不変性は理論上の理想であり、更新可能なADRのほうがチームで機能したという異なる運用経験も報告されています。architecture-decision-recordプロジェクトの見解も踏まえ、導入時に「確定後は新規ADRで置換する」「既存ADRの更新を許す」のどちらを採るか決めておくべきです。履歴の明確さを優先するなら前者、文書管理の簡潔さを優先するなら後者が検討候補になります。

ADRが向いていないチーム・判断

ADRは、記録とレビューの時間を確保できないチームや、短期的で低リスクな判断が大半の状況には向きません。対象を広げすぎると、重要な判断が大量の文書に埋もれる可能性があります。まず「重要なアーキテクチャ判断」に限定し、1件1判断、最小3項目、所有者ありの小さな運用から始めるのが現実的です。

AWSはADRについて、チームの足並みをそろえ、戦略的な方向性を記録し、時間のかかる意思決定の繰り返しを減らすものと説明しています。ADRの目的を達成するには、件数を増やすことではなく、後から理由を確認する価値のある判断を選ぶことが重要です。