インフィニットループ 技術ブログ

2023年03月02日 (木)

著者 ： t-kono

設計 #ADR #開発

ADR – アーキテクチャ上の設計判断を記録しよう

はじめに

昨年、2022 年に「ソフトウェアアーキテクチャの基礎」[1] という書籍が出版されました。 これは今年、2023 年の 1 月 16 日に発表された「IT エンジニア本大賞2023」技術書部門ベスト10 に選ばれるなど、ソフトウェアエンジニアからの注目が多かった書籍であると言えるでしょう。

そこで紹介された アーキテクチャディシジョンレコード (Architectural Decision Records; ADR) という方法は、この書籍の評判が浸透するにつれ、目に耳にすることが多くなった印象があります。 本記事では、この ADR とはどのような方法であるのか、またそれに対する個人的な考察や雑感について、記述しています。

なお本記事における「判断」「決定」いずれの用語も、Decision の訳語であると解釈していただいて差し支えございません。 文脈や出典の都合上、言葉を使い分けているだけです。

ADR の概略

ADR とは『特定のアーキテクチャ決定を記述した短いテキストファイル』[1] です。 アーキテクチャ決定は、どのようなプロジェクトであれ、必ず行われていると考えて良いでしょう。 また、その決定の内容についても、多かれ少なかれ、きっと何らかの形式で文書化されているはずです。

そういった文書化の形式を ADR と名付けて認識し区別することにより、必要な機会に一貫性のある文書を作成する手続きを、運用に組み込めるようになります。 これは、上掲した「IT エンジニア本大賞2023」の大賞に選ばれた「良いコード／悪いコードで学ぶ設計入門」[2]の冒頭で述べられている、『真名ーすなわち正体を知覚できれば、正しく対処でき』るという発想に、近しいものを見出せるかもしれません。

アーキテクチャ決定

先述したように ADR とは、アーキテクチャ決定 (Architectural Decision; AD) を記述する、文書形式の１つです。 そこで ADR より先に、アーキテクチャ決定について記述します。

アーキテクチャ決定のステップ

wikipedia の Architectural Decision 記事[3] では、以下のようにステップが紹介されています。

  • 決定の識別 (Decision identification)
  • 決定を下す (Decision making)
  • 決定の文書化 (Decision documentation)
  • 決定の制定／施行 (Decision enactment/enforcement)
  • 決定の共有 (Decision sharing)

決定の識別においては、緊急性や重要性を評価します。 プロダクトバックログのような「アーキテクチャ決定のバックログ」を用意しておくと、いま決定を下す必要がないものを保留できます。 ADR は、下されたアーキテクチャ決定の文書化を行うときの、形式であると解釈できるでしょう。

下されたアーキテクチャ決定はソフトウェア設計に使用されるため、決定の制定／施行を通して、システムの資金調達・開発・運用を行うステークホルダーに伝えられ、受け入れられなければなりません。 また、多くのアーキテクチャ判断はプロジェクトにまたがって繰り返されるため、過去に下された決定の共有を行うことにより、良いものも悪いものも含めて、貴重な・再利用可能な資産となるはずです。

私見となりますが、決定の識別を行い「アーキテクチャ決定のバックログ」に追加する、というのは重要なアイデアであるように思います。 この問題にはアーキテクチャ決定が必要ではないか？という提起について、消極的になってはならず、忘れ去られてもならないと考えているためです。

アーキテクチャ上重要なもの

Michael Nygard の記事[4] において、ADR とは、アーキテクチャ上重要な (architecturally significant) 決定の記録であるとしています。 また、そのアーキテクチャ上重要な決定として、以下のものが挙げられています。†

  • 構造 (structure)
  • 非機能特性 (non-functional characteristics)
  • 依存関係 (dependencies)
  • インターフェース (interfaces)
  • 構造手法 (construction technique)

また、この記事の末尾にある Philipe Kruchten の書籍[5] においては、以下の記述があります。
（英文は [5] の 16 章より引用、邦文は筆者による翻訳）

…, that the architect focuses only on the architecturally significant requirements and the corresponding architecturally significant design decisions (see Figure 16.1).

…、 アーキテクチャ上重要な要件と、それに対応するアーキテクチャ上重要な設計判断とのみに、アーキテクトは焦点を当てます（下図参照）。

Figure 161

（図16.1. 上画像も [5] の 16 章；オライリー学習プラットフォーム https://learning.oreilly.com/ より引用）

Architects need to consider and balance the impact along a number of different dimensions when making architectural decisions. This forces the architects to constantly make difficult tradeoffs.

アーキテクトがアーキテクチャ決定を下すときには、多くの異なる次元に沿う影響を考慮して、バランスを取る必要があります。そのため、アーキテクトは常に難しいトレードオフを強いられることになります。

