こんにちは、虎の穴ラボのKanonです。
今回は僕が所属するチームで新たに始めたADRを書く取り組みについてです。
実際にADRを始める準備から、実際に3ヶ月ほど運用してみてどうだったかをお話します。
「ADRってなに？」っていう方や、同じくADRの導入を検討されている方の参考になれば幸いです。
導入のきっかけ
ある日。これまで動いていたCIがとあるライブラリのバージョンが古いことによりビルドに失敗するようなりました。
原因を調べていくと、どうやらそのライブラリのバージョンは以前から上げずに固定されているようでした。
けど、「これまでどうしてバージョンを上げていなかったのか？」「そもそもなぜそのライブラリを導入したのか？」という理由がわからない状況でした。*1
結局バージョンを上げる方向で対応したのですが、この「どうして？」という経緯は結局わからないまま。
この「"どうして？"がわからない事態をどう防ぐか？」を考えた時に一番最初に思い浮かんだのがADRでした。
ちょうどYAPC::Hakodate 2024ではてなの大仲さんのADRに関するセッションを聞いた直後だったこともあり、実践してみるのにちょうど良い機会だと思い、まずは自分のチームのなかで運用してみることを提案しました。
概略: ADR
ADRとは略称で、 Architecture Decision Records の頭文字をとったものです。直訳すると アーキテクチャ決定の記録 というところでしょうか。
その名の通り、構築計画中のソフトウェアアーキテクチャの重要な側面に関してチームが取った選択について説明する文書のことを指します。
ADRにはライフサイクルがあり、Proposal → Ready For Review → Approved の流れを踏みます。
書く内容は自由なのですが、未来の自分やチームメンバーがその技術選定に対しての意思決定の内容について把握できるものである必要があります。
なので少なくとも以下のことを書く必要があると考えています。
- なにを選んだのか？
- なぜ選んだのか？
- なぜ選ばなかったのか？
- 決定の背景
- 決定がプロジェクトまたはその成果物にもたらす結果
導入にあたってチームメンバーたちといろんなドキュメントや書籍をあたりましたが、簡潔かつ分かりやすかったのは以下の2点でした。
ADRについてもっと詳しく知りたい人や、実践内容を踏まえてADRを知りたいという方にはものすごくおすすめです。
導入するまでの流れ
自チームで提案
全社・全チームを最初から巻き込んで始めるにはカロリーが高いうえ腕力がいるので、まずは自チームでちいさくはじめてみることをスプリントレトロスペクティブで提案しました。
余談ですが、虎の穴ラボはこういった提案がすごくしやすい環境です。提案が受け入れられれば、導入までのフットワークもすごく軽いです。みなさん勉強家なので、すぐに各々でキャッチアップを始めて改善に取り組むことができます。
自チームで提案した結果みなさんに興味を持っていただき「やってみよう！」となったので、まずはADRについてチームでキャッチアップするところから始めました。
チームメンバー全員でキャッチアップ
キャッチアップをするにあたって、まずは僕がADRについていろんなドキュメントに目を通し、簡単に内容をまとめたスライドを作成しました。
そのスライドを使って簡単にADRについて説明したうえで、特にわかりやすいと感じていたドキュメント(先に紹介した2つです)をチームメンバー全員で一緒に読む時間を設けました。
このMTGの時間は1時間くらいです。ADRそのものの概念はそんなに難しくないので、1時間で十分キャッチアップすることができました。
どう運用していくか？を決める
キャッチアップが済んだところで、「では自分たちはどうADRを運用していくか？」を決めていくことにしました。
具体的には、キャッチアップ直後は以下の3つについて課題を感じていました。
- ADRに何を書くべきか？
- ADRをどこに置くか？
- ADRのライフサイクルをどう管理するのがいいか？
ここではこの3つの課題に対するアプローチについて話します。
ADRに何を書くべきか？
まず最初にやったことは、他のADRのテンプレートを見ることでした。先の大仲さんの資料でもテンプレートの所在について触れられています。
僕たちは以下のページを参考にしました。
その上で僕たちは以下のことについて書くことにしました。
- TL;DR
- 背景・問題
- 影響機能
- 関連案件
- 選択肢
- 決定事項
- 決定理由
- 決定するにあたった理由
- 否決するにあたった理由
- 導入することで得られる効果
- 備考
なかでも特に重要だと考えていたのは、決定理由のうち否決するにあたった理由です。
「なぜそれを選んだのか？」は実際のアーキテクチャやソースコードなど現状あるものから推測できたりします。導入の背景や解決したい問題はBacklogのチケットやWiki、KPTを管理しているスプレッドシート*2に残っています。
しかし「なぜそれを選ばなかったのか？」という理由がどこにも残っていない状況でした。「なぜやらなかったのか？」という理由はその当時の状況から変わってしまうと忘れ去られてしまいがちです。今回の導入の経緯もそれに起因しているため、この項目を入れることは問題解決のためにはマストでした。
ADRをどこに置くか？
候補としてはGitHubのリポジトリ、スプレッドシート、Backlogでした。理由は、すでに虎の穴ラボの全員のアカウントが存在するサービスがこの3つだからです。
結果としてGitHub Repositoryにマークダウンで保存していくことにしました。それぞれを選んだ・選ばなかった理由は以下のとおりです。
- GitHub Repository
- ラベルを使うことで分類分けができ、検索性が高い
- PRを経由することで確実なレビューができる
- Scheduled Remindersを使うことで未レビューの通知が来る
- Openになっているものに対して常に監視することができる
- スプレッドシート
- レビューを確実にできない
- サマリーを作るのは得意だが、検索性は良くない
- Backlog
- レビューが終わらない場合にボードにチケットが残り続けるのは嬉しくない
- 完了になっていないチケットの存在を自動で通知する手段がない
- Wikiは検索性が良くない
ADRのライフサイクルをどう管理するのがいいか？
先に「ADRをどこに置くか？」について話しましたが、実は「どこに置くか？」を考える際にADRのProposal → Ready For Review → Approvedのフローをどのように管理するか？も一緒に考えていました。
これを踏まえた段階で、スプレッドシートは選択肢から外れることになりました。基本的に状態を管理したり、分類したりといった機能が搭載されていないからです。*3
そしてBacklogとGitHub Repositoryの2択になった結果、選ばれたのはGitHub Repositoryでした。理由はいくつかあります。
まずはレビュー時のコメントがADRの何についてコメントしているかが一目瞭然な点です。
Backlogの場合はコメントが縦に伸びていくため、コメントを見ただけではADRの何について議論しているのかがわかりづらいです。またコメントの並び順も特定のトピックごとに並ぶわけではないので、読みづらい。結果、読まなくなっていく。読まれないから書かなくなるという未来を危惧していました。
その点GitHubのPRでは、マークダウンで書いたADRに対してコメントを入れていくため、トピックが一目瞭然かつトピックごとにスレッドが並ぶため、読みやすいです。
もう一つはProposal → Ready For Review → ApprovedのフローをPRレビューに乗せられることです。
書きかけのADRはDraftでPRを書いておくことで、Ready For Review以前の状態でも誰でも見ることができます。Ready For ReviewになればPRをオープンし、レビュワーを割り当てます。Approveされればマージして終了です。
他にもSchedule Reminderを設定しておくことでADRのレビュー忘れを防止することができます。また、僕たちのチームではGitHubのSlackアプリを連携しているので、通常のソースレビューと同様にレビュワーにアサインされた時点で通知が来ます。この通常のソースレビューと同じサイクルで回せるという点が重要だと考えました。習慣化されたレビューの中にADRが入ってくるだけなので、何か特別新しいことを習慣化する必要がないです。なので、無難にチームに浸透していくことを狙いました。
3ヶ月ほど運用してみて
負担
特に感じていないです。そもそもADRを書く機会というのがそこまで多くないからです。実際3ヶ月の間に数人で運用した結果、作成したADRは4件ほどです。
またADR自体が軽量なドキュメントなので、これまでに作成した4件のADRはいずれも4~50行程度のものです。
レビューの負担というのもそこまで実感はありません。先にも書いたとおり、通常のソースコードと同じ要領でレビュー依頼が自動で飛んでくるため、レビューの存在を頭の片隅に置いておくような認知負荷もかからないです。
影響
運用を初めて3ヶ月なので、意思決定の内容が記憶に新しいです。なのでそこまで恩恵を受けている感はまだないです。
が、このブログを書くにあたって最初にお試しで書いたADR導入のADRがものすごく役に立ちました。導入までの流れなどは完全にADRに書かれていたことから引っ張ってきています。この点でADRの威力を体験することはできました。
課題
現状は自チームで運用している状態なので、これを同じプロダクトを作る別チームへ広めたいです。果ては虎の穴ラボ全体へ広げていくことで、「なんでこうしたんだっけ？」「なんでこうしなかったんだっけ？」がない世界を作りたいです。
一応GitHub Repositoryは他のチーム・プロダクトであっても問題なく運用できる想定で設計はしています。小さく始める場合は、スケールするときのことも視野に入れておくと後から困らずに済みそうだと考えています。
おわりに
やってみて一番実感したことは、"ADRはWhyを残すためのHow"ということ。そして、そのHowとしてなかなかに優れたものだということでした。提案〜導入までは別のタスクの片手間で準備していきましたが、直接かかった時間は1日くらいでした。それくらい簡単に始めることができます。
「なんでこうしたんだっけ？」「なんでこうしなかったんだっけ？」に悩んでいる方はこの機会にぜひ取り組んでみてはいかがでしょうか。
Fantia開発採用情報
虎の穴ラボでは現在、一緒にFantiaを開発していく仲間を積極募集中です！
多くのユーザーに使っていただけるtoCサービスの開発をやってみたい方は、ぜひ弊社の採用情報をご覧ください。
toranoana-lab.co.jp
