この記事は、株式会社カオナビ Advent Calendar 2023の２日目です。
カオナビでは2022年9月からArchitectural Decision Record（以下ADR）を導入開始しました。本記事ではADRを導入し実際に一年間運用して見た経過をご報告しつつ、導入のポイントや注意点について紹介します。
ADRをなぜ導入したのか？
まずADRについて簡単に説明すると、「アーキテクチャー設計の記録をドキュメントとして残すこと」 です。Michael Nygardのブログ記事が初出のようです。
ソフトウェア開発を行っていく間には、途中で様々な設計決定をする必要があります。例えばウェブアプリケーションであれば、データベースはMySQLにしようとか、キャッシュはRedisを使おうとかという実行環境の決定の話から、実際のプログラムの基本構造といったところまで様々です。
この設計決定は、口頭のMTGであったり、Slackなどのチャットツール上で議論しながら決められていきます。その決定方法自体には異論はないのですが、問題はその内容が保存されていないことです。どんな理由でその決断をしたのか、空気感も含めて知りたいですが、記録が無いと後から正確に知ることは出来ません。ソフトウェア界隈ではこういったわかりにくい過去の決定内容を調査することを考古学などと呼んだりもします。
Slackのログなどに残っていればマシで、口頭で決められたものなどに関しては、当時の人間が居なければ絶対にわからない決定理由があります。ADRはそういった設計決定を記録しておいて、将来的にも分かるようにしようというものです。
カオナビにおけるADR
個人的に、過去にADR導入で失敗したことがあったので、思いっきり人のやり方を参考にしようという方針で考えました。ソフトウェアアーキテクチャーの基礎という本では 「第19章 アーキテクチャ決定」 でADRについてまるまる一章書かれています。
この内容を全面的にリスペクトして、記述内容から、使用するツールまで策定しました。
使用ツール
履歴が残り、かつ社員が自由に触れて、プログラマー以外でも容易に編集可能であるツールが望ましいということで、Confluenceを選定しました。もともと弊社内でWikiとして使われていましたので、誰もが自然に使うことが出来ます。
Wikiのリンクはソースコード管理ツールのアカウントが無くても、基本的に社員であれば自由に閲覧することができるため、情報共有も簡単でした。
導入にあたって用意したもの
ADR導入をADRとして記述してサンプルとしました。
また、記述を容易にするためのテンプレートを用意しました。このテンプレートに合わせて、順番に内容を記載していけば、簡単にADRを作れるというものです。
受け入れられるまでに時間がかかることは予想していたので、導入当初はとにかく同じ所属部署のメンバーでADRを積極的に活用して記述するようにしました。
活用事例
横断的なログの設計
組織横断での設計で役に立った例です。ADRという形で最初は曖昧な設計でしたが、コメントのやり取りを行う中で明確化されました。以後はログに関して何か議論するときのベースの資料として、このADRを参考することができるので、非常に効率が良くなりました。
Feature Toggle
ビッグバンマージが開発チーム内で問題視されていた中で作成したADRです。策定当初はFeature Toggles自体の認知度が高くなかったのですが、以後の議論の起点として使えるため、このADRも非常に役に経っています。現在は、サンプル実装などもADRに紐づけてWikiを追加しており、Feature Togglesを使うためのすべての情報がここに詰まっています。
参考記事 : ビッグバンリリース対策でFeature Toggleを導入したら、開発チームが「デプロイできる状態」をより深く考えるようになった
一年運用を続けたADRの今
現在では、70以上のADRが採番されており、バックエンド・フロントエンド、はたまたQAなどのいろんな文脈で、意思統一を図るための文書としてADRはある程度の地位を確立しました。
運用を続けていく中でわかったことは、ADRはある種「街の掲示板」のような役割を果たしてくれるのだなということです。突然決定だけが行われるのではなく、コメントを募集するような未決定状態のフェーズから衆目に晒すことができるため、組織内にジワジワと意思決定を浸透させていってくれます。
未熟な状態の設計決定でも、コメントのやり取りを行う中で明確化されていくので、記録も残るし設計も洗練されるし、良いことづくしです。実際にADRで策定された機能であったり、設計上の変更がリリースされた場合も、すでに全体に情報が周知された状態になっており良かったです。
まだまだ油断は禁物ですが、なんとなく開発に携わるメンバーにおいて、全体に共有しつつ、ゆるゆると妥当な合意を得る手段としてADRが認知されてきたことを感じています。
まとめ
ADRは、"現在"にも役に立つし、"未来"にはもっと役立ちます。あのとき、どんなことを考えてその決定をしたのかが思い出せますし、コミットコメントに参照リンクとして忍ばせれば、開発者も完全にコンテキストを理解することが出来ます。
ただし、導入に際しては、旗振り役となるメンバーが積極的にADRを活用する姿を見せていくことが大切です。そうすれば、ADR自体がサイロ化することなく、チーム横断でみんなから広く意見を集めることができるメディアなのだという態度を示すことが大切だと思います。
歴史の長いウェブサービスを運営している会社様に置かれましては、将来の開発者がより妥当な決断を下せるようにするためにも今の情報をADRを残してみてはいかがでしょうか？
おまけ : 過去の失敗
個人的にはADRを過去にも取り入れようとしたことがあったのですが、その時は失敗してしまいました。その失敗の最たる原因は、ADRをソフトウェアと一緒にソースコード管理ツールの管理下においたことです。
結果としてADRは、一つのソフトウェア内にロックインされました。ADRという会社の共有資産としてはではなく、特定のソフトウェア内の情報になってしまったのです。そのプロジェクトに参加していた人はそれを閲覧できるが、それ以外の人からすれば見に行く動機がありません。ドキュメントが残っていること自体は良いのですが、ソースコード管理ツールを自由自在に操れるのは基本的にはプログラマーです。そのため、ディレクターや関連する他部署の人からは参照しづらいADRになってしまいました。
人から見られることのないドキュメントは、批判を受けないので修正もされずに野放しになります。結果的に、この時のADRは作り始めて数週間で廃れ始めて、そのうち誰もそのドキュメントを参照しなくなりました。