概要
ADR（Architecture Decision Record）について調べた。
ADRとは
2011年にMichael Nygardによって紹介されたアーキテクチャに関する決定事項を記録したドキュメントのこと。 cf. cognitect.com - DOCUMENTING ARCHITECTURE DECISIONS
フォーマット
Michael Nygardは提案するフォーマットは次の通り。 cf. cognitect.com - DOCUMENTING ARCHITECTURE DECISIONS
- タイトル
- コンテキスト
- 文脈。どういうシーンにおける決定なのか。
- 決定
- 決定事項は1つのADRにつき1つが推奨
- ステータス
- 提案、承認、非推奨など
- 結果
- 決定事項を適用した後にどういう状態になるか、結果のコンテキストについての説明
ドキュメントは1~2ページ程度の読みやすい長さにする。
コピペで使えるMarkdownテンプレート
# ADR-XXXX: [タイトル]
## ステータス
提案中 / 承認済み / 廃止済み / 対象外
## 日付
YYYY-MM-DD
## コンテキスト
この決定が必要になった背景・状況を記述する。
例）モノリスからマイクロサービスへの移行にあたり、APIゲートウェイの選定が必要になった。
## 決定
決定事項を1つ記述する。
例）API GatewayにAWS API Gatewayを採用する。
## 理由
なぜこの決定を行ったかの根拠を記述する。
- 候補1との比較
- 候補2との比較
- チームの技術スタックとの親和性
## 結果
この決定を実施した後に生じる結果・影響を記述する。ポジティブな面もネガティブな面も含める。
## 参考
- 参照したドキュメントやリンク
ADRを採用する利点
- アーキテクチャに関する設計判断についてキャッチアップしやすくなる
- 明記された決定事項に関する議論頻度の減少
- チーム内外におけるアーキテクチャの透明性への貢献
ADRを採用するかどうかの判断
- チームで繰り返し議論を行うような内容であるか？
- チームで意思決定した設計について決定事項であるか？
- ソフトウェア全体に影響がある決定事項であるか？
などアーキテクチャの何かしらの判断・決定をする際はADRを書く機会がある。
所感
- ソフトウェアアーキテクチャの基礎では、
- ADRを導入しようと思った際は、ADRの導入についてのADRをまずは書いてみるのが良さそう
- Design Docsと少し雰囲気が違って、ADRの管理はリポジトリでソースコードとともに管理されるのが好まれる雰囲気を感じた
- ADRを書くか書かないかの判断基準はシンプルにするのが良いと思った
- チームで議論し、決定したことについては全て書く、など
- ADRの検索性
- 運用上ADRを検索したいときにちゃんと検索しやすい工夫があると良いのかもしれない（数が多くなるのであれば）
- カテゴライズ、タグなど工夫したほうが良さそう
参考
- github.com - Architecture decision record (ADR)
- cognitect.com - DOCUMENTING ARCHITECTURE DECISIONS
- docs.aws.amazon.com - ADR process
- betterprogramming.pub - The Ultimate Guide to Architectural Decision Records Introduction
- engineering.atspotify.com - When Should I Write an Architecture Decision Record
- www.redhat.com - Why you should be using architecture decision records to document your project
- www.thoughtworks.com - Lightweight Architecture Decision Records
- developer.mamezou-tech.com - アーキテクチャ・デシジョン・レコードの勧め
- cloud.google.com - アーキテクチャ決定レコードの概要
- qiita.com - アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？
- qiita.com - アーキテクチャに関するドキュメントの残しかた - ADRとARCHITECTURE.md テンプレート
- blog.studysapuri.jp - 〜その意思決定を刻め〜「アーキテクチャ・デシジョン・レコード(ADR)」を利用した設計の記録
- fintan.jp - Architecture Decision Records導入事例
