ADR（Architecture Decision Record）は、ソフトウェアアーキテクチャに関する重要な意思決定を記録するためのドキュメントである。
ADRを書く内容が決まっていても実際書いてみると人によって内容がバラついたり、そもそも何を書けば良いのか分からなかったりして、形骸化してしまうことがある。
私の経験上大事だと思うことを4つにまとめた。
最初の、そして最も重要なルールは「1つのADRには、1つの意思決定だけを書く」ことである。
「データベースと認証基盤の選定」のように、複数のトピックを一つのドキュメントにまとめてはいけない。もし将来、データベースだけを変更することになった場合、ドキュメント全体を「無効（Superseded）」にするのか、部分的に修正するのか、管理が非常に複雑になるからである。
また、複数の決定が混ざっていると、レビューの際に「DBには賛成だが、認証には反対」という意見が出た場合、合意形成がストップしてしまう。
タイトルに「AとBについて」と書きたくなったら、それは2つのADRに分割するサインである。
ADRはシステムの説明書ではない。「分岐点（意思決定ポイント）」の記録である。
ソフトウェアアーキテクチャの基礎で語られているソフトウェアアーキテクチャの第二法則に「『どのように（How）』よりも『なぜ（Why）』の方が重要である」という言葉がある。実装の詳細（How）はコードを見ればわかる。ADRに残すべきは、コードからは読み取れない「選択の理由」と「捨てた選択肢」である。
特に重要なのが「結果（Consequences）」のセクションである。メリットだけでなく、その決定によって生じるデメリット（トレードオフ）やリスクを記録する必要がある。
「開発スピードを優先するために、整合性の担保を一部犠牲にする」といった判断こそが、将来にわたって価値ある情報になる。
ADRは、チームの議論と合意を固定化し、後から変更しない「決定の証」である。いきなり清書しようとせず、まずはホワイトボードや軽量なドキュメントなどでチームと議論し、合意形成を図ることが重要である。
ADR執筆時も文章化する前に、書くべき事項を箇条書きでまずは書き出して、アウトラインベースからレビューを始めるのも良い。
議論の発散と収束のプロセスを経ることで、チーム全体の理解と納得感が高まり、ADR自体の品質も向上する。
ADRは技術的なドキュメントであるため、テクニカルライティングの原則を適用することが効果的である。
参考：developers.google.com - Technical Writing
ADRに限った話ではないが、技術文書を書く際には誰が書いても文章の質が一定になるようにする心がけが重要である。
ADRのフォーマットは様々存在するが、Nygard氏が提唱する形式は自由度が高く、特に「結果（Consequences）」セクションは何を書くべきか迷いやすい。組織やチームに合わせてフォーマットをカスタマイズする際は、意思決定における重要な判断軸を取りこぼさない構造を意識する必要がある。
例えば、トレードオフは意思決定の核心であるため、「トレードオフ」を独立したセクションとして設けることで、メリット・デメリットの検討が形骸化せず、判断の根拠が明確に残る。
ADRを単なる「記録」で終わらせず、将来の意思決定を支える資産にするための4つのポイントを紹介した。
意思決定の記録を的確に記録しておくことは、将来の資産となり、チームの一貫性と理解を深める助けとなる。