Architecture Decision RecordAWS アーキテクチャ決定記録プロセス
アーキテクチャ決定記録(ADR)とは、チームが構築を計画しているソフトウェアアーキテクチャの重要な側面について行った選択を記述した文書です。各 ADR は、アーキテクチャ上の決定、そのコンテキスト、およびその結果を記述します。ADR には状態があり、したがってライフサイクルに従います。ADR の例については、付録を参照してください。
ADR プロセスは、アーキテクチャ決定記録のコレクションを出力します。このコレクションが決定ログを構成します。決定ログは、プロジェクトのコンテキストに加え、詳細な実装および設計情報を提供します。プロジェクトメンバーは、各 ADR の見出しをざっと読んでプロジェクトのコンテキストの概要を把握します。そして ADR を読み込んで、プロジェクトの実装や設計上の選択を深く理解します。
チームが ADR を承認すると、その ADR は不変になります。新たな知見によって異なる決定が必要になった場合、チームは新しい ADR を提案します。チームが新しい ADR を承認すると、それが以前の ADR に取って代わります。
ADR プロセスの範囲
プロジェクトメンバーは、ソフトウェアプロジェクトまたは製品に影響を与える、アーキテクチャ上重要なすべての決定について ADR を作成する必要があります。これには次のものが含まれます(Richards and Ford 2020):
構造(たとえば、マイクロサービスなどのパターン)
非機能要件(セキュリティ、高可用性、耐障害性)
依存関係(コンポーネントの結合)
インターフェース(API と公開された契約)
構築技術(ライブラリ、フレームワーク、ツール、プロセス)
機能要件と非機能要件は、ADR プロセスへの最も一般的な入力です。
ADR の内容
チームが ADR の必要性を特定すると、チームメンバーがプロジェクト全体のテンプレートに基づいて ADR の作成を開始します。(テンプレートの例については、GitHub の ADR 組織を参照してください。)テンプレートは ADR の作成を簡素化し、ADR に関連するすべての情報が確実に記載されるようにします。最低限、各 ADR は、決定のコンテキスト、決定そのもの、そしてプロジェクトとその成果物に対する決定の結果を定義する必要があります。(これらのセクションの例については、付録を参照してください。)ADR 構造の最も強力な側面の 1 つは、チームがどのように実装したかではなく、決定の理由に焦点を当てていることです。チームがなぜその決定を下したのかを理解することで、他のチームメンバーがその決定を受け入れやすくなり、意思決定プロセスに関与していなかった他のアーキテクトが将来その決定を覆すことを防ぎます。
ADR 採用プロセス
すべてのチームメンバーが ADR を作成できますが、チームは ADR の所有権の定義を確立する必要があります。ADR の所有者である各作成者は、ADR の内容を積極的に維持し、伝達する必要があります。この所有権を明確にするため、このガイドでは以降のセクションで ADR の作成者を ADR 所有者と呼びます。他のチームメンバーはいつでも ADR に貢献できます。チームが ADR を承認する前にその内容が変更された場合、所有者はこれらの変更を承認する必要があります。
チームがアーキテクチャ上の決定とその所有者を特定した後、ADR 所有者はプロセスの開始時に ADR を Proposed(提案済み) 状態で提示します。Proposed 状態の ADR はレビューの準備ができています。
次に ADR 所有者は、その ADR のレビュープロセスを開始します。ADR レビュープロセスの目標は、チームが ADR を承認するか、やり直しが必要と判断するか、却下するかを決めることです。所有者を含むプロジェクトチームが ADR をレビューします。レビュー会議は、ADR を読むための専用の時間枠から始める必要があります。平均して 10〜15 分で十分です。この間、各チームメンバーは文書を読み、不明確なトピックにフラグを立てるためにコメントや質問を追加します。レビューフェーズの後、ADR 所有者は各コメントを読み上げ、チームと議論します。
チームが ADR を改善するためのアクションポイントを見つけた場合、ADR の状態は Proposed のままです。ADR 所有者はアクションを策定し、チームと協力して各アクションに担当者を割り当てます。各チームメンバーはアクションポイントに貢献し、解決することができます。レビュープロセスを再スケジュールするのは ADR 所有者の責任です。
チームは ADR を却下することもできます。この場合、ADR 所有者は、同じトピックに関する将来の議論を防ぐために却下の理由を追加します。所有者は ADR の状態を Rejected(却下) に変更します。
チームが ADR を承認する場合、所有者はタイムスタンプ、バージョン、およびステークホルダーのリストを追加します。その後、所有者は状態を Accepted(承認済み) に更新します。
ADR とそれが作成する決定ログは、チームが行った決定を表し、すべての決定の履歴を提供します。チームは、可能な場合、コードレビューやアーキテクチャレビューの際に ADR を参照として使用します。コードレビュー、設計タスク、実装タスクの実施に加えて、チームメンバーは製品の戦略的決定について ADR を参照する必要があります。
良い実践として、すべてのソフトウェア変更はピアレビューを経て、少なくとも 1 人の承認を必要とするべきです。コードレビュー中に、レビュー担当者が 1 つ以上の ADR に違反する変更を見つけることがあります。この場合、レビュー担当者はコード変更の作成者にコードの更新を依頼し、その ADR へのリンクを共有します。作成者がコードを更新すると、ピアレビュー担当者に承認され、メインのコードベースにマージされます。
ADR レビュープロセス
チームは、ADR を承認または却下した後は、それを不変の文書として扱う必要があります。既存の ADR を変更するには、新しい ADR を作成し、新しい ADR のレビュープロセスを確立し、その ADR を承認する必要があります。チームが新しい ADR を承認した場合、所有者は古い ADR の状態を Superseded(置き換え済み) に変更する必要があります。