アーキテクチャ・デシジョン・レコードの勧め

庄司です。

Michael Nygard 氏は「DOCUMENTING ARCHITECTURE DECISIONS」で、特にアジャイル開発では最初の時点でアーキテクチャが決まることはなく、また包括的なドキュメンテーションには価値がなく、小さなピースのドキュメントが全てのステークホルダーに必要となるため「アーキテクチャ・デシジョン・レコード (ADR: architecture decision record)」と呼ばれるドキュメントを提案しています。

その後、ADR は 2022年の InfoQ のトレンドレポートで「アーリーアダプタ」の位置を獲得し、さらに「Fundamentals of Software Architecture (邦題: ソフトウェアアーキテクチャの基礎)」の中にも解説されています。

この記事では、「ソフトウェアアーキテクチャの基礎」に書かれていることをベースに、ADR の概要を説明します。

ADR とは、特定のアーキテクチャ決定を短いテキストファイルで表したものです。Markdown フォーマットで記述されることが多いようです。

最初の投稿記事では、次のセクションが提案されています。

• タイトル (title)
• ステータス (status)
• コンテキスト (context)
• 決定 (decision)
• 影響 (consequences)

「ソフトウェアアーキテクチャの基礎」では、次の2つの追加を推奨しています。

• コンプライアンス (compliance)
• 備考 (notes)

ADR には重複のない連番を振り、タイトルには連番を含めた。短い名前をつけます。例えば、「ADR 9：マルチテナント統合のためのLDAP」のようにです。

ステータスは、「提案済み」、「承認済み」、「破棄」のいずれかになります。

例えば、次のようになります。

ADR 3
ステータス: 破棄。9 に伴い。

ADR 9
ステータス: 承認済み。3 を破棄。

ADR 3 と ADR 9 との間にリンクと履歴があることで、アーキテクチャの変更をトレースし経緯を理解できます。

どのような状況で決定 (デシジョン) を迫られているかを明確にします。

このセクションはさらに、アーキテクチャを文書化する方法にもなります。

このセクションには、技術的、政治的、社会的、およびプロダクトの現場を含む、プレイ中の原動力について記述します。これらの力はおそらく引っ張り合っているので、そのように登場させる必要があります。

このセクションの言語は、価値中立的です。単に事実を記述するだけです。

決定は、受動的にではなく、非常に肯定的かつ命令的に記述します。

影響のセクションでは、決定を適用した後のコンテキストについて説明します。アーキテクチャの決定には、他のアーキテクチャとのトレードオフがあるでしょう。つまり「肯定的な」ものだけでなく、そうした内容も含めます。個別の決定が肯定的、否定的、中立的な結果となるかもしれませんが、それら全ての決定が将来のチームやプロダクトに影響します。

コンプライアンスのセクションでは、決定したアーキテクチャの評価、管理のためのテスト内容、テストする場所、テストの実行方法などを記述します。例えば、Java を使用したレイヤードアーキテクチャの場合に、あるレイヤーのアーキテクチャを決定した場合は、ArchUnit をどのように使用して評価するのかというようなことになります。

ADR に関するさまざまなメタデータを記述します。

• オリジナルの著者
• 承認日
• 承認者
• 置き換え日
• 最終更新日
• 変更点
• 最終更新内容

文書全体は、1ページまたは2ページに収まるようにします。

プログラミング言語について等、ADR のサンプルのいくつかが GitHub にあります。

プロダクト開発は、チームが長い時間をかける旅路のようなものです。時間の経過とともに、ある時点で決定したアーキテクチャを変更したくなったり、実際変更することになる場合も少なくありません。このような場合に、過去にどのような理由、経緯で、またどのようなトレードオフの検討の元に決定したのかを全てのステークホルダーに提供する ADR はアジャイル開発プロセスにおいても価値のあるドキュメントになります。

• Architectural Decision Records