ADR（Architecture Decision Record）とは？AI時代に重要度が急上昇している「決断のログ」
Claude Codeの情報を追っていると、たびたび出てくるのが「ADR」という言葉です。
最初は、
また新しいIT用語か……
と思いました。
ですが調べてみると、これは単なる技術用語ではなく、
「人間とAIが一緒に開発する時代の必須ツール」
と言ってもいいくらい重要な概念でした。
今回はADRについて整理してみます。
ADRとは何か？
ADRは、
Architecture Decision Record
の略です。
日本語にすると、
「アーキテクチャ決定記録」
とか
「設計判断の記録」
という意味になります。
難しく聞こえますが、
本質は非常にシンプルです。
ADRとは、
「なぜその設計にしたのかを書き残すメモ」
です。
例えば開発中、
こんな選択肢が出てきます。
データベースはMySQLにするかPostgreSQLにするか
認証はGoogleログインを採用するか
画像は自社サーバーに置くかクラウドに置くか
システム開発では、
こうした分かれ道が何度も登場します。
そして重要なのは、
何を選んだかではなく、なぜそれを選んだか
です。
なぜ記録が必要なのか
開発を続けていると、
数ヶ月後にはほぼ確実にこうなります。
あれ？
本当にこうなります。
しかも設計した本人ですら忘れます。
例えば、
画像保存をAWS S3にしたとします。
半年後に新しいメンバーが入ってきます。
すると、
自社サーバーに保存した方が安くないですか？
という話が出ます。
一見もっともらしく聞こえます。
しかし実際には、
過去に散々検討した結果、
容量問題や運用コストの関係でAWSを採用したかもしれません。
ADRがなければ、
同じ議論を何度も繰り返すことになります。
だから決断の理由を残しておく。
これがADRです。
ADRは議事録に近い
ADRを理解する時は、
技術文書というより
議事録
として考えると分かりやすいです。
例えばこんな感じです。
タイトル
画像保存にAWS S3を採用する
背景
ユーザー数増加に伴い、自社サーバーの容量管理が限界に近づいている
決定事項
画像保存先はAWS S3とする
理由
スケーラビリティが高く運用負荷が小さいため
デメリット
ランニングコストが発生する
こんな感じで十分です。
大事なのは、
技術的な正解を書くことではなく、
その時の意思決定プロセスを残すこと
です。
なぜClaude Code界隈で話題なのか
ここが一番面白いところです。
昔のADRは、
人間同士で共有するためのものでした。
しかしAI時代になると意味が変わります。
Claude CodeのようなAIエージェントは、
プロジェクト内のファイルを読みながら開発します。
つまり、
ADRも普通に読めるわけです。
例えば、
あなたがこう指示します。
画像アップロード機能を追加して
ADRが無い場合。
AIは、
画像はローカルサーバーに保存しておきました
と実装するかもしれません。
しかしADRがある場合。
AIは先にADRを読みます。
すると、
このプロジェクトは画像保存をAWS S3に統一する方針なのか
と理解します。
その結果、
最初から正しい方向でコードを書いてくれるようになります。
AIにとってADRは「会社のルールブック」
人間の場合、
長くプロジェクトにいると暗黙知が増えます。
例えば、
このプロジェクトはAWS優先
認証は必ずAuth0
API設計はREST形式
みたいなルールです。
ベテランメンバーは知っています。
でもAIは知りません。
だからADRを書く。
するとAIは、
暗黙知を明文化されたルールとして理解できます。
言い換えると、
ADRは
AI向けのプロジェクト憲法
みたいなものです。
対話型AIより自立(エージェント)型AIの利用時に重要度が増す
対話型AIだと、
基本的には人間が細かく指示を出します。
しかしClaude Codeのようなエージェント型AIは違います。
かなり自律的に判断します。
だからこそ、
事前に判断基準を与えておく必要があります。
その判断基準を記録する仕組みがADRです。
AIが賢くなるほど、
逆にADRの価値は上がっていきます。
ADRは「未来の自分への説明書」
ADRを難しく考える必要はありません。
結局のところ、
ADRとは
「なぜそう決めたのかを忘れないためのメモ」
です。
そして今は、
そのメモを読む相手が人間だけではなくなりました。
未来の自分。
新しく入るチームメンバー。
そしてClaude CodeのようなAIエージェント。
ADRは、
人間とAIが同じ設計思想を共有するための共通言語になりつつあります。
Claude Code界隈で頻繁に登場するのも、そのためです。
