こんにちは。2025年1月にLeaner Technologies に入社しました おぐち です。
私が所属する「Leaner見積」というプロダクトの開発チームでは、Notionを使ってADRを書き、設計判断を記録しています。
ですが、ADRのフォーマットが明確に決まっておらず結論に辿り着きにくいといった課題もありました。
この記事では、その課題を解消するためにADRの運用を整備し、ADRのテンプレートを見直した事例を紹介します。
ADR（Architecture Decision Record）とは
ADR（Architecture Decision Record）とは、ソフトウェアアーキテクチャに関する設計判断を文書化したものです。
ADRについての詳細な説明はこの記事では割愛します。
参考:
テンプレートは存在したが...
私たちのチームには私の入社前からADRのテンプレートが存在していました。
改善前のADRのテンプレートは「結論」「検討過程」の2つのセクションで構成されており、これを複製してADRが作成されていました。
しかし、実際にはこのテンプレートはあまり活用されておらず、フォーマットが統一されていませんでした。
当初は、以下のようなADRの一般的なフォーマットを適用し、これをもとに意思決定の内容とその理由を記録できるようにすれば解決すると思っていました。
- タイトル(Title)
- コンテキスト(Context)
- 決定(Decision)
- ステータス(Status)
- 結果(Consequences)
ですが、チームで議論した結果、そもそもADRを作成する目的や運用の共通認識がないことがわかり、そこから整理していくことになりました。
ADRという名目で運用されているものの、実際には意思決定の結果や理由が記録されていないものもあり、後から見た時に情報が把握しづらい状況でした。
ADRをいつ、何を目的に作成するか
目的
過去の設計の意思決定について、過去の状況・選択肢を含めて簡単に見返せるようにする ことを、ADRを作成する目的として定義しました。
この共通認識をチームで持ったことで、意思決定の内容を把握しやすくするためにADRを構造化する必要があることを再認識できました。
いつ書くか
私たちのチームでは実現したい要件は別のドキュメントにまとめており、その整理中または整理後に発生した、技術的な意思決定を必要とする内容に対してADRを作成することにしました。
「この内容は書かない」という明確なルールはありませんが、主にDB設計案を検討する際や、ユースケースを実現するための複数の手段から一つを選定する際に作成しています。
改善後のテンプレート
上記の目的に合うように改善したテンプレートはこちらです。
主な変更点
ストック情報とフロー情報を区分けした
検討過程で残した情報（フロー情報）と結論（ストック情報）は明確に分け、検討過程の内容はトグル内に記述するようにしました。
改善前のADRのテンプレートでも「結論」と「検討過程」でセクションを分けていましたが、この構成があまり活用されていなかったことと、検討過程の分量が多く、結論が埋もれがちだったため、それを防げるフォーマットにしました。
また、検討した案とそのPros/Consはストック情報として目立つようにセクションを分け、結論として選択した案とその理由、別案があれば選択しなかった理由を記述するようにしました。
ADRの運用フローを定義
以下のフローで運用することに決定しました。
- ADRの作成者はADRに背景・必要要件、案、そのPros/Consを記述する。ステータスは「Draft（作成中）」。
- ADRを書き終えたらステータスを「In Review（レビュー中）」に変更し、他のチームメンバーに確認を依頼する。
- 作成者以外のメンバーは、ADRの内容を確認し問題なければLGTMボタンを押す。内容に意見がある場合は「検討内容」のところに切り出す。
- 議論が完了したら、ADRの作成者は結論（決定した案とその理由。別案があればそれを選ばなかった理由）を書いて、作成者以外のメンバーに共有する。
- 作成者以外のメンバーから反対意見がなければステータスを「Complete（完了）」に変更して完了とする。
また、ADRは特定時点での意思決定の記録として扱い、変更が必要な場合は既存のものを修正せず、新しいADRを作成することにしました。
運用を定める前までは既存のADRの内容に変更があった場合、上書きするか新しいADRを作成するかの認識がチーム内で曖昧になっていましたが、このように定義したことでADRのステータスの運用も明確になりました。
まとめ
目的を決めても決めなくても、結果的にADRを構造化するというゴールは同じだったかもしれませんが、そこに至るまでにADRの目的について共通認識を持てたことで、ADRテンプレートを整備することへの納得感が生まれたのではないかと感じています。
まだ運用は始まったばかりですが、この対応によって過去の設計判断を見返す際に、初見の人でも把握しやすい構造になったのではないかと思っています。
Discussion