コードレビューやバグ調査で、「なんでこの実装にしたんだっけ？」 と思うことはありませんか？
そんな中、このような課題に対して、ADR（Architecture Decision Records）というものがあることを知り、導入を検討してみました。
本記事では、ADRの概要と主要フォーマットの比較を通じて、自チームでの導入方針を選定したプロセスを共有します。
ADRとは
ADR（Architecture Decision Records）とは、ソフトウェア開発におけるアーキテクチャ上の意思決定を記録するドキュメントです。
「何を決めたか」だけでなく、**「なぜそう決めたか」「どんな選択肢を検討したか」**を残すことを目的とします。
一般的には、1つのADRで1つの意思決定を扱い、短くシンプルに記述します。Markdownで書いてGitで管理する運用がよく使われます。
ADRで解決できること
- 既存メンバー：数か月後でも「なぜこの実装にしたか」を追える
- チーム全体：過去の意思決定背景を共通認識として持てる
- 新メンバー：背景説明がドキュメント中心になり、キャッチアップしやすい
フォーマットの選択肢
ADR関連の文書には複数のスタイルがあります。今回は次の3つを比較しました。
Nygard形式
Michael Nygardが提唱した、いわゆるオリジナルのADRスタイルです。
基本は次の4項目です。
- Status：承認済み・検討中などの状態
- Context：決定が必要になった背景
- Decision：何を決めたか
- Consequences：影響・トレードオフ
まずは習慣化したい、小規模で軽量に始めたい場合に向いています。
MADR（Markdown Architectural Decision Records）
Nygard形式を発展させたMarkdownベースのテプレート群です。
特徴は、検討した選択肢を構造的に残しやすいことです。
RFCスタイル
提案→レビュー→承認のプロセスを強く意識した文書スタイルです。
大きな変更や影響範囲が広いテーマで有効です。
※RFCはADRの完全な代替というより、ADR前段の合意形成文書として併用されるケースもあります。
フォーマットを比較する
フォーマットを選ぶにあたり、まず自チームの状況と課題を整理しました。
チームの状況
- 小規模なAndroidチーム
- ADRの導入経験はなく、これから文化として根付かせていく段階
- 書く負担が高いと習慣化する前に定着しないリスクがある
- 将来的にAIを活用したADRの検索・解析も視野に入れている
チームの課題
- 「なぜこの実装にしたのか」が後から追えないことがある
- 新メンバーへの意思決定の背景の引き継ぎが難しい
この課題を解決するために、以下の5軸でフォーマットを比較しました。
- 書くコストの低さ：迷わず書けるか・負担になりすぎないか
- 「なぜ」が残せるか：意思決定の背景・理由の記述しやすさ
- 却下した選択肢が残せるか：「他の案も検討した」が伝わるか
- 初見での読みやすさ：新メンバーが読んでも理解しやすいか
- AI可読性：構造化されていてAIが解釈しやすいか
※評価は相対比較（◎ > ○ > △）です。
| 比較軸 | Nygard | MADR | RFC |
|---|---|---|---|
| 書くコストの低さ | ◎ | ○ | △ |
| 「なぜ」が残せるか | ○ | ◎ | ◎ |
| 却下した選択肢が残せるか | △ | ◎ | ◎ |
| 初見での読みやすさ | ◎ | ○ | △ |
| AI可読性 | ○ | ◎ | ○ |
小規模チームでの意思決定の記録という用途にはRFCはやや重く、NygardとMADRに絞って検討しました。
フォーマットの選定
比較の結果、MADR Minimalをベースにする方針が自チームに適していると考えました。
重視したのは次の3点です。
- メンバーが迷わず書けるか
- 書いた本人以外が意思決定の背景と理由を理解できるか
- 後から仕様を振り返るときに実際に役立つか
チームの課題を解決するには、背景だけでなく却下した選択肢とその理由まで記録することが重要と考えました。
Nygard形式でも記述は可能ですが、運用次第で粒度にばらつきが出やすい懸念があります。
MADRは「検討した選択肢」を構造的に残しやすく、より適していると判断しました。
また、詳細項目を増やしすぎると書く負担が上がり、定着前に失速するリスクがあります。
そのため、まずはMADR Minimalをベースに始め、必要に応じて項目を追加する方針にしました。
実際に書いてみた
選定したMADR Minimalをベースに、進行中の案件に対して試しにADRを作成してみました。
題材は「コンテキスト依存での通知表示制御」です。
ユーザー操作の連続性を損なわずに情報提示を行う必要があり、複数の実装アプローチを比較検討しました。
今回の試行では、MADR Minimalの必須項目をベースにしつつ、チーム運用に必要な項目（変更概要、将来の検討事項）を追加して記録しています。
実例（一部抜粋）
前提
- 制御条件は設定ファイルで切り替え可能にする
- 判定は端末状態や利用環境に依存し結果に揺らぎがあることを許容する
- 対象条件では、表示取得処理全体を制御対象にする
決定事項（要約）
- 表示制御用フラグを追加
- 判定結果キャッシュを導入
- 判定処理の完了を待って後続処理を実行する方式を採用
- 「判定の実施」と「機能モード遷移」の責務を分離
- 判定失敗時のフォールバック動作を定義
検討した選択肢（抜粋）
| 方式 | 採否 | 理由（要約） |
|---|---|---|
| 非同期APIを新設して待ち合わせ | 不採用 | 既存処理と重複しやすく、導入コストが増える |
| 既存のイベント連携に統合 | 不採用 | ライフサイクル起点の処理と整合を取りにくい |
| 既存更新処理へ完了通知を追加 | 採用 | 既存ロジックを活かしつつ変更を最小化できる |
この実例で特に有効だったのは、採用理由だけでなく不採用理由も残せたことでした。
比較しながら書くことで判断軸が明確になり、後から見返したときにも意図を再現しやすくなると感じています。
まとめと今後の課題
今後の課題
フォーマットを決めるだけでは、ADRは定着しないはずです。
ここからは、まだ運用前の段階として考えている課題と対応案を整理します。
陳腐化をどう防ぐか（仮）
実装が変わってもADRが更新されないと、誤った前提を残してしまう可能性があります。
ただし、更新ルールを厳密にしすぎると運用負荷が上がり、結果的に続かない懸念もあります。
現時点では、次のような運用が現実的かもしれないと考えています。
- 実装変更でADRの前提に影響しそうな場合は、関連ADRを見直す
- 変更規模に応じて、既存ADRの修正か新規ADR追加かを判断する
- PRとADRの紐づけ運用は、まずは無理のない範囲で試し、負荷を見ながら調整する
AIを活用した可能性（仮）
MADRのような構造化フォーマットは、将来的にAIで検索・参照しやすい可能性がありますが、一方で、現時点ではまず「継続して書けること」が優先です。
そのため、最初は運用を安定させ、一定の蓄積ができてからAI活用を試すのがよさそうです。
まとめ
今回の検討を通じて、自チームへの導入フォーマットとして MADR Minimalベース が現実的だと考えています。
- 却下した選択肢と判断軸を構造的に残せる
- 必須項目を絞って、書く負担を抑えやすい
- 必要に応じて項目を追加できる柔軟性がある
ADRの正解は1つではありませんが、だからこそ自分たちのチームに合う形を一度言語化してみる価値は大きいと感じました。
この記事が、みなさんのチームでADR導入やフォーマット見直しを検討するきっかけになれば嬉しいです。
参考リンク（公式・原典）
- Michael Nygard, Documenting Architecture Decisions
https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions - MADR 公式
https://adr.github.io/madr/ - MADR Minimal template
https://github.com/adr/madr/blob/develop/template/adr-template-minimal.md - RFC（Request for Comments）概要
https://en.wikipedia.org/wiki/Request_for_Comments