アーキテクチャ意思決定記録（ADR）とは何か

『エンジニアリングマネージャーのしごと』を読んだ際に、アーキテクチャ意思決定記録（Architecture Decision Record; ADR）という用語を初めて知りました。最近、チームメンバーが増えてデータ基盤の設計に関してADRに残さないかという話が出ており、ADRについて自分なりに理解するために調べてみました。

ADRとは

Architecture Decision Record（ADR）は、ソフトウェアアーキテクチャにおいて重要な意思決定をドキュメントとして残したものです。ADRには、ソフトウェアアーキテクチャに関する意思決定の履歴や根拠、その結果を記録し、プロジェクトチーム全体に共有します。ポイントは決まったことだけを記録するのではなく、意思決定に至った議論や背景、制約条件なども含めて記録することです。

ADRの主な目的は次のとおりです。

アーキテクチャ上の意思決定を明確にすることで、チーム内での認識のズレを減らす。
新しいメンバーが、過去のアーキテクチャ上の意思決定を理解しやすくする。
過去の意思決定から学習することで、チーム全体でアーキテクチャに関する知識や経験を蓄積でき、今後のプロジェクトにおいて不要な議論を減らして意思決定までの効率性を向上する。

新しく入ったメンバーが現在のアーキテクチャ設計の意図を知りたい場合、アーキテクチャ設計をした当人がチームに在籍していればその人に聞くことができますが、退職されていたり、その当人が忘れてしまった場合に意図を知ることができません。

意図を知らなければ、今後アーキテクチャを見直す場合に、設計した当初と同じ議論をしてしまうかもしれないですし、誤った意思決定をしてしまうかもしれません。

現在、Aという設計になっているが、Bという設計がいいのではないかという議論が出たとします。しかし、本当はCという制約条件があるためBが採用できず、Aを採用せざるを得ないかもしれません。そのような制約条件を知らなければ、Bに変更しようというプロジェクトが発動されるも設計や実装途中で制約条件が見つかり、中止せざるを得なくなります。それまでに費やしてきた時間とお金がまったく無駄になってしまいます。それだけ、アーキテクチャ設計における意思決定の意図や履歴や根拠、制約条件などの情報は必要です。

ADRのテンプレート

ADRを作成する際に、以下の要素で構成されることが多いです。

Title（タイトル）：意思決定の概要を示す簡潔な表現。
Status（ステータス）: 意思決定の現在のステータス
- Draft: これから提案するもの
- Proposed: 提案中
- Accepted: 提案が受け入れられた
- Rejected: 提案が却下された
- Deprecated: 非推奨
- Superseded: 別のADRに置き換えられた
Decision（決定事項）：アーキテクチャやソリューションの意思決定の内容
Context（経緯・背景情報）: この意思決定が行われる背景、問題点、目的など
Consideration（比較・検討内容）: 他に検討した選択肢や検討した内容
Consequences（結果）: 予期される結果。意思決定がシステムやプロジェクトに与える影響、関連する利害関係者への影響など
References（参照）: 関連リンク

ADRの運用プロセス

導入：チーム全員にADRの目的とメリットを説明し、導入の合意を得る
テンプレート作成：Notionなどにテンプレートを作成する。Notionのデータベース機能を利用してADR一覧を管理する。
ADRの作成・更新プロセスの定義（後述）
いつADRを作成し、レビューするかを決定する
チーム全体への共有: 定期会議などで新たなADRや更新内容を共有する

ADRの作成プロセス

AWSの公式ドキュメントに掲載されていたプロセス図を以下に転載します。

adr-creation

参考: https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html#adoption

ADRはチームメンバー全員が作成できる
ADRの作成者は、ADRをコンテンツの維持やステータス更新、およびメンバーへの伝達やレビュー依頼をする必要がある
ADRを作成してレビューできる状態になったら、ステータスをProposedにする
ADRの作成者はレビューミーティングを開催するか、定例ミーティングでレビューをする
- 平均して10～15分程度
- 各チームメンバーはADRを読み、コメントや質問をしてチーム内で議論する
ADRを改善するアクションポイントが見つかった場合は、チームで協力してアクションポイントの解決を図る
チームがADRを承認した場合、ステータスをAcceptedにする
チームがADRを却下した場合、却下の理由を追記して、ステータスをRejectedにする
ADRドキュメントを変更できないようにロックする（Notionなどのドキュメントツールに依存する）