ADR とは

アーキテクチャ決定レコード（ADR）は、コンテキストと結果とともに行われた重要なアーキテクチャ決定をキャプチャするドキュメント。

　ADR を残す理由

既存のアーキテクチャの背後にある決定の意図が不透明な場合、我々が行える振る舞いは以下の 2 点である

• 盲目的にその決定を信じる

  • 現構成が有効だと思っている間はいいかもしれない。しかし、課題が出てきたり、そういった決定が増えてくると開発チームは何かを変えることを恐れるようになる。その結果、チームが機能しなくなる。

• 盲目的(不確実性を含みつつ)にそれを変更する

  • 丸ごと決定を覆すのであればまだよい。しかし、変更が認知していないクリティカルな部分に響いてしまった場合、プロジェクト全体の価値を損なう可能性がある。

両者とも、背景がわからないことで変更に対するリスクをチームで見積もれないことが大きなデメリットかと思う。

誰がプロジェクトに入っても、今までの決定の歴史や将来に予期されている課題を理解し、新たな課題解決のための決定ができる状態が望ましい。
これは、チームをスケールさせることや、チームの健全性にも関わってくるはずだ。
そのために、ADR を残して運用を続ける。

format

ADR を考案した Michael Nygard の Documenting architecture decisions より引用

ここから

Title

Status

• proposed
• accepted
• rejected
• deprecated
• superseded

Context

アーキテクチャの決定を行う必要性、背景的な部分
また、アーキテクチャの代替手段を複数提案する

Decision

重要: 決定するのであれば、アーキテクチャの正当性を書き記す

Consequences

採用した決定の結果について述べる
基本的にはいい結果がもたらされるはず。(そのために議論し決定しているはず) もし懸念がある場合はその点についても触れておく。将来の自分へのメモとして。

ここまで

その他

ADR は 1 or 2ページ程度のシンプルなものでなければならない。あくまで、後からジョインしたメンバが読んで早く理解できるものが望ましいため。
前段の議論などは、Amazon の 6 pager で話しやすいようにまとめておき、決まったことについて ADR に清書するのがよさそうに思った。
自分も 6 pager 風に決定したいことはまとめるが、議論があるとその資料は色々な変更が入ったまま放置してしまいがちなため。正直人に読んでおいてと堂々進められるものではない状態になっていることが多い。