「この構成、なんでこうなってるんだっけ」
半年前の判断を追いかけようとして、手がかりがコミットログしか無い。
そんな場面は、決めた結果だけが残って、決めた理由が誰の頭にも残っていないときに起こります。
設計そのものはコードに刻まれているのに、そのとき何と何を天秤にかけたのかは、どこにも書かれていない。
この穴を、ごく軽い書式で埋めにいくのが ADR（Architecture Decision Record）という記録の作法 です。
テックリードを目指して学んでいる立場から、ADR が何を残すための道具なのかを整理してみました。
ADRは「決めたこと」ではなく「決めた理由」を残す
ADR は日本語にすると「アーキテクチャ決定記録」で、ひとつの技術判断を1ファイルにまとめた短い文書を指します。
言い出したのは Michael Nygard さんで、2011年11月に公開された記事がこの言葉の出発点になりました。
設計書との違いは、扱う単位にあります。
設計書が「システム全体が最終的にどうなっているか」を描くのに対して、ADR が扱うのは「その日、何を捨てて何を選んだか」という一回ぶんの判断だけ。
だから1本あたりの分量は A4 で1枚に収まる程度で、書くのに30分もかかりません。
そして置き場所はドキュメントツールではなく、コードと同じリポジトリの中が推奨されます。
判断とコードが一緒にバージョン管理されていれば、片方だけが古びていく事故を防げるからですね。
5つの節で書く｜Nygardのテンプレート
Nygard さんが示した書式は、タイトル・Context・Decision・Status・Consequences の5つという素朴なものでした。
Context は「どんな事情があったか」で、チームの人数・締切・既存システムの制約といった、当時の前提を書く場所。
Decision は「何を選んだか」を一文で言い切る節になります。
Status は「提案中（proposed）」「承認済み（accepted）」といった、その決定が今どの段階にあるかを示す短いラベル。
そして最後の Consequences が、実はいちばん後から効いてくる節です。
ここには良い影響だけでなく、その選択によって引き受けることになった不便や制約も並べて書きます。
「この方式にした結果、ローカル環境の起動が遅くなる」といった負の側面を最初から明記しておくと、後から来た人が同じ議論を蒸し返さずに済むのです。
良いことだけを書いた ADR は、読み手にとって判断材料になりません。
書き換えずに、新しい1枚で上書きする
ADR でいちばん独特なのは、一度受け入れられた記録を後から書き換えないという運用でしょう。
判断が覆ったときは、古い記録を修正するのではなく、新しい ADR を書いて古いほうに「superseded（置き換え済み）」という印を付けます。
Nygard さんの記事も、覆った決定について「それが決定だったことを知るのは今も意味がある。ただしもはや現在の決定ではない」という趣旨の説明をしていました。
つまり ADR が残しているのは、正解の一覧ではなく判断が動いてきた軌跡のほう。
「なぜ今の形になったのか」を追いたい人にとっては、途中で捨てられた案こそが手がかりになります。
上書き保存してしまうと、その手がかりが毎回消えてしまうのですね。
ちなみに Thoughtworks の Technology Radar でも、この軽量な ADR は2018年5月版で最も推奨度の高い Adopt に置かれていました。
テックリードにとっての使いどころと、外し方
チームの技術判断に責任を持つ役割から見ると、ADR の効き目は「後から読める」ことだけではありません。
書式が Context と Consequences を要求するので、決める前の段階で前提と副作用を言語化させられるという副産物があります。
「なんとなく良さそう」で通っていた案が、Consequences を書こうとした途端に穴を露呈する。
この書くことが検討そのものを兼ねる性質が、レビューの場を助けてくれます。
とはいえ、この仕組みが外れるパターンもはっきりしているのです。
すべての判断を ADR にしようとすると、この仕組みは真っ先に形骸化します。
ライブラリのマイナーバージョンを上げた程度の話まで1枚起こしていては、書く側も読む側も続きません。
対象は「後から覆すのに大きなコストがかかる判断」に絞るのが現実的でしょう。
テンプレートの種類そのものは Nygard 形式のほかにもいくつかあり、ADR の情報が集まっているサイトで見比べられます。
テックリードが担う「技術・人・プロセス」の3つの軸のうち、ADR は技術とプロセスの境目に効く道具です。
最後に
ADR は、新しい設計手法ではなく判断の理由に住所を与えるだけの仕組みでした。
決定そのものはコードに残る。
けれど、そのとき捨てた選択肢と、引き受けた不便は、意識して書かないと残りません。
まずは直近で一番揉めた技術判断を、5つの節にあてはめて1枚だけ書いてみる。
そこから始めるのが、いちばん軽い入り口になるはず。
以上です。
コメントを残す