はじめに

設計の仕事をしていると、こんな経験ありませんか?

「半年前に決めたこの設定、なんでこうしたんだっけ?」
「あの時、別の案も検討した気がするけど、なぜ採用しなかったんだろう?」などなど。。。。

私もまさに同じ状況で、設計書を書いたり、昔の設計書を読んだりしています。でも「なぜその設計にしたか」「他の候補は何だったか」「チームに確認しても曖昧になっていたり」が、時間が経つと曖昧になってしまう。

そんな悩みを解決してくれたのが ADR (Architecture Decision Record) という仕組みです。試しに、導入してみたら想像以上に良かったので、まだ知らない人向けに紹介します。

ADRって何?

ADR は Architecture Decision Record の略で、ざっくり言うと「チームで合意した設計判断の記録」です。

「え、それ設計書やん」と何が違うの？って最初は自分も思っていました。

ADR には次の4つのステータスがあります。

  • Proposed: 提案中、レビュー待ち
  • Accepted: チームレビューを経て承認済み
  • Rejected: 検討の結果、採用しないと決定
  • Superseded: 後のADRによって上書き

つまり ADR は単なるメモじゃなくて、「Proposed で起票 → レビュー → Accepted」というプロセスを経た、チームの意思決定の記録になります。

設計書だけじゃダメなのか?

ここで「設計書あるんだから ADR いらんくない?」という疑問が出てきます。でも実際にやってみると、両者は役割が全然違います。

設計書 ADR
書く内容 What (何を作るか) Why (なぜそうしたか)
採用しなかった案 通常書かない 必ず書く
更新頻度 仕様変更のたび 判断が変わったときだけ

設計書は「完成形を伝える」のが目的なので、検討経緯や没案は書かれません。でも、後から「なんでこうしたんだっけ?」となるのって、まさにその没案や検討経緯の部分になると思います。

ちなみに ADR で 一番価値があるのは「採用しなかった理由」 だと思ってます。「Aを選んだ理由」より「Bを選ばなかった理由」の方が、後から読む人にとって有用です。

監視設計の例

抽象的な話だけだとイメージしづらいので、私が監視設計で実際に書いた ADR を例に紹介します。

監視って、閾値とか検知ルールとか、「なぜその数字なのか」が後から分からなくなりがちです。（自分はそうです…）

例えば、評価周期と検知回数の設定。

  • 選択肢1: 評価周期1分、検知1回
  • 選択肢2: 評価周期5分、検知5回 ← 採用
  • 選択肢3: 評価周期10分、検知3回

採用したのは選択肢2ですが、なぜか?

「選択肢1だとアラートが出すぎるし、選択肢3だと気づくのが遅れるから」

…って、これだけだと「もうちょっと論理的に書かなきゃ」って思いますよね。
でも、これでも全然OKです。

ADR にしたものを少し整えるとこんな感じです。

### 選択肢1: 評価周期1分、検知1回
- 不採用理由: 一時的なスパイクでも即アラートになり、運用上ノイズが多い。
アラート疲れにより本当に対応すべき通知を見逃すリスクが高い。

### 選択肢3: 評価周期10分、検知3回
- 不採用理由: 異常検知までに最大10分かかり、対応開始が遅れる。
サービス影響が拡大するリスクがある。

経験則ベースの理由でも、ちゃんと「なぜダメか」を言語化すれば立派な ADR です。むしろ運用者の肌感覚って、設計書には載らない貴重な知見になると思います。
１年後とかに「この閾値、見直したほうがいいかも?」となったときにも、ADRがあると当時の判断根拠が分かるので議論がスムーズです。

ちなみに監視 ADR は、後追いで書きました。「ADR は設計フェーズで書くもの」だと思っていたんですが、後追いでも全然価値があります。むしろ運用してみての実感(「想定通りアラート疲れは起きなかった」など)を盛り込めるのは、後追いADRの特権です。設計フェーズで書くのが理想だとは思いますが、後追いでも遅くないので、
「うちの過去の判断、ADRにしてみようかな」と思ったタイミングで書き始めるのがおすすめです。

運用するときの工夫

フォーマットは MADR 形式が使いやすい

MADR (Markdown Architectural Decision Records) というテンプレート形式があります。最低限こんな項目を埋めればOK。

# ADR-0001: タイトル

## ステータス
Accepted (2026-02-25)

## コンテキスト
〈なぜこの判断が必要か〉

## 検討した選択肢
- 選択肢A
- 選択肢B

## 決定
選択肢Aを採用する。

## 理由
〈採用した理由 / 採用しなかった理由〉

## 結果
〈この決定による影響・トレードオフ〉

最初から全部完璧に書こうとせず、この最小構成から始めるのがおすすめです。

管理は Git + Markdown + PR レビュー

ADR の管理場所は Git リポジトリ + Markdown がイチオシです。理由はシンプルで、

  • PR ベースでレビュー・承認できる
  • PR のマージ日時 = Accepted 日時として自動的に残る
  • PR のレビュアー = 承認者として自動的に残る
    「いつ・誰が・どう承認したか」が、特別な仕組みなしで履歴に残る

まとめ

正直に言うと、私自身もADRを始めたばかりで、まだ手探りの部分は多いです。「これで正解なのかな?」と思いながら書いているADR もあります。

でも、それでも導入してみて良かったなと思うことが3点あります。

  1. 「なぜこの設計にしたか」を後から振り返れる
  2. 「採用しなかった選択肢と理由」が残るので、将来の見直しがしやすい
  3. レビューと承認のプロセスが自然に組み込める

最初から完璧にやろうとせず、まず1本書いてみるのがおすすめです。MADR形式で最小限の項目から始めて、運用しながら自分たちのチームに合った形に育てていけばOKかなと思っています。

おまけ: AI時代の設計書として

最後に余談ですが、昨今のAI時代において、ADR はとてもいい仕組みだなと思っています。

コードや設計はAIが生成できるようになってきましたが、「なぜその判断をしたか」という人間の意思決定は、まだ人間が残すべき領域なんじゃないかと。
AIに設計を手伝ってもらうときも、ADR があれば「過去にこういう理由でこの構成にした」と前提を伝えられるので、AIとの協業もスムーズになると感じています。

ADR はその「なぜ」の部分を綺麗に切り出せる仕組みだと感じています。

参考リンク