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).

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

（図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 のリンクは、オライリー学習プラットフォームにおける該当書籍へのリンクです。

• ^[1] Mark Richards, Neal Ford. 「ソフトウェアアーキテクチャの基礎 – エンジニアリングに基づく体系的アプローチ」 島田 浩二 訳. オライリージャパン. 2022.
  • https://learning.oreilly.com/library/view/fundamentals-of-software/9781492043447/
• ^[2] ä»™å¡²å¤§ä¹Ÿ. 「良いコード／悪いコードで学ぶ設計入門 – 保守しやすい 成長し続けるコードの書き方」 技術評論社. 2022.
• ^[3] “Architectural decision”. https://en.wikipedia.org/wiki/Architectural_decision. 2023/02/28 閲覧.
• ^[4] Michael Nygard. “DOCUMENTING ARCHITECTURE DECISIONS”. https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions. 2023/02/28 閲覧.
• ^[5] Per Kroll, Philippe Kruchten. “The Rational Unified Process Made Easy: A Practitioner’s Guide to the RUP”. Addison-Wesley Professional. 2003.
  • https://learning.oreilly.com/library/view/the-rational-unified/0321166094/
  • 邦訳： 「ラショナル統一プロセス〈RUP〉ガイドブック : RUP実践者を成功に導く」 杉本宣男, 落合修 訳. 永田葉子 監訳. エスアイビー・アクセス. 2004
• ^[6] Joel Parker Henderson. “Architecture decision record (ADR)”. https://github.com/joelparkerhenderson/architecture-decision-record. 2023/02/28 閲覧.
• ^[7] Thoughtworks. “Lightweight Architecture Decision Records”. https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records. 2023/02/28 閲覧.
• ^[8] Michael Keeling. 「Design It! – プログラマーのためのアーキテクティング入門」 島田 浩二 訳. オライリージャパン. 2019.
  • https://learning.oreilly.com/library/view/design-it/9781680502923/
• ^[9] AWS. “ADR process”. https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html. 2023/02/28 閲覧.
• ^[10] kawasima. “実践ADR”. https://scrapbox.io/kawasima/%E5%AE%9F%E8%B7%B5ADR. 2023/02/28 閲覧.
• ^[11] Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Paulo Merson, Robert Nord, Judith Stafford. “Documenting Software Architectures: Views and Beyond”. 2nd Edition. Addison-Wesley Professional. 2010.
  • https://learning.oreilly.com/library/view/documenting-software-architectures/9780132488617/
  • 邦訳： 「ソフトウェアアーキテクチャドキュメント – ソフトウェア戦略の中核:アーキテクチャを捉えプロジェクトを革新する」 前田 卓雄 訳. 日刊工業新聞社. 2004
• ^[12] Jeff Tyree, Art Akerman. “Architecture Decisions: Demystifying Architecture”. IEEE Software, Volume22, Issue2. 2005. https://personal.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf. 2023/02/28 閲覧.
• ^[13] Joel Parker Henderson, kawasima. “Architecture decision record (ADR)”. https://github.com/kawasima/architecture_decision_record/tree/japanese. 2023/02/28 閲覧.

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

• GitHub における ADR の説明
  • https://adr.github.io/
  • https://github.blog/2020-08-13-why-write-adrs/
• Cloud アーキテクチャセンターにおける ADR の説明
  • https://cloud.google.com/architecture/architecture-decision-records?hl=ja
• Qiita, Zenn, Scrapbox でみつけた記事
  • https://qiita.com/fuubit/items/dbb22435202acbe48849
  • https://zenn.dev/goldeneggg/scraps/5974c5f0a36661
  • https://scrapbox.io/iki-iki/ADR
• 企業ブログとしてみつけた記事
  • https://fintan.jp/page/1636/
  • https://blog.studysapuri.jp/entry/architecture_decision_records
  • https://developer.mamezou-tech.com/blogs/2022/04/28/adr/
  • https://tech.crassone.jp/posts/introduce-adr-documentation
  • https://miraitranslate-tech.hatenablog.jp/entry/2022/06/07/120000

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