Architecture Decision Recordのすすめ

著者：soma00333
目次

自己紹介

こんにちは、soma00333です。株式会社Industry TechnologyでCTOとして活動する傍ら、株式会社enechainでSREの仕事にも携わっています。

SREの仕事に大きなやりがいを感じる一方で、Platform EngineeringやSecurity分野への興味も持っています。

この記事では、ソフトウェア開発におけるアーキテクチャの意思決定とドキュメント管理の重要性に焦点を当て、「Architecture Decision Record（ADR）のすすめ」というテーマで話を進めていきたいと思います。

はじめに

enechainにおけるソフトウェア開発では、アーキテクチャの意思決定とドキュメント管理に関して以下のような課題がありました。

アーキテクチャのAs-IsとTo-Beの管理が不十分

アーキテクチャの現状と将来像の理解・管理は、開発プロセスにおいて重要です。しかし、プロジェクトにおけるアーキテクチャ関連の意思決定を体系的に追跡し文書化するアプローチが取られていませんでした。

例えば、あるチームではGatherやSlack Huddles上で意思決定をし、文章として残さない等のアプローチが取られていました。

アーキテクチャレビューの仕組みが不十分

アーキテクチャの品質を保証し、技術的負債を未然に防ぐため、開発プロセスにおけるアーキテクチャレビューの導入が必要です。しかし、多くのプロジェクトでこの体系的なアプローチが欠けていました。

例えば、適切なレビューアーを設定しないことでチームに部分最適化されたアーキテクチャが採用されてしまい、全社的な観点から見ると非効率な意思決定がなされる危険性がありました。また、一部の先進的なチームでADRが採用されており、チーム毎に意思決定プロセスが異なっていることも問題でした。

意思決定の透明性と情報共有の課題

アーキテクチャ関連の意思決定が適切に文書化されていないと、透明性が損なわれ、チーム間での情報共有が困難になります。当時の状況は新規メンバーのオンボーディングを難しくし、既存決定への理解不足を招く恐れがありました。

監査対応の問題

適切に文書化されていないアーキテクチャの意思決定は、外部監査やコンプライアンス要件を満たすことを難しくする可能性がありました。

これらの課題に対処するため、enechain SREチームでADRの導入を検討しました。SREチームが担当した理由は、全チームに対して横断的なプロセス改善を推進できるチームだからです。

SREチームとしても、ADRをリリースプロセスに組み込むことでソフトウェアの信頼性と品質を担保できる期待がありました。

ADRとは

概要

ADR（Architecture Decision Records）とは、ソフトウェアアーキテクチャに関する重要な意思決定を記録し、管理するための短いテキストドキュメントのことです。ADRの主な目的は、プロジェクトのアーキテクチャに関連する決定を透明にし、将来的な参照や意思決定のプロセスを支援することにあります。ADRはソフトウェア開発プロセスにおける重要な決定を文書化し、追跡することで、チーム内のコミュニケーションを改善し、技術的負債の管理を容易にします。

ADRの構成要素

一般的に、ADRには以下のような情報が含まれます。

  • Title: アーキテクチャ決定の簡潔な説明。
  • Status: 「Proposed」、「Accepted」、「Rejected」など、ADRの現在のステータス。
  • Context: 決定がなされた背景や状況。プロジェクトやシステムの特定のニーズや制約条件を説明します。
  • Decision: どのような決定が行われたか、その具体的な内容。
  • Consequences: 決定によってもたらされる結果。その決定のとprosとcons。

ADRの価値

ADRは以下のような価値を提供します。

  • 透明性: アーキテクチャに関する決定がなぜ、どのようにして行われたのかを明確にします。
  • ナレッジ共有: 新しいチームメンバーやプロジェクトステークホルダーが既存のアーキテクチャ決定を容易に理解できるようにします。
  • 再利用と学習: 過去の決定から学び、同様の状況で有用なインサイトを提供します。
  • 監査とアカウンタビリティ: 外部の監査やコンプライアンス要件に対応しやすくなります。

ADRの導入

enechainでは以下のようにADRを導入しています。

管理方法

Notionを採用し、Notion DBでADRを集中管理しています。このアプローチにより、文書のアクセシビリティと組織全体のナレッジ共有が促進されます。

また、Michael NygardのDocumenting architecture decisions を元にテンプレートを作成しています。

テンプレート

テンプレートの内容は以下です。

image

  • Team：担当チーム
  • Status：レビューのステータス
  • Category：ADRの内容がどのカテゴリーに属するか
  • Reviewer：レビュアー
  • Spec doc反映：spec docへの反映ステータス（必要があれば）
  • Related Spec Doc：関連するspec doc（必要があれば）
  • Related ADR：関連するADR（必要があれば）
  • MTG Date：ミーティングの日程
  • Participants：ミーティングの参加者
  • Motivation：この決定または変更の動機となっている問題を記載
  • Scope / Out of Scope：提案または実行しようとしている変更を記載
  • Consequences：この変更により、何が簡単になり、何が難しくなるか、ProsConsを記載
  • 決定結論：変更点などがあれば、Before / After を意識する形で記載
  • 備考

運用方法

ADRの品質を保証し、一貫性を維持するために、ADRのレビュープロセスを導入しています。ADR作成者は適切なレビュアーを設定し、必要に応じてミーティングを行います。関連するspec docがあれば、合わせて修正も行います。ADRの更新が必要になった際には、適宜レビューを行い、最新の状態を保つ努力をしています。

ADRにはステータス（proposed、accepted、rejected）が設定され、アーキテクチャの意思決定プロセスを明確に示しています。これにより、プロジェクト内での意思決定の進行状況を追跡しやすくしています。

導入の工夫

上記内容に落ち着くまでにenechain SREチームとしてはかなりの苦労がありました。全開発チームへの導入はハードルが高く、全チームに使ってもらえるように以下のような取り組みを粘り強く行いました。

  • SWEやEMのヒアリングを繰り返してADRのtemplateを作成する
  • 社内勉強会でADRの魅力を語る
  • 適宜SWEやEMと相談して使い方をレクチャーする
  • SREチームで率先してADRを書く
  • 各プロジェクトのNotion page直下にADRを置くなど、各チームがADRにアクセスしやすい環境を作る
  • 新規プロジェクトのキックオフ時にSREがチームに入りADRの使用を促す

上記取り組みにより、今ではenechainは全開発チームでADRが採用されています。

良かった点

良かった点として以下が挙げられます。

透明性の向上

ADRを導入することで、アーキテクチャに関する決定の透明性が向上しました。チームメンバーがなぜ特定の技術的選択がなされたのかを理解しやすくなりました。

ナレッジ共有の促進

ADRはナレッジの共有を容易にしました。新しいチームメンバーや将来のプロジェクト参加者が、過去の意思決定を迅速にキャッチアップできるようになりました。

再利用と学習の機会

過去のアーキテクチャ決定からの学習とその再利用が促進されました。これにより、同じ過ちを繰り返さずに済み、ベストプラクティスの適用が容易になりました。

アカウンタビリティの強化

決定が文書化されているため、誰が何を決定したのかが明確になり、責任の所在がはっきりしました。

監査対応の容易さ

ADRは監査やコンプライアンスの要件に対応する際に有用でした。意思決定プロセスが記録されているため、外部の監査に対しても対応しやすくなりました。

ドキュメンテーション文化の醸成

ADRの保管先としてGitHubではなくNotionを採用したことにより、enechainではADRの文化が開発チーム外にも浸透しつつあります。CorporateやBusiness側でもADR書くような例が出てきており、会社としてドキュメンテーション文化の広がりを実感しています。

悪かった点

悪かった点として以下が挙げられます。

維持管理の負担

ADRを継続的に更新し、管理することは、追加の労力を要します。特に大規模なプロジェクトでは、多くのADRが生成されるため、これらを最新の状態に保つのが困難になることがありました。

導入の障壁

ADRの概念やその価値をチームメンバーに理解してもらい、適切に利用する文化を確立するまでには、時間と労力が必要でした。

適切な利用の判断

どの決定がADRに値するのかを判断することは非常に難しいです。重要な意思決定とみなされる基準を明確にしていくことが今後も重要となります。

今後の進め方

ADRの導入は多くの利点をもたらしますが、その効果を最大限に引き出すためには、上記の課題に対処するための適切な戦略とコミットメントが必要です。引き続き、以下の取り組みを行っていく予定です。

定期的な勉強会

チームメンバーがADRの価値と正しい記述方法を理解するために、定期的な勉強会を実施します。実際の例を用いて、どのような決定がADRに値するのか、またADRをどのように活用するのかを示すことが重要だと考えています。

成功事例の共有

ADRの導入によって成功を収めた事例を積極的に共有します。実際のプロジェクトでの成功事例を示すことで、チーム内でのADRの価値認識を高め、積極的な利用を促進できると考えています。

これらの取り組みを通じて、ADRの導入と利用における課題を克服し、ソフトウェア開発プロセスにおけるアーキテクチャの意思決定とドキュメント管理の効率性と効果を高めることができると考えています。

さいごに

今回はenechainのSREチームが全開発チームにADRを導入して得られた所感をお話ししました。

ソフトウェア開発におけるアーキテクチャの意思決定とドキュメント管理は、進化し続ける技術の世界での成功の鍵です。ADRはその重要な一環であり、適切に活用することで、より強固で透明性の高い開発プロセスを構築できます。

全チームへの導入には大きな苦労が伴いますが、SREとして勇気をもって挑戦しましょう。

ぜひみなさんも、ADRの導入を検討してみてください。