ADR(Architecture Decision Records)を書く

ADR(Architectural Decision Records)

文脈と問題点の説明

ソフトウェア開発中に、あるアーキテクチャを採用した理由を知りたいことがある。

幸運にもそのアーキテクチャを採用した開発者にインタビュー可能で、また開発者の記憶が定かであれば、当時どのような状況・どのような選択肢が用意されている中から選択したかを明らかにできる。 しかしそうではなかった場合、過去に採用したアーキテクチャを盲目的に受けいれたり、完全に無視するといった不健全な意思決定を強いられることになる。

そこで、決定の粒度が大きくかつプロダクトの品質に大きく影響を与えるアーキテクチャ上の変更の「なぜ」を記録し、時間が経過した後も簡単にアクセスできるよう ADR という手法を用いる。

決定要因

ADR を書いた場合、ソフトウェアの費用に比べて効果が上まわるか?

検討した選択肢

決定内容

以下の理由により選択肢「ADR を書く」を採用する。

今回作ろうとしているソフトウェアの特徴は以下のとおりで、上記の一般論にあてはめると ADR 記述の効果が費用を上まわると想定される。

検討したこと

コミットログでは足りないのか

何をどのように変更したかはソースコードの差分を見るとわかる。行儀のよいコミットログがあれば、なぜ変更したかコミット単位での理由がわかる。どちらもソースコードのバージョン管理システムを使っていれば容易に取得できる。

一方で複数のコミットからなる変更をなぜ行ったかを保存し一覧を平易に眺めるという機能はバージョン管理システムには存在しない。フィーチャーブランチをマージするときのコミットログに書くという運用で複数コミットの変更理由を保存することもできるが、一覧を平易に眺めることはできない。

またそもそもコードの変更を伴わない変更、たとえば運用環境の制定や、前提条件の緩和、あるいは検討した結果コードに手を加えないことを決定したものなどはコミットログとして残らない。

上記よりコミットログでは足りないと判断した。

リンク