By “architecturally significant,” we mean the ones that will have a long and lasting effect on the system performance, quality, and scalability, as opposed to the myriad other design decisions that will be made during the construction of the system.

「アーキテクチャ上重要な」というのは、システム構築中に行われる他多数の設計判断とは異なり、システムの性能・品質・拡張性に、長期的かつ永続的に影響を与えるものを意味します。

†: 挙げられているこれらについては、「ソフトウェアアーキテクチャの基礎」[1] でそれぞれ説明が加えられています

アーキテクチャ決定におけるアンチパターン

「ソフトウェアアーキテクチャの基礎」[1] では、以下のようなアンチパターンが紹介されています。
（概要を引用するに留めるので、詳細は該当書籍を参照してください）

  • グラウンドホッグデーアンチパターン (Groundhog Day -)
    • 『ある決定が下された理由がわからずに、繰り返し何度も議論されてしまう』こと
  • 資産防御アンチパターン (Covering Your Assets -)
    • 『選択を誤ることを恐れて、アーキテクチャ決定を下すことを避けたり、先延ばしする』こと
  • 分析麻痺アンチパターン (Analysis Paralysis -)
    • 『過度に分析し過ぎることによって決定が「麻痺」してしまい、解決策や行動方針が決まらない』こと
  • メール駆動アーキテクチャアンチパターン (Email-Driven Architecture -)
    • 『人々がアーキテクチャ決定を見失ったり、忘れたり、あるいは決定されたことさえ知らなかったりするために、そのアーキテクチャ決定を実装できなくなってしまう』こと

Michael Nygard の記事[4] においては、闇雲に判断を受け入れる／変更することがアンチパターンとして挙げられています。 アーキテクチャ決定の文脈・背景が埋もれてしまっているがために、文脈・背景に変化が生じたのに決定の再検討を恐れてしまう、 または文脈・背景に変化がないのに決定を変更してしまうことにより、プロジェクト全体の価値が損なわれてしまう可能性があります。

ADR

一般に ADR は、いくつかのセクション（項目）からなります。 どのセクションを採用するか（標準とする ADR のテンプレートをどう定義するか）については、状況によって取捨選択したり、独自定義しても良いでしょう。 どうあれ「判断を記録すること」が目的であり、「どのように判断を記録するか」は手段であることに、留意が必要です。 joelparkerhenderson/architecture-decision-record リポジトリ[6] で紹介されている ADR のテンプレートを確認すると、 比較的自由にセクションが定義されていることがわかります。

ADR の運用をサポートするためのツールは、いくつかの言語で作成されています。たとえば PHP ならば globtec/phpadr などがあります。

本記事では Michael Nygard が紹介した形式と、Jeff Tyree, Art Akerman が紹介した形式を示します。なお便宜上、ADR のセクションは墨塗カッコ【】でくくり、区別して以下表記していきます。

Michael Nygard による形式

Michael Nygard の記事[4]において、紹介されている形式になります。 この形式は ThoughWorks テクノロジーレーダーに Lightweight Architecture Decision Records として採用されている[7]ため、「軽量ADR」と呼称してもいいかもしれません。 重厚に記述すると、 ADR の作成や保守のコストが高くなってしまったり、読まれなくなってしまう恐れがあるため、軽量さは無視できない要素と言えるでしょう。

「ソフトウェアアーキテクチャの基礎」[1] や「Design It!」[8] で紹介されているのもこの形式です。 これらの書籍においては、解釈の補足や拡張が行われているため、それも踏まえて以下記述します。なお Michael Nygard の記事[4] で紹介されているセクションは、 title, context, decision, status, consequences の 5 つとなります。

タイトル (Title)

【決定】を識別できる程度には説明的な、簡潔な表題を記述します。通常は連番を振ります。

文脈・背景 (Context)

【決定】が下された文脈・背景について記述します。 その【決定】を下す要因となった要求仕様について記述するセクションであるとも考えられます。

価値中立的 (value-natural) な事実を記述するのが望ましいとされています。 例えば過去のアーキテクチャ決定、技術、スキル、ビジネス、社会・政治事情、プロジェクトの地域性といった、アーキテクチャに作用する力 (forces) が挙げられます。

アーキテクチャ決定は、連鎖的に影響を及ぼすことがあります。 この ADR が、先行する ADR の【決定】に影響を受けているのならば、それを記述しておくことができます。

代替案 (Alternatives)

【決定】の代替案について、その分析の詳細を【文脈・背景】セクションを記述すると、理解しづらいものになってしまうかもしれません。 そのようなときは【代替案】を追加して、別途に記述することができます。

決定 (Decision)

アーキテクチャ決定そのものについて記述します。

