実践ADR

従来のアーキテクチャ文書の課題として、以下のようなものがありました。

決定事項だけが書かれていて経緯が分からない。

リリース後のメンテがされていない。

ADRは、アーキテクチャ設計ドキュメントが重厚長大になり、結局誰も読まない文書にならないよう、継続したメンテナンスに重きをおいたものです。

ADRとは何か?

アーキテクチャとは「設計上の重要な意思決定」です。そして、この意思決定にまつわる関係者の「思い」が重要で、これが継承されていかないと、新規プロジェクト参画者は次のどちらかの行動をとるでしょう。

1. 何も考えず意思決定を受け入れる

もし意思決定がいまだ妥当なものならば、この行動はOKかもしれません。しかしコンテキストが変わって、意思決定が本当は見直されなければならないとしたら、これは良くないことです。 プロジェクトによく理解されずに積み重なった多くの意思決定事項があると、開発チームはどんな変更も怖がり、プロジェクトはその重みに耐えられなくなります。

2. 何も考えず決定を覆す

意思決定が立ち戻る必要があるならば、これはOKかもしれません。が一方で、その思いや因果関係を理解せずに決定を覆すことは、プロジェクト全体の価値にダメージを与えることを意味します。 (たとえば、その決定はまだテストされていない非機能要求をサポートするものであった、など)

継続して成長するビジネスを支えるシステムににおいては、何も考えず受け入れることも、何も考えず覆すことも避けなければなりません。

そこで設計上重要な意思決定の記録をキープするようにしましょう。それは構造や非機能の性質、依存関係、インタフェース、構築手法などに影響するものたちです。

用語の定義

architecture decision record (ADR) : アーキテクチャ上の重要な意思決定を、そのコンテキストや結果とともに記録した文書

architecture decision (AD) : 重要な要求に対するソフトウェア設計上の選択を指す。

architecture decision log (ADL): あるプロジェクト(または組織)のために、作成されメンテされている、すべてのADRを指す。

architecturally-significant requirement (ASR) :　ソフトウェアシステムのアーキテクチャに影響を与える要求のことで、計測可能でなくてはならない。

これらすべては、architecture knowledge management (AKM)のトピックの範疇です。

ADRを書く対象

ADRはAD(architecture decision)について書くものですが、これはすなわち

一旦決定したら、その変更には大きなコストがかかるもの

を意味します。「大きなコスト」はプロジェクトによりしきい値を決めるべきですが、一般的には言語やフレームワークの決定、システムの分割と責務配置それらの連携方式などが、ADになるでしょう。

ADRのツール

いくつかの管理の仕方があります。

Google Driveを使ってオンラインで編集するのが好みならば、Google DocsやGoogle Spreadsheetが使える。

gitのようなバージョン管理システムを使うのが好みならば、ADR毎にファイルを作ればよい。

JIRAのようなプロジェクト計画ツールが好みであれば、ツールのプランニングトラッカーを使うと良い。

MediaWikiのようなWikiが好みであれば、ADR wikiを作ると良い

gitを使うやり方

gitを使うのが好きな人のために、典型的なソフトウェアプロジェクトのためのgitでのADRの始め方をここに示します。

ADRファイルを置くためのディレクトリを作る:

code:shell

$ mkdir adr

各ADRのために、database.txt のようなテキストファイルを作る:

code:shell

$ vi 001_select_rdbms.txt

ADRに必要なことを書き込む。このリポジトリにADRのテンプレートがあるので、それを参照しましょう。

ADRファイルの命名規約

テキストファイルを使ってADRを作るのであれば、ADRファイルの命名規約が欲しくなるでしょう。

以下のファイル命名規約を使うとよい。

code:命名規約例

choose_database.md

format_timestamps.md

manage_passwords.md

handle_exceptions.md

名前には現在時制の命令動詞句を使う。これは可読性を高め、コミットメッセージのフォーマットにも合う。

名前には小文字とアンダースコアを使う。これは読みやすさとシステムでの扱いやすさのバランスだ。

拡張子はマークダウンのものにする。簡単にフォーマッティングするのに便利だから。

ADRのテンプレート

いくつかのスタイルがある。

項目数が少なく、ちゃんとメンテしていけることを重視するならこれ。

クラシカルなアーキテクチャ設計文書の流れをくむ

ADRの内容をパターンとして書き下すときに

ADRの例

Example

実例

ADRの運用フロー

https://gyazo.com/15aa85491324e27938b4ac8cdad1d291

ADRは、時間の経過によってコンテキストが変われば、デシジョンも変わってくるため、定期的な見直しが必要です。数ヶ月に一度、棚卸しとしてチームメンバでADRを読み返す場を作るとよいでしょう。

ADRを書いてみるワークショップ

1. 自身のプロジェクトに関して、今直面している設計課題や、過去取り組んだ設計課題について思い出しリストアップしましょう。

2. テーマを決めたら、コンテキストを明らかにします。

ダイアログマッピングを使って書きましょう。アナログでもホワイトボードツールでも構いませんが、CacooやMiroで描くのが便利です。

3. コンテキストを前提として、解決策の代替案を作ります。(これもダイアログマッピング上でやってよいです。)

4. 代替案のフィジビリティをチームで議論し、それぞれの案についてPros/Consを挙げます。

5. 最終的にどの案でいくか、(過去実際に決断したものは)どの案でいくべきだったかを決めます。

6. 決定した案に関して、Consequencesを議論します。