フレームワーク活用ガイドひとことで言うと#
個々のアーキテクチャ決定記録（ADR）を時系列で蓄積・管理し、プロジェクトの設計判断の歴史を組織の共有知識にする仕組み。「なぜこの技術を選んだのか」「当時どんな選択肢があったのか」を後から追跡可能にする。
押さえておきたい用語#
- ADR（Architecture Decision Record）
- 1つの設計判断を記録する単位ドキュメント。タイトル・コンテキスト・決定・結果の4要素で構成される。
- ADL（Architecture Decision Log）
- 複数のADRを時系列で管理するコレクション全体を指す。リポジトリの
docs/adr/ディレクトリに番号付きで格納するのが一般的。 - ステータス（Status）
- ADRの現在の状態。**Proposed（提案中）→ Accepted（採用）→ Deprecated（廃止）→ Superseded（後継に置換）**の遷移をたどる。
- コンテキスト（Context）
- その判断に至った背景・制約条件・前提を記述するセクション。当時のチーム規模、技術スタック、納期などが含まれる。
- 後継参照（Superseded By）
- あるADRが新しいADRに置き換えられたとき、新旧をリンクする仕組み。設計判断の進化の履歴を追跡可能にする。
ADLの全体像#
こんな悩みに効く#
- 「なぜこのフレームワークを選んだのか」を知っている人が退職してしまった
- 新メンバーが過去の設計判断の経緯を理解するのに数週間かかる
- 同じ設計議論が半年ごとに繰り返される
- 技術負債の返済判断をするとき、当時の制約条件がわからない
基本の使い方#
チームで統一したテンプレートを決め、リポジトリに配置する。
- タイトル:
ADR-NNN: 〇〇を採用するの形式で、判断内容を1行で表す - ステータス: Proposed / Accepted / Deprecated / Superseded のいずれか
- コンテキスト: 判断に至った背景（ビジネス要件・技術制約・チーム状況）
- 決定: 何を選んだか、なぜそれを選んだかを明記
- 結果: この判断によって予想されるプラスとマイナスの影響
すべての小さな判断を記録する必要はない。以下の基準で選別する。
- 技術スタック（言語、フレームワーク、DB）の選定
- アーキテクチャパターン（マイクロサービス、モノリスなど）の採用
- 外部サービスやSaaSの導入判断
- セキュリティやコンプライアンスに関わる設計方針
- 判断基準: 「6か月後に理由を聞かれそうか？」と考える
ADLはコードに近い場所に置くことで、参照されやすくなる。
docs/adr/ディレクトリに0001-rest-api-adoption.mdのように番号付きで格納- PRと一緒にADRを提出し、コードレビューの一部としてレビューする
README.mdやdocs/adr/index.mdに全ADRの一覧を自動生成する- 既存のADRを変更するのではなく、新しいADRを起こして
Supersedes: ADR-003とリンクする
四半期に1回、ADLを棚卸しして古くなった判断を見直す。
- ステータスが
Acceptedのまま実質的に使われていない判断はないか - コンテキストが大きく変わった判断はないか（チーム規模の変化、新技術の登場など）
- 棚卸しの結果、見直しが必要なADRは新しいADRで更新する
- ADLの棚卸し自体もカレンダーに入れて習慣化する
具体例#
従業員60名のフィンテック企業。認証基盤の選定で「Auth0」「Firebase Auth」「自前実装」の3択を検討していた。テックリードが判断を下したが、1年後にテックリードが退職。後任が「なぜAuth0を選んだのか」を理解するのに3週間かかった。
この反省からADLを導入。ADR-012として認証基盤の決定を記録した。
ADR-012のコンテキスト欄:
- 金融規制でデータの国内保管が必要
- 開発チーム4名でセキュリティ専門家はいない
- 6か月以内にSOC2取得が経営目標
決定欄: Auth0を採用。国内リージョン対応、SOC2レポート提供、MFA標準搭載が決め手。Firebase Authは国内リージョン非対応で除外。自前実装はチームにセキュリティ専門家がいないため除外。
2年後、Auth0の料金が月額$2,400→$4,800に上がり見直しが発生。新テックリードがADR-012を読み、当時の判断理由を30分で把握。コンテキストが変わった点（チームが12名に拡大、セキュリティエンジニアが入社）を踏まえ、ADR-028「認証基盤をCognitoに移行する」を起票。ADR-012のステータスを Superseded by ADR-028 に更新した。
従業員200名のSaaS企業。エンジニアの採用を年30名ペースで進めていたが、新メンバーが「なぜこの設計なのか」を理解するまでの期間が平均6週間かかっていた。Slackの過去ログを遡ったり、在籍者に口頭で聞いたりするのが主な情報源だった。
ADLを導入し、過去2年間の主要な設計判断を23件遡って記録した。
ADL構成:
docs/adr/0001-monorepo-adoption.md— モノレポ採用の理由docs/adr/0005-graphql-over-rest.md— GraphQL選定の経緯docs/adr/0012-event-driven-architecture.md— イベント駆動への移行理由- （以下20件）
オンボーディングの最初の1週間に「ADLを読む」をタスクに組み込んだ。新メンバーからは「なぜこうなっているのかが文書で追えるので、質問する前に自分で理解できる」というフィードバック。
6か月後の計測で、新メンバーが独力でPRを出せるまでの期間が6週間→3.5週間に短縮。既存メンバーの「設計経緯を説明する」時間も月平均12時間→4時間に減少した。
プロダクト歴7年のECプラットフォーム。フロントエンドがjQuery＋サーバーサイドレンダリングで構築されており、React移行の議論が2年間繰り返されていたが、毎回「工数が大きすぎる」で見送られていた。
ADL導入後、過去の関連ADRを時系列で並べたところ、議論の変遷が見えた。
| ADR | 時期 | 判断 | 当時のコンテキスト |
|---|---|---|---|
| ADR-003 | 2019年 | jQuery採用 | チーム3名、SPA不要 |
| ADR-011 | 2021年 | React移行を見送り | チーム5名、移行コスト3か月 |
| ADR-018 | 2023年 | 部分的Vue導入を見送り | 2つのFWの共存が複雑 |
コンテキストの変化を整理すると:
- チームは3名→15名に拡大（React経験者が8名）
- jQueryでの新機能開発速度がReact対比で推定40%遅い
- 採用面接でjQueryスタックが敬遠されるケースが月3件
この分析を基にADR-025「段階的React移行」を起票。過去の見送り理由と現在のコンテキストの差分を明記したことで、CTOの承認が1週間で下りた。「2年間同じ議論を繰り返していた問題がADLで解決した」とチームから評価された。
やりがちな失敗パターン#
- ADRを書くのが面倒で結局書かない — テンプレートを簡潔にし、コンテキスト・決定・結果の3つだけ書けば十分。完璧な文書より「存在する記録」の方が100倍価値がある
- 既存のADRを直接編集してしまう — ADRは不変（イミュータブル）が原則。変更が必要なときは新しいADRを起こして
Supersedesでリンクする。履歴が追えなくなると導入した意味がなくなる - コードと別の場所で管理する — Confluenceやnotionに書くと、コードの変更とADRの更新がズレる。コードリポジトリの
docs/adr/に置き、PRと一緒にレビューする - 全員がADLの存在を知らない — オンボーディング資料にADLへの導線を入れ、設計議論の場では「まず既存のADRを確認する」を習慣にする
まとめ#
ADLは、個々の設計判断（ADR）を時系列で蓄積し、プロジェクトの設計思想の歴史を検索可能な組織知に変える仕組み。コンテキスト（当時の背景）を明記することで、後から見たときに「なぜその判断をしたか」が追跡できる。判断の正しさよりも、判断の経緯を残すことに価値がある。半年後の自分も、3年後の後任も、ADLがあれば同じ議論を繰り返さずに済む。