フレームワーク活用ガイドひとことで言うと#
「なぜこの技術を選んだのか」「なぜこのアーキテクチャにしたのか」という重要な技術的意思決定を、背景・選択肢・結論の構造で記録し、チームの知識資産として残す手法。
押さえておきたい用語#
- コンテキスト（Context）
- この決定が必要になった背景、制約条件、課題を指す。ADRの中で最も重要な要素の一つ。
- ステータス
- ADRの現在の状態を示す値。提案中・承認済み・廃止・代替済みの4つが基本。
- 代替済み（Superseded）
- 新しいADRによってこの決定が置き換えられた状態。元のADRは書き換えず、新ADRへのリンクを記載する。
- 不変性（Immutability）
- 一度承認されたADRは内容を書き換えないという原則。過去の判断を正確に残すことに価値がある。
- トレードオフ
- ある選択をすることで得られる利点と、引き換えに受け入れる制約や欠点である。ADRでは必ず記録する。
ADRの全体像#
こんな悩みに効く#
- 過去の技術選定の理由がわからず、「なぜこうなっているのか」が誰にも説明できない
- アーキテクチャの変更提案に対して、過去の議論が蒸し返される
- 新しいメンバーがシステムの設計思想を理解するのに時間がかかる
基本の使い方#
すべての決定ではなく、重要な決定に絞ってADRを作成する。
- プログラミング言語やフレームワークの選定
- データベースやメッセージキューなどのインフラ選定
- アーキテクチャスタイル（モノリス、マイクロサービスなど）の選択
- 後から変更するコストが高い決定すべて
ポイント: 「後から変更が難しい決定」かどうかがADRを書くべきかの判断基準。
定型フォーマットに従って記録する。
- タイトル: 決定内容を簡潔に表す（例: 「メッセージキューにKafkaを採用する」）
- ステータス: 提案中 / 承認済み / 廃止 / 代替済み
- コンテキスト: この決定が必要になった背景と制約条件
- 決定: 何を選び、何を選ばなかったか
- 結果: この決定によって生じるメリット・デメリット・影響
ポイント: 特に**「コンテキスト」と「結果」が重要**。選択した事実だけでなく、なぜそう判断したかを残す。
ADRをソースコードと同じリポジトリに保存する。
docs/adr/ディレクトリに連番で管理（例:001-use-kafka-for-messaging.md）- プルリクエストでADRを追加し、チームレビューを経て承認する
- Wikiや外部ツールではなく、コードと一緒にバージョン管理する
ポイント: コードリポジトリに置くことで、コードの変遷とADRの変遷がリンクする。
書いたADRをチームの意思決定プロセスに組み込む。
- 新しいアーキテクチャ決定の前に、関連する既存ADRを確認する
- 状況が変わって決定を見直す場合、元のADRを「代替済み」にし、新しいADRを作成する
- オンボーディング時にADR一覧を読むことを推奨する
ポイント: ADRは不変の記録。過去のADRを書き換えず、新しいADRで「代替」する。
具体例#
ADR-005 認証基盤にAuth0を採用する（ステータス: 承認済み）
コンテキスト: ユーザー認証機能を実装する必要がある。MFA対応、OAuth2.0/OIDC準拠、SOC2対応が要件。開発チーム8名にセキュリティ専門エンジニアはゼロ。
検討した選択肢:
- Auth0: マネージドサービス。全要件を満たす。月額$500
- Keycloak: OSS。セルフホスト。機能は十分だが運用負荷が高い
- 自前実装: フルカスタマイズ可能だが、開発・運用コストが最も高い
決定: Auth0を採用する。理由はセキュリティ専門エンジニア不在でのリスク回避と、開発速度の確保。
認証機能の実装が推定3ヶ月から2週間に短縮。月額$500は自前運用のエンジニアリングコスト（推定月$8,000）より圧倒的に安かった。
状況: 20名のチームで年間4〜5名の新メンバーが加入。毎回「なぜPostgreSQLではなくDynamoDBなのか」「なぜモノリスではなくマイクロサービスなのか」を口頭で説明し、1人あたり2週間の説明コストが発生。
施策:
- 過去2年間の重要な技術決定を振り返り、ADR 15件を一括作成
docs/adr/に格納し、オンボーディングチェックリストに「ADR全件を読む」を追加- 新しい技術決定はADR作成をPRの必須条件に
ADRがオンボーディングの「最強の教材」になった。新メンバー3名がADRを読むだけで設計思想を理解し、オンボーディング期間は4週間→2週間に短縮。「なぜ」を聞く質問も月15件→3件に減少している。
状況: 2年前のADR-003で「リアルタイム性を重視してDynamoDBを採用」と記録。しかし現在はバッチ処理中心に変化し、DynamoDBのオンデマンドキャパシティが月30万円のコスト。
ADR-018 DynamoDBからAurora PostgreSQLへの移行（ステータス: 承認済み）:
- ADR-003を「代替済み」に変更し、ADR-018にリンク
- コンテキスト: ワークロードの変化（リアルタイム→バッチ中心）、DynamoDBの月額コスト高騰
- 決定: Aurora PostgreSQLに移行。リレーショナルなクエリが多く、コスト効率も改善
インフラコストが月30万円→月5万円に削減（年間360万円の削減）。ADR-003があったおかげで、当時の判断は正しかったが状況が変わったことを全員が納得した。
やりがちな失敗パターン#
- 些細な決定にもADRを書く — ライブラリの小さなバージョンアップなどにADRを書くと、数が膨れて読まれなくなる。後戻りが困難な重要決定に限定する
- 結論だけ書いて背景を省略する — 「Kafkaを使う」とだけ書かれたADRは価値がない。なぜKafkaを選び、なぜRabbitMQを選ばなかったかまで記録する
- 書いたまま放置する — 状況が変わって決定が無効になっても更新されない。定期的なADRの棚卸しを行い、ステータスを最新に保つ
- ADRがWikiに分散する — Confluence、Notion、リポジトリと分散して管理すると検索できなくなる。コードリポジトリの1ディレクトリに集約すること
まとめ#
ADRは「技術的な意思決定の理由を未来の自分たちに伝える」ためのシンプルだが強力な手法。コンテキスト・決定・結果の3要素 を構造的に記録し、コードリポジトリで管理することで、チームの知識資産として長く活用できる。書くコストは1件30分程度だが、「なぜこうなっているのか」 を後から説明できる価値は計り知れない。