能動的・肯定的に、命令形で、完全な文章 (full sentences) で記述することが望ましいとされています。 【文脈・背景】にて記述した、アーキテクチャに作用している力への対応を記述するのも良いでしょう。

ステータス (Status)

この ADR のステータスを記述します。

ステータスとして「提案済み (Proposed)」「承認済み (Accepted)」「代替済み (Superseded)」「非推奨 (Deprecated)」、「棄却 (Rejected)」の５つ（のうちいずれか）が通常用いられます。

はじめは「提案済み」というステータスにし、プロジェクトのステークホルダーから同意が得られたとき「承認済み」とします。 同意が得られなかったとき、その ADR を修正しあらためて同意を得ようとはしないのであれば、「棄却」とします。 以降に、後続の ADR によって判断が代替されたときは「代替済み」ないし「非推奨」とします。 なお代替されたときには、その後続の ADR と相互に参照させるべきでしょう。

上記に加え、「下書き (Draft)」というステータスを設定することも考えられます。 この場合ははじめ「下書き」とし、ステークホルダーにレビューを依頼をする段階で「提案済み」とします。 また、「ソフトウェアアーキテクチャの基礎」[1] では「コメント募集 (Request For Comments; RFC)」というステータスが紹介されています。

結果・影響 (Consequences)

【決定】による結果・影響、ないし成果 (outcomes) やアウトプット・フォローアップを記述します。

肯定的・中立的・否定的、いずれの観点からも列挙すべきです。 このセクションに「プラスの結果」「マイナスの結果」といった小項目を予め用意しておくと、記述しやすくなるかもしれません。

繰り返しになりますが、アーキテクチャ決定は、連鎖的に影響を及ぼすことがあります。 この ADR での【決定】が、後続の ADR にも影響するのならば、それを記述しておくことができます。

【結果・影響】を記述するタイミングは、いくつか考えられます。 【決定】を下したのと同じタイミングで、これらを予想して記述しても構いません。 また、例えば１ヶ月後といった一定期間後に、レビューを行い追記することもできます。 その場合は After-Action Review や、トレードオフ分析などが考えられます。

順守方法 (Compliance)

【決定】を順守するための方法と、順守されているかを評価するための方法を記述します。

備考 (Notes)

ADR に関するメタデータを記述します。 「ソフトウェアアーキテクチャの基礎」[1] では、以下の項目が例示されています。

  • オリジナルの著者
  • 承認日
  • 承認者
  • 代替された時刻
  • 最後に更新された時刻
  • 変更点
  • 最終更新内容

Michael Nygard による形式における運用フロー例

以上を踏まえた、運用フローの一例を以下に示します。 なお運用フローについては、AWS による ADR に関する記事[9] や kawasima さんの scrapbox[10] にも図示されているものがあります。

Jeff Tyree, Art Akerman による形式

“Documenting Software Architectures” [11] という書籍において、紹介されている形式になります。 IEEE Software というジャーナルで 2005 年に発表した、アーキテクチャ決定に関する記事 [12] でも類似のものを読むことができます （なおこれは「Design It!」[8] においては、『問題へのトレーサビリティを強調するテンプレート』と説明されています）。

この形式について詳説すると長くなってしまうため、 joelparkerhenderson/architecture-decision-record リポジトリ[6] や、それを fork した邦訳である kawasima さんの kawasima/architecture_decision_record [13] リポジトリを参照してください。 なぜこの形式を紹介したのかというと、すべてのアーキテクチャ決定を軽量に文章化したいとは限らないためです。 リポジトリ内の例にある、プロダクトで使用する言語や監視ツールの選択などは、同社内で複数のプロダクトが開発されているときは特に、より有意義な資産に成り得るでしょう。

ADR のオーナー

AWS による ADR に関する記事[9]では、ADR のオーナーについて触れられています。 ある ADR の執筆者は同時にオーナーとなり、保守や伝達、ないし後続の ADR によって代替されるときのレビューを行う責務を担うというものです。 異動などにより、その ADR について責務を負えなくなったときは、他メンバーに責務を移譲します。

出典・参考文献など

learning.oreilly.com のリンクは、オライリー学習プラットフォームにおける該当書籍へのリンクです。

そのほか参考にさせていただいたリンク

インフィニットループでは PHP エンジニアのご応募を絶賛お待ちしております。

arrow_back 前の記事へ
一覧へ戻る
次の記事へ arrow_forward

ブログ記事検索

このブログについて

このブログは、札幌市・仙台市の「株式会社インフィニットループ」が運営する技術ブログです。 お仕事で使えるITネタを社員たちが発信します！

最新の記事

人気タグ

YouTube あいえるちゃんねる
広報ブログ