アーキテクチャデシジョンレコード（Architecture Decision Record: ADR）とは、プロダクトやエコシステムに関する重要なひとつの決定を記録および説明する簡潔な文書である。文書は短く、数ページ程度に収め、内容には決定事項、決定の背景、重要な影響を含めなければならない。決定を変更した場合は、文書を修正するのではなく、置き換えた決定にリンクしておく。

ほとんどの文書がそうであるように、ADRの作成にも2つの目的がある。まず、決定の記録である。数か月後あるいは数年後でもシステムが現在のように構築された理由を理解できる。だが、それよりも重要なのが、文書を書くことで考えが明確になる点である。グループの場合は特にそうだ。重要な文書を書くことで、異なる見解が浮かび上がってくる。こうした意見の違いについて議論し、できれば解消することが望ましい。

一般的なルールとして「逆ピラミッド」の書き方を踏襲する。これはニュース記事でよく使われる手法だ。最も重要なことを冒頭に配置し、詳細は記録の後半に配置する。

決定の記録はソースコードと同じリポジトリに保存することが推奨されている。保存ディレクトリは「doc/adr」が使われる。こうすることで、コードベースを扱うすべての人が容易に利用できる。同様の理由から、Markdownなどの軽量マークアップ言語で書くことが推奨されている。そのほうが読みやすく、コードと同じように差分が取れるからだ。ビルドタスクを利用して、プロダクトチームのウェブサイトに公開することも可能である。

ただし、複数のコードベースにまたがる広範なエコシステムのADRをプロダクトのリポジトリに保存するのは適していない。また、ADRをgitに保存すると非開発者が扱いにくいという意見もある。

各記録には個別のファイルを用意する。ファイル名には連番と記録内容を付ける。こうすれば、一覧表示したときに読みやすい（例：0001-HTMX-for-active-web-pages）。

ADRにはステータスがある。議論中は「proposed（提案済み）」、チームが承認してアクティブなものは「accepted（受け入れ済み）」、大幅に修正または上書きされたものは「superseded（廃止済み）」とする（置き換えたADRにリンクする）。一度ADRを受け入れたら、議論に戻したり変更したりすることは認められない。そのような場合は、廃止にするべきである。このようにすることで、明確な決定の履歴と作業に適用された期間を保持できる。

ADRに含まれるのは決定だけではない。決定に至った簡潔な理由も記載しておく。そこには決定が必要になった問題の要約と考慮したトレードオフを含める。これを考えるときには、パターンを書くときの「フォース」が参考になる。これを書くときには、検討したすべての代替案とそれぞれの長所と短所を明示的に列挙することが重要である。

すべての決定には影響が伴う。理由から読み取れるものもあるが、セクションを分けて明記しておいたほうがいい場合もある。決定は一定の不確実性の下で行われるため、決定の信頼度を記録しておくことは有用である。チームが決定を再評価すべきプロダクトの文脈の変更についても、ここに記載しておくといいだろう。

ADRはアドバイスプロセスにおいて中心的な役割を果たす。そこではADRは単に決定を文書化したものではなく、文書を作成することで専門知識を引き出し、関係者で認識を合わせる。本来ならばADRの作成中のアドバイスも記録するべきだが、ADRを簡潔に保つために、アドバイスの要約だけを記載し、詳細な記録は別途保存しておくといいだろう。

最も重要なのは簡潔さである。ADRは短く要点を押さえたものにする。通常は1ページ以内に収める。補足資料があれば、それらにリンクする。

ADRはソフトウェアアーキテクチャの決定を記録する形式だが、簡潔に決定を記録するという概念は他の分野でも検討すべきだろう。このような決定の履歴は、物事が現在のようになっている理由を説明するための歴史的記録になる。

さらに詳しく知るために

2011年、Michael NygardがADRの書式に関する記事で「アーキテクチャデシジョンレコード」という用語を提唱した。彼が「決定の履歴」というアイデアを考案したわけではないが、彼は決定の重要性と軽量な文書の必要性を強く主張した。この点については、Phillipe Kruchtenの決定目録と決定履歴（decision registers / decision logs）やソフトウェアパターンの書き方に影響を受けている。このテーマについては、彼の記事が他のどの文章よりも優れている。私が本記事を書こうと思ったのは、その後の展開を示したかったからだ。

本サイトでは、Harmel-LawおよびRowseとShepherdが執筆した記事のなかで、ADRの書式の実例を使っている。

adr-toolsはADRを管理するためのシンプルなコマンドラインツールである。このツール自体のADR一式も含まれているため、実例として参考になる。

謝辞

Andrew Harmel-Law, Brandon Cook, David Lucas, Francisco Dias, Giuseppe Matheus Pereira, John King, Kief Morris, Michael Joyce, Neil Price, Shane Gibson, Steven Peh, Vijay Raghavan Aravamudhanとは、本記事の草稿について社内チャットで議論を交わした。Michael Nygardからは彼が記事を書いた背景について説明を受けた。