アーキテクチャ決定記録（ADR）は、製品またはエコシステムに関連する単一の決定を捉えて 説明する短い文書です。文書は短く、数ページ程度にし、決定、その決定を 下した文脈、および重要な影響を含めるべきです。決定が変更された場合でも 修正するのではなく、後継の決定へのリンクを付けるべきです。

ほとんどの文書と同様に、ADRを書くことには2つの目的があります。1つ目は 決定の記録として機能し、数ヶ月または数年後に人々が システムがなぜそのように構築されているのかを理解できるようにすることです。しかしおそらく さらに価値があるのは、それらを書く行為が思考を明確にするのに役立つこと、 特にグループで作業する場合です。重要な文書を書くことは しばしば異なる視点を浮き彫りにし、それらの違いを 議論し、 hopefully 解決することを強いることになります。

一般的なルールは、ニュース記事でよく使われる「逆ピラミッド」スタイルの 書き方に従うことです。重要な内容を最初に置き、詳細は 記録の後半に回すことが鍵です。

一般的なアドバイスは、適用されるコードベースのソースリポジトリに 決定記録を保管することです。保管場所として一般的な選択肢は doc/adr です。これにより、コードベースで作業する人々が 簡単にアクセスできるようになります。同様の理由から、軽量マークアップ言語、 例えば Markdown で書くべきであり、コードと同様に簡単に読み、 diff できるようにします。ビルドタスクを使って、製品 チームの Web サイトに公開することができます。

製品リポジトリに保管することは、単一のコードベースよりも広い エコシステムをカバーする ADR には適しません。ADR を git に保管すると、開発者以外が扱いにくくなると感じる人もいます。

各記録は独自のファイルとし、ファイル名の一部として単調増加する 連番を付け、決定を捉えた名前を付けるべきです。 これにより、ディレクトリ一覧で読みやすくなります（例： “0001-HTMX-for-active-web-pages”）。

各 ADR にはステータスがあります。議論中は “proposed”、 チームが受け入れて有効になると “accepted”、 大幅に変更または置き換えられた場合は “superseded” となり、後継 ADR へのリンクを付けます。 ADR が一度受け入れられたら、再び開いたり変更したりするべきではなく、 代わりに後継とします。これにより、決定とそれがどれだけ長く 作業を支配したかの明確なログが得られます。

ADR には決定だけでなく、決定の簡単な根拠も含まれます。これには、 この決定が必要になった問題と、考慮されたトレードオフを 要約する必要があります。これらを考える良い方法は、パターンを書くときの 「力」の概念に従うことです。その一環として、検討されたすべての重大な代替案を 明示的にリストアップし、それぞれの長所と短所を記載することが価値があります。

あらゆる決定には結果があります。これらが根拠から明確に示唆される場合もありますが、 明示的なセクションで明確に述べる価値がある場合もあります。決定は通常、ある程度の 不確実性の下で行われるため、決定の確信度を記録しておくと便利です。これは、 チームが決定を再評価すべき製品コンテキストの変更を 言及する良い場所でもあります。

ADR は Advice Process で中心的な役割を果たします。 そこで ADR は決定を文書化するだけでなく、それらを書く行為が 専門知識と整合性を引き出すために使われます。この場合、ADR の形成時に集められた アドバイスも含めるべきですが、簡潔に保つために、ADR ではアドバイスを要約し、 アドバイスの完全な記録は別途保管する方が良いかもしれません。

ここで最も重要なのは簡潔さです。ADR を短く要点を絞ってください。 通常は1ページ程度です。補足資料がある場合は、リンクを貼ってください。

ADR はソフトウェアアーキテクチャにおける決定を記録する形式ですが、 短い決定記録を書くというより広い概念は、 他の文脈でも検討する価値があります。この種の決定ログは、 物事がなぜそのようになったのかを説明する上で価値ある歴史的記録となります。

Further Reading

Michael Nygard が “Architecture Decision Record” という用語を考案したのは、 2011 年の ADR 形式の記事 でした。彼は決定ログというアイデアを 生み出したわけではありませんが、決定自体に焦点を当てた軽量な文書の 必要性を主張しました。この点で彼は特に、 Phillipe Kruchten の決定レジスタ／決定ログに関する議論と、 ソフトウェアパターン の執筆スタイルに着想を得ました。彼の 記事は、このトピックについて書かれたほぼすべてのものよりも優れており、私が この記事を書いた唯一の理由は、それ以降のいくつかの発展を指摘するためです。

このサイトでは、Harmel-Law と Rowse and Shepherd の記事に ADR 形式の簡単な例があります。

adr-tools は ADR を 管理するためのシンプルなコマンドラインツールです。自身の一連の ADR を含んでおり、 この形式の良い例となっています。

Acknowledgements

Andrew Harmel-Law, Brandon Cook, David Lucas, Francisco Dias, Giuseppe Matheus Pereira, John King, Kief Morris, Michael Joyce, Neil Price, Shane Gibson, Steven Peh, and Vijay Raghavan Aravamudhan が社内チャットでこの投稿の草稿について議論しました。Michael Nygard は彼の 執筆の起源に関する背景を提供してくれました。