「なんでこれ選んだんだっけ?」を解決する - ADRという考え方

先日、Zennにプロジェクト管理ツールの選定について記事を書いたところ、コメントで「ADRを書くといいと思います」とアドバイスをいただきました。

正直に言うと、その瞬間まで私はADRという言葉を知りませんでした。

「ADRって何？」

「またよく分からない横文字が出てきた...」

そう思いながら調べ始めたのですが、理解してみると 「これ、もっと早く知りたかった」 と思える内容でした。この記事では、ADRを知らなかった私が学んだことを、同じように初めて聞いた方向けにまとめます。

ADRとは何か

ADRは「Architecture Decision Record（アーキテクチャ決定記録）」の略です。

簡単に言うと、技術的な意思決定をした理由や背景を記録しておくドキュメントのこと。2011年にMichael Nygardがブログ記事「Documenting Architecture Decisions」で提唱した概念で、ソフトウェアエンジニアリングのコミュニティでは比較的知られています。

基本的な構成

通常、こんな項目で構成されます：

# [番号]. [決定のタイトル]

## Status
提案中 | 承認済み | 廃止 | 代替: ADR-XXX

## Context
なぜこの決定が必要になったのか？
どんな問題や課題があったのか？

## Decision
何を選択したのか？

## Consequences
この決定によるメリット・デメリットは何か？

これだけです。意外とシンプルですよね。

なぜADRが必要なのか

半年後、誰かが「なんでこのツール使ってるんだっけ？」と疑問に思ったとき、どうなるでしょうか。

よくあるパターン：

ADRがあれば、1つのファイルを読むだけで以下が分かります：

議事録との違い

「それって議事録じゃダメなの？」という疑問を持つ方もいると思います。

実は、ADRと議事録は役割が違います。

議事録（プロセスの記録）

14:00 Aさん: Linearいいと思います
14:05 Bさん: でも英語UIですよね
14:10 Cさん: Jiraは？
14:15 Aさん: Jiraは高いです
...（会話が続く）

時系列で何が起きたかを記録

ADR（決定の記録）

## Decision: Linearを採用

## 理由
- シンプル（過去の反省から）
- コスト妥当
- 組織横断可視化が可能

## 却下した選択肢
- Jira: 高価で複雑
- GitHub Projects: レポート機能不足

なぜそう決めたのかを構造化して記録

6ヶ月後に読むなら、どちらが分かりやすいでしょうか？

両方必要ですが、未来の自分たちへの説明としてはADRの方が適しています。

実践的な運用方法

Git管理

ADRはGitで管理するのが一般的です。

project-root/
├── docs/
│   └── adr/
│       ├── 0001-choose-database.md
│       ├── 0002-use-microservices.md
│       └── 0003-select-pm-tool.md

ファイル名は番号-スラッグ形式が多いです。一覧を見るだけで「どんな決定があったか」が分かります。

5分で書けるテンプレート

完璧を目指すと続きません。これくらいシンプルでOKです：

# 0003. Linearを採用

## Context
- RedmineとAzure DevOpsが混在
- 統一したい

## Decision
Linearを採用
- シンプル
- コスト: 年$3,000

## Consequences
良: シンプル、安い
悪: 英語UI、カスタマイズ少ない

詳細: [MTG議事録](link)

5-10分で書けなければ何かが間違っています。

形骸化を防ぐために

ADRについて理解を深めていく中で、ある疑問が湧きました。「こういうドキュメントって書くことを形骸化させないことが一番重要じゃないか？」と。

調べてみると、ADRが形骸化する典型的なパターンがありました：

よくある失敗

実践的な対策

1. ハードルを下げる

70%の情報で十分です。残りの30%は議事録へのリンクで補えます。

完璧より完成。完成より公開。

2. 読まれる仕組みを作る

書くだけでは意味がありません。以下のような場面で実際に使われる必要があります：

3. 生きたドキュメントにする

一度書いたら終わりではありません。

## Status
承認済み (2026-01-22)

## 追記 (2026-04-15)
3ヶ月使ってみて分かったこと:
- 英語UIは思ったより問題なかった
- ただしカスタムフィールドが足りず、結局スプレッドシート併用

継続的に価値が生まれる仕組みにします。

4. 強制しない

「全ての技術決定にADR必須！」とすると、形式だけのADRが量産されます。

文化は強制からは生まれない。便利さの実感から生まれる。

まず1つ書いてみて、チームに共有。誰かが「これ便利だね」と感じたら自然に広がります。

完璧主義の罠

「情報をきちんと網羅したADR作るのって大変じゃない？」

この疑問、ADR導入で多くの人が躓くポイントです。

現実的な考え方

実は、ADRは100%網羅する必要はありません。

6ヶ月後の新メンバーが最初に知りたいのは：

これだけで80%の疑問は解決します。

残りの20%（「予算の詳細な議論は？」など）は、必要になってから議事録を見ればいいのです。

比較：完璧主義 vs 実用主義

【完璧主義】
作成時間: 3時間
完成度: 100%
書かれる頻度: 年に1-2回

結果: 大半の決定が記録されない

【実用主義】
作成時間: 5-10分
完成度: 70-80%
書かれる頻度: 月に2-3回

結果: 大半の決定が記録される

70%の情報がある方が、100%の情報がないより遥かにマシです。

私の場合

先日書いたプロジェクト管理ツール選定の記事、実はすでにADR的な構成になっていました。

足りないのは「詳細な議論の全記録」ですが、それは最初から必要ありません。

むしろ「完璧なADRを作ろう」と思った瞬間、誰も書かなくなって、何も記録されない方が問題です。

まとめ

ADRを知らなかった私が学んだこと：

「この人が書いている」と感じられる記事を目指していますが、技術的な判断プロセスを記録するADRも、似たような思想があると感じました。

未来の自分たちへの手紙として、最小限の情報を残す。

それがADRの本質だと理解しました。

関連書籍

アーキテクチャ設計や技術的意思決定についてさらに深く学びたい方には、以下の書籍がおすすめです。

参考資料

ADRの基礎

実践例

テンプレート