ADRとは

ADR（Architecture Decision Record）は、プロダクトやシステムに関する重要な設計判断を1つずつ記録する簡潔な文書。通常Markdownで1ページ以内に収める。

参考: bliki-ja: ArchitectureDecisionRecord

本質的な価値は2つ

1. 「なぜこうなった？」に答えられる

コードは「何をしているか」は読めるが、「なぜその設計にしたか」は時間とともに消えていく。ADRはその「なぜ」を残す仕組み。

2. 書くこと自体が思考を強制する

曖昧な合意や雰囲気での決定を防ぐ。特にチーム開発では「実は違う理解だった」が表面化し、議論と合意形成につながる。

実践面の良さ

  • コードと一緒にgitリポジトリに入れる（doc/adr/）ので、コードと一緒に追跡できる
  • Markdownで1ページ以内。運用が重くない
  • 「廃止」ステータスがある — 過去の決定を消さず、歴史として残しつつ新しい決定に移行できる
  • 却下した代替案とその理由も記録する — 同じ議論の繰り返しを防げる

ステータス管理

提案済み → 受け入れ済み → 廃止済み

の3段階で履歴を保持する。廃止しても削除しないのがポイント。新しいADRから古いADRを参照し、「あのときはこう決めたが、今回はこう変えた」という流れが追える。

一番刺さるポイント

半年後の自分（or 新メンバー）が「なんでこんな設計なの？」と思ったとき、ADRがあれば答えがある。なければ当時のSlackを掘るか、誰かの記憶に頼るしかない。

軽量なのに効果が大きい — このバランスの良さがADRの最大の魅力。