ADR プロセス

アーキテクチャ決定レコード (ADR) は、構築計画中のソフトウェアアーキテクチャの重要な側面に関してチームが取った選択について説明する文書のことです。各 ADR には、アーキテクチャの決定、その背景、およびその結果が記載されています。ADR には状態があるため、ライフサイクルに従います。ADR の例については、「付録」を参照してください。

ADR プロセスはアーキテクチャ決定レコードのコレクションを出力します。このコレクションが決定ログを作成します。決定ログには、プロジェクトのコンテキストだけでなく、実装や設計に関する詳細な情報も記録されます。プロジェクトメンバーは各 ADR の見出しにざっと目を通して、プロジェクトコンテキストの概要を把握します。また ADR を読み、プロジェクトの実装と設計上の選択について深く掘り下げます。

チームが ADR を受け入れると、その ADR はイミュータブルになります。新しいインサイトに別の決定が必要な場合、チームは新しい ADR を提案します。チームがその新しい ADR を受け入れると、新しい ADR が前の ADR に取って代わります。

ADR プロセスの範囲

プロジェクトメンバーは、ソフトウェアプロジェクトまたは製品に影響を及ぼすアーキテクチャ上の重要な決定があるたびに ADR を作成する必要があります (Richards and Ford 2020)。この重要な決定には以下を含みます。

• 構造 (マイクロサービスなどのパターンなど)

• 非機能的要件 (セキュリティ、高可用性、耐障害性)

• 依存関係 (コンポーネントの結合)

• インターフェイス (API と公開済みの契約)

• 構築技術 (ライブラリ、フレームワーク、ツール、プロセス)

ADR プロセスでは、機能的要件と非機能的要件が最も一般的な入力項目です。

ADR の内容

チームが ADR の必要性を判断すると、チームメンバーはプロジェクト全体のテンプレートに基づいて ADR の作成を開始します。(テンプレートの例については、「ADR GitHub organization」を参照してください。) テンプレートを使うと ADR の作成が簡単になり、ADR がすべての関連情報を確実にキャプチャできるようになります。各 ADR には、少なくとも、決定の背景、決定自体、および決定がプロジェクトとその成果物にもたらす結果を定義する必要があります。(これらのセクションの例については、「付録」を参照してください。) ADR 構造の最も強力な点の 1 つは、チームがどのように決定を実行したかではなく、決定の理由に焦点を当てていることです。チームが決定を下した理由を理解することで、他のチームメンバーがその決定を採用しやすくなり、意思決定プロセスに関与しなかった他のアーキテクトが将来その決定を覆すのを防ぐことができます。

ADR の導入プロセス

すべてのチームメンバーが ADR を作成できますが、チームで ADR の所有権の定義を確立する必要があります。ADR の所有者である各作成者は、ADR の内容を積極的に管理し、伝える必要があります。この所有権を明確にするために、このガイドの以下のセクションでは ADR 作成者を ADR 所有者と呼びます。他のチームメンバーはいつでも ADR に寄稿できます。チームが ADR を受け入れる前に ADR の内容が変更された場合、所有者はその変更を承認する必要があります。

次の図は、ADR の作成、所有、採用のプロセスを示したものです。

チームでアーキテクチャの決定事項とその所有者を決定したら、ADR 所有者はプロセス開始時に ADR を提案済みの状態にします。提案済み状態の ADR はレビューの準備ができています。

その後、ADR 所有者は ADR のレビュープロセスを開始します。ADR レビュープロセスの目標は、チームが ADR を受け入れるか、やり直す必要があると判断するか、ADR を拒否するかを決定することです。所有者を含むプロジェクトチームで ADR をレビューします。レビューミーティングは、ADR を読むためだけの時間を設けることから始めます。平均して 10～15 分で十分です。この時間で、各チームメンバーは文書を読み、不明瞭なトピックを報告するコメントや質問を付け足します。レビューフェーズの後、ADR 所有者は各コメントを読み上げてチームで話し合います。

チームが ADR を改善するためのアクションポイントを見つけても、ADR の状態は提案済みのまま変わりません。ADR 所有者はアクションを策定し、チームと協力して各アクションに担当者を付けます。これで各チームメンバーは寄稿することができ、アクションポイントを解決することができます。レビュープロセスのスケジュールを変更するのは ADR 所有者の責任です。

また、チームは ADR を拒否する決定を行うこともできます。この場合、ADR 所有者は、将来同じトピックに関する議論が起こるのを防ぐため、拒否の理由を追加します。所有者は ADR の状態を拒否済みに変更します。

チームが ADR を承認すると、所有者はタイムスタンプ、バージョン、利害関係者のリストを追加します。その後、所有者は状態を承諾済みに更新します。

ADR と ADR が作成する決定ログは、チームが下した決定を表し、すべての決定の履歴になります。チームは可能な限り、コードやアーキテクチャのレビューの際に ADR を参考として使用します。チームメンバーは、コードレビュー、設計作業、実装作業を行うだけでなく、製品の戦略的決定について ADR を参照する必要があります。

次の図は、ADR を適用して、ソフトウェアコンポーネントの変更が、合意された決定に準拠しているかどうかを検証するプロセスを示しています。

良い習慣として、各ソフトウェアの変更はピアレビューを受け、少なくとも 1 回の承認を得る必要があります。コードレビュー中に、コードレビュー担当者は ADR に違反する変更を 1 つ以上発見することがあります。この場合、レビュー担当者はコード変更の作成者にコードの更新を依頼し、ADR へのリンクを共有します。作成者がコードを更新すると、そのコードはピアレビュー担当者によって承認され、メインのコードベースにマージされます。

ADR のレビュープロセス

ADR をチームが承認または拒否した後は、ADR を変更不可能な文書として扱う必要があります。既存の ADR を変更する場合は、新しい ADR を作成し、新しい ADR のレビュープロセスを確立し、ADR を承認する必要があります。チームが新しい ADR を承認した場合、所有者は古い ADR の状態を置き換え済みに変更する必要があります。以下の図は、その更新プロセスを示したものです。