ADRについて調べたことをまとめてみる

過去の経緯とか、どういった設計思想で今こうなっているのか？がなかなか分らなかったりするという課題があるので、ADRをやってみると良いんじゃなかろうか？と思い、いろいろと調べたことをまとめておく。

ADRの目的や得たい状態

• 自チーム内での認識のズレを減らしたい
• 他のチームが自分たちの意思決定を追えるようにして、どういった背景があってその選択をしたのか？を把握できるようにしておきたい
• 意思決定当時の文脈・背景を把握することで、「今はどうだっけ？」と文脈や背景の変化から改めて意思決定をするべきかどうかを考える材料にしたい
• 狙う効果
  • 自チームで作るものに対するオンボーディング時の理解促進
  • アーキテクチャ見直し時の判断軸の一つになる
  • 「なぜこうしたのだったっけ？」みたいな掘り返しが減る
  • 振り返って、この意思決定がどうだったか評価され、次に生かされる

特に重要そうな要素

ADRを行う上で、下記のポイントを押さえながら実施する。

• 小さく軽量な意思決定の記録にする
• 「何をした・どのようにした」みたいなWHATはもちろん、なぜそうしたのか、WHYを記録する
• 想定読者は誰か？を意識して、未来の意思決定を助けるものにする
• 仕様書にはしない。あくまでも技術的意思決定（技術選定など）のログにする
• 過去の意思決定の理由がわからないが故に、同じ轍を踏むことを避ける

どうやって実践していくか

具体的にどうやっていくかは、下記の文章構成と運用フローを実施してみようと思う。
ドキュメントの保存先の使用ツールだけとても悩ましい。GithubのIssueを使うケースが多いみたいだけど、特定のリポジトリにコンテキストが限られてしまうので、ある程度横断した意思決定を置きにくい。会社で使ってるドキュメントツール（弊社の場合はConfluence）だと、ある程度横断的なことも置きやすいけど、あくまでも自チーム内での取り組みに限られてしまう。
ひとまず小さく始めるという面で、会社で使ってるドキュメントツールで置き場所を作ってやってみようかな。

文章構成

• タイトル
  • 「ADR :」から始め、内容を簡潔に表現
• ステータス
  • 「提案済み (Proposed)」「承認済み (Accepted)」「代替済み (Superseded)」「非推奨 (Deprecated)」、「棄却 (Rejected)」の５つ
• コンテキスト・シチュエーション
  • 決定が必要となった背後にある動機や理由
  • 決定時のビジネスにおける制約や会社、チームの状況
  • 重要な決定ほど外的要因に左右されるような、決定に作用した状況を記載します 意思決定の状況があることでテクノロジー以外の部分で決定に作用した内容を把握できるようになります
• 決定時に参照した材料
  • 決定の材料を記載します。意思決定をスムーズに行うために必要な項目です
  • 比較検討して、採用しなかったものなど
• 決定事項と理由
  • アーキテクチャ決定そのものについて記述
  • 決定に至った背景・理由も記述する
• 影響
  • 決定による結果・影響、ないし成果 (outcomes) やアウトプット・フォローアップを記述します
  • プラスの影響、マイナスの影響、両方を記載する

運用フロー

• 草案を書く
• チームで議論
• 承認or否決
• 新規の決定の場合、ステークホルダーに周知・説明する
• 既存の決定の改定の場合、既存ADRをDeprecatedにする