「このデータを、なぜ別の表に分けたんですか」。担当者が変わるたびに説明し、AIに修正を頼むたびに背景を入れ直す。コードから動きは読めても、選ばなかった案や当時の事情までは分からないことがあります。
ADRは、重要な設計判断の理由を短く残す記録です。正式な長い設計書を増やす前に、1つの判断を1枚にします。この記事では、架空の小規模な予約管理を例にします。特定の技術を採用すべきという比較ではありません。
全部の実装に書かず、戻しにくい判断から選ぶ
変数名の変更まで記録すると続きません。データの持ち方、認証の境界、外部サービスとの接続など、後から変える際に影響が広い判断を選びます。「次の担当者が、理由を知らずに変えると困るか」を目安にできます。
背景には、当時の制約を具体的に書く
「シンプルだから」だけでは、次の人は別の案もシンプルだと考えます。担当者の人数、必要な連携、扱うデータ、運用できる範囲を残します。将来の大規模化を先回りして複雑にしたのか、現時点の仕事に必要だったのかも区別できます。
| 項目 | 架空の記入例 |
|---|---|
| 判断 | 予約データと通知の状態を分ける |
| 背景 | 予約確定後に通知だけ失敗することがある |
| 比較した案 | 予約と通知を同時に完了扱い／状態を別に持つ |
| 採用理由 | 予約の有無と通知の再送を別に判断したい |
| 受け入れる不便 | 通知待ち一覧と再送処理が必要 |
| 見直し条件 | 通知先や処理量が増え、手動確認が追いつかない |
採用しなかった案も、一言だけ残す
判断の価値は、選択肢との比較にあります。「大きな会社が使っていたから」では、自分のチームに当てはまる条件が分かりません。候補Aが悪いのではなく、今回の制約ではBを選んだ、と書くと、条件が変わった際に見直せます。
ADR-003：予約と通知の状態を分ける
状態：提案中
背景：予約済みでも通知が届かない場合がある
候補：一括完了／状態を分離
判断：状態を分離し、通知だけ再処理できるようにする
影響：通知待ちの確認と再送記録を追加
確認すること：保存後の通知失敗、再送時の重複
見直し条件：処理量や通知先が変わったとき
判断者・日付：チームで確定後に記入
変更するときは、昔の理由を消さない
AWSのADRガイドは、承認後の判断を新しい記録で置き換え、履歴を残す流れを説明しています。小さなチームでも、旧記録に「ADR-008で置き換え」とリンクを付けると、以前の判断が誤りだったのか、条件が変わったのかを区別できます。
検討中の案と確定した判断も分けます。提案のメモを、AIがすでに決まった仕様として参照しないよう、状態を冒頭に置きます。新しい判断を採用したら、関連する仕様書や実装の参照先も更新します。
AIへ渡すのは、判断と確認対象のセット
実装を頼むときは、今回の修正に関係するADRと、対象の機能・変更点を渡します。文書だけを読ませて、現行コードも一致していると考えないことが大切です。理由に反する変更が必要なら、コードより先に判断を見直す話をします。
まず次の設計相談で、「なぜ選ぶか」「どんな不便を受け入れるか」「いつ見直すか」を各1文で残してください。将来のための大量の文書より、次の判断を説明できる小さな記録が役に立ちます。
参考資料・確認範囲
2026年11月2日確認。本文の例・図・ひな型は本記事用に作成したものです。以下は、設計や事例の背景として参照した一次資料です。
コメント