ADRを試してみる
本記事は、 DDD-Community-Jp Advent Calendar 2020の24日目です。
はじめに
モデリング会では二週間に1回というペースでやっているので、どうしても前回までにしていた設計の内容を思い出すことが大変です1
そういった課題があったときにADRというものを知り、これはモデリング会のみならず普段の業務でも使えそうだと思い、試すことにしました。
ADRというのは
Architecture Decision Records の略であり、その名のとおり、アーキテクチャの決定の記録です。
詳しい説明はこちらの記事が参考になります。
ADRを導入するモチベーション
「はじめに」でも書いていますが、隔週ペースでやっている勉強会だと、前にやっていた内容を忘れてしまい、「どうしてこんな設計にしたんだっけ」という事が多発しています。
現在の状態はコードやモデルを見ることで把握できますが、その「なぜ」を素早く把握するために、1つの議題に対して状況や、決定事項を書いて残しておけるADRというフォーマットは良さそうだと感じました。
やってみた
ADRはざっくり言うと、ある議題に対しての決定事項の積み重ねです。
良いADRの特徴： - ポイントインタイム(Point in Time) 決定が作成された時を特定できる。
上記で挙げた記事で、1つの議題に対して1レコードかつ、それらは変更されないべきであると書いてあります。
あくまでADRはテンプレートであり、手法の話をしているので、ADRの保存場所については特に決められていなそうですが、ソースコードを管理している場所と一緒に置いておくのが都合が良いと思われます。 今回はGitHubでソースコードを管理しているので、同じくGitで管理しておくようにします。
テンプレを守っていれば普通に手書きでMarkDownで書いても良さそうですが、
adr-tools 使い方
インストール方法
brew install adr-tools
参考: https://github.com/npryce/adr-tools/blob/master/INSTALL.md
新規ADR作成
何かしら設計などの決め事が決まった時（レイヤー分けの方針とか、画面レイアウトの決め事など）に、1つADRを作成します。
<タイトル>は、決定事項の内容を簡潔に記します。
adr new <タイトル>
例
adr new ADR導入の検討
注意事項として、adr-toolsはファイル名に日本語を判断してくれずに、日本語を抜いたものをファイル名とします。
（上記の例の場合、 0001-adr となってしまう）
以前のADRを差し替えたADRの作成
状況の変化などにより、以前決めた事が変わることがあります。 以前のADRを置き換えるか、無効にする「決定」がされた場合には、新しいADRを書いていきます。
adr new -s <置き換えるADRのID> <タイトル>
例
adr new -s 1 ADRやめた
この例だと、1個目のADRにとって変わった2個目のADRが作成されます。 各ADRにもリンクが貼られ、1個目のADRはステータスが変更されます。
0002-ADRやめた.md
## Status Accepted Supercedes [1. ADR導入の検討](0001-ADR導入の検討.md)
0001-ADR導入の検討.md
## Status Superceded by [2. ADRやめた](0002-adr.md)
やってみた結果
今回は以下のようにPRを出してみました。
https://github.com/ModelingKai/Reservation2/pull/18/files
まだPR段階で、導入してみてどうだったか？ という計測はまだ出来ていないのですが、非常に軽量なやり方で良いと感じています。
その時々の状況と決定事項をちゃんと残せるのが強いと感じます。
やってみた結果（現場）
せっかくなので現場でも試してみました。
ドキュメント自体はGitHubで管理していましたが、形式張ったやり方ではなかったし、やはりその設計にしたWhatは残せても、Whyが残しづらかったです。
今の状況が設計において試行錯誤するフェーズにいるため、この設計にした理由や、やったけどやめたなどの理由を、ADRを使っていくことにより逐一残していけるのはとても良いと感じています。
しばらく続けていき、また別のところで結果を書いていけたらと思っています。
