コメントで教わった「ADR」についての整理
はじめに：コメントから始まった学び
先日、プロジェクト管理ツール選定について記事を書きました。
記事では、RedmineとAzure DevOpsが混在する状況で、Linearへの統一を検討している過程を書いたのですが、コメントで「ADRを書くといいと思います」とアドバイスをいただきました。
正直に言うと、ADRという言葉を初めて知りました。
「ADRって何？」と思いながら調べてみたところ、「これ、もっと早く知りたかった」と思える内容だったので、同じように初めて聞いた方向けに学んだことをまとめます。
ADRとは - 意思決定の記録
ADRは「Architecture Decision Record（アーキテクチャ決定記録）」の略で、技術的な意思決定をした理由や背景を記録しておくドキュメントのことです。
2011年にMichael Nygardがブログ記事「Documenting Architecture Decisions」で提唱した概念です。
基本構成
# [番号]. [決定のタイトル]
## Status
提案中 | 承認済み | 廃止 | 代替: ADR-XXX
## Context
なぜこの決定が必要になったのか？
どんな問題や課題があったのか？
## Decision
何を選択したのか？
## Consequences
この決定によるメリット・デメリットは何か？
意外とシンプルですよね。
なぜADRが必要なのか
半年後、誰かが「なんでこのツール使ってるんだっけ？」と疑問に思ったとき、よくあるのがこんな状況：
- Slackの履歴を漁る → 200件ヒット、どれが本質か分からない
- Google Docsで議事録を探す → 10個見つかる、どれが最終決定か不明
- 当時の担当者に聞く → 記憶が曖昧
ADRがあれば、1つのファイルを読むだけで以下が分かります：
- 何を選んだのか
- なぜそれを選んだのか
- 他に何を検討したのか
- 主なトレードオフは何か
議事録とADRの違い
「それって議事録じゃダメなの？」という疑問があると思います。実は役割が違います。
議事録（プロセスの記録）
14:00 Aさん: Linearいいと思います
14:05 Bさん: でも英語UIですよね
14:10 Cさん: Jiraは？
14:15 Aさん: Jiraは高いです
...
時系列で何が起きたかを記録。
ADR（決定の記録）
## Decision: Linearを採用
## 理由
- シンプル（Azure DevOpsの反省から）
- コスト妥当（年$3,000 vs Redmineメンテ120万円）
- 組織横断可視化が可能
## 却下した選択肢
- Jira: 高価で複雑
- GitHub Projects: レポート機能不足
なぜそう決めたのかを構造化して記録。
両方必要ですが、未来の自分たちへの説明としてはADRの方が適しています。
実践：私の記事をADRにすると
先日書いた記事の内容を、ADR形式にするとこうなります：
# 001. プロジェクト管理ツールの統一検討
Date: 2026-01-22
## Status
提案中（Linear評価中）
## Context
- 30人規模の組織で、部署ごとにツールが分断
- A部署: Redmine（DBメンテができていない状態）
- B部署: Azure DevOps（多機能すぎて使いこなせていない）
- 組織横断での生産性可視化とPDCAが困難
制約条件:
- 予算: 年間$2,880〜$5,040程度
- 移行時の生産性低下を最小限にしたい
- Azure DevOpsの「使いこなせない」経験がある
## Decision
Linearを候補として評価する
理由:
- シンプルで学習コストが低い
- 組織横断の可視化に必要な機能は揃っている
- Azure DevOpsほど複雑ではない
- コスト的にもRedmineメンテナンスより安価
他の候補と比較:
- Jira: 機能充実だが高価で複雑
- GitHub Projects: 追加コストほぼゼロだが、レポート機能が弱い
- Azure DevOps継続: すでに「使いこなせていない」実績あり
## Consequences
メリット:
- ツール統一により組織横断での可視化が可能
- シンプル設計により「使いこなせない」リスク低減
- トータルコスト削減の可能性
デメリット・リスク:
- 新ツールへの慣れによる一時的な生産性低下
- 既存のカスタマイズやプラグインが使えなくなる
- 英語UIのため慣れるまで時間がかかる可能性
未解決の課題:
- 実際の運用での使用感が不明
- 移行作業の具体的な工数見積もりが必要
記事で書いていた内容が、そのままADRの構成要素になっていることが分かります。
Git管理とディレクトリ構成
ADRはGitで管理するのが一般的です。
project-root/
├── docs/
│ └── adr/
│ ├── 0001-choose-database.md
│ ├── 0002-use-microservices.md
│ └── 0003-select-pm-tool.md
ファイル名は番号-スラッグ形式。一覧を見るだけで「どんな決定があったか」が分かります。
形骸化を防ぐには
ADRについて調べていく中で、「こういうドキュメントは形骸化させないことが重要」だと考えました。
よくある失敗パターン
-
テンプレートが複雑すぎる
- 20個のセクションを埋める必要がある
- 誰も書かなくなる
-
完璧を求めすぎる
- 全情報を網羅しようとする
- 3時間かかる
- 結果、年に1-2回しか書かれない
-
読まれない
- 書きっぱなしで終わる
- 価値が実感されない
実践的な対策
1. 5-10分で書けるテンプレート
# 0003. Linearを採用
## Context
- RedmineとAzure DevOpsが混在
- 統一したい
## Decision
Linearを採用
- シンプル
- コスト: 年$3,000
## Consequences
良: シンプル、安い
悪: 英語UI、カスタマイズ少ない
詳細: [MTG議事録](link)
5-10分で書けなければ何かが間違っています。
2. 読まれる仕組みを作る
- オンボーディング時: 新メンバーに読んでもらう
- 疑問が出た時: 「なんでこうなってるの？」→「ADR-0003見て」
- 定期レビュー: 四半期に1回、見直す
3. 生きたドキュメントにする
## Status
承認済み (2026-01-22)
## 追記 (2026-04-15)
3ヶ月使ってみて分かったこと:
- 英語UIは思ったより問題なかった
- ただしカスタムフィールドが足りず、結局スプレッドシート併用
一度書いたら終わりではなく、継続的に価値が生まれる仕組みにします。
4. 強制しない
文化は強制からは生まれない。便利さの実感から生まれる。
まず1つ書いてみて、チームに共有。誰かが「これ便利だね」と感じたら自然に広がります。
完璧主義の罠
「情報をきちんと網羅したADR作るのって大変じゃない？」という疑問があると思います。
実は、ADRは100%網羅する必要はありません。
6ヶ月後の新メンバーが最初に知りたいのは：
- 何を選んだのか
- なぜそれを選んだのか
- 他に何を検討したのか
- 主なトレードオフは何か
これだけで80%の疑問は解決します。
残りの20%（「予算の詳細な議論は？」など）は、必要になってから議事録を見ればいい。
比較：完璧主義 vs 実用主義
【完璧主義】
作成時間: 3時間
完成度: 100%
書かれる頻度: 年に1-2回
→ 結果: 大半の決定が記録されない
【実用主義】
作成時間: 5-10分
完成度: 70-80%
書かれる頻度: 月に2-3回
→ 結果: 大半の決定が記録される
70%の情報がある方が、100%の情報がないより遥かにマシです。
Googleのデザインドキュメント文化
参考として、Googleには「Design Docs」という文化があります。これもADRに近い考え方です。
彼らの特徴：
- 完璧を求めない - 箇条書きレベルでもOK
- 議論のたたき台 - 書いてから議論する
- 必須ではない - 大きな変更の時だけ
- レビュー文化 - コメントで議論、改善する
"A design doc is not a spec. It doesn't need to be perfect. It's a tool for discussion."
（デザインドキュメントは仕様書ではない。完璧である必要はない。議論のためのツールだ）
まとめ
ADRを知らなかった私が学んだこと
- ADRは意思決定の記録 - 議事録とは役割が違う
- 5-10分で書ける - 完璧を目指さない
- 70%の情報で十分 - 残りは議事録へのリンク
- 生きたドキュメント - 後から追記・修正できる
- 便利さの実感が鍵 - 強制しても続かない
私が書いたプロジェクト管理ツール選定の記事は、実はすでにADR的な構成になっていました。足りないのは「詳細な議論の全記録」ですが、それは最初から必要ありません。
未来の自分たちへの手紙として、最小限の情報を残す。
それがADRの本質だと理解しました。
参考資料
ADRの基礎
- Documenting Architecture Decisions - Michael Nygard (2011) - ADRを提唱した原典
- Architectural Decision Records - adr.github.io - 公式サイト、テンプレート集
- ADR Templates - 様々なテンプレート
実践例・文化
- Design Docs at Google - Googleのデザインドキュメント文化
- Why you should be using architecture decision records - Red Hat
Discussion
四半期毎くらいにどうなっているかの記事を期待しています。
特に学びがどう変わったかあたり。。。