こんにちは。スタディサプリのWeb開発をやっている@highwideです。
今日は、自分の所属する"コーチングチーム"(個別指導コースや合格特訓コースの機能開発を行っています)が、最近のプロジェクトで利用した「アーキテクチャ・デシジョン・レコード」、通称「ADR」について紹介したいと思います。
アーキテクチャ・デシジョン・レコード(ADR)とは
「ADR」「アーキテクチャ・デシジョン・レコード」という概念を知ったのは、社内で行っていた「Design It! プログラマーのためのアーキテクティング入門」(以後「Design It!」)の読書会でのことでした。
最初にそのキーワードが登場する「11.2.3 必要なときだけ形式的な記述に投資する」では、「"膨大な量のドキュメントになる傾向"がある形式的なドキュメンテーション」に対比して、以下のように紹介されます。
伝統的なドキュメントから始める代わりに、ホワイトボードのスケッチやシステムメタファーから始めよう。判断を下す度に、アーキテクチャデシジョンレコード(ADR)を1つずつ記録する。(中略) アーキテクチャが融合し始めたら、必要に応じて(またはステークホルダーがそれを求めたときに)、従来のドキュメントを作成しよう。
- Michael Keeling、島田浩二 訳、2019「Design It! プログラマーのためのアーキテクティング入門」、オライリー・ジャパン P177
システムアーキテクトが持つべきデザインメソッド集として構成されている第Ⅲ部においては、「設計をタンジブル*1にするアクティビティ」の1つとして以下のように説明されます。
テキストベースの軽量なテンプレートを使用して、アーキテクチャ上の設計判断を記録する。軽量なアーキテクチャデシジョンレコード(Architecture Decision Records:ADR)は、実績のあるアーキテクチャ手法に対する開発者寄りのアプローチだ。設計判断を記録していくことで、それらを共有し分析することが容易になる。意思決定の履歴を残すことで、現在のアーキテクチャについてのコンテキストを、その過程と結びつけて提供できる。
- Michael Keeling、島田浩二 訳、2019「Design It! プログラマーのためのアーキテクティング入門」、オライリー・ジャパン P302
重要なアーキテクチャ上の設計判断とその判断の背景および影響を書き留める。各ADRには一つの設計判断を記述する。どの設計判断が、ただの詳細設計でなく、アーキテクチャに影響するものかは、システムやチームによって異なる。
- Michael Keeling、島田浩二 訳、2019「Design It! プログラマーのためのアーキテクティング入門」、オライリー・ジャパン P303
本の中では、ADRのテンプレートの紹介が続きます。
またWeb上でも、How toやテンプレート例などを見ることができます。
- GitHub上のテンプレート集リポジトリ: https://github.com/joelparkerhenderson/architecture_decision_record
- Spotify社の例: https://engineering.atspotify.com/2020/04/14/when-should-i-write-an-architecture-decision-record/
そんなADRを、僕たちのチームでどのように利用してきたか実例を出しながら紹介したいと思います。
ADRを利用するようになるまでの経緯
先日、コーチングチームでは、コーチとユーザーの方がやりとりするためのメッセージ機能の脱モノリス化を推し進め、Goによるマイクロサービスとして切り出すことに成功しました。*2
プロジェクトは、2020年の秋頃からチームのWeb developer主体で始まったのですが、明示的にプロジェクトのリーダーやマネージャーというロールを置かず、基本的には「皆で考え、皆で決め、皆で実装する」のスタイルで進みました。この仕事の進め方は、皆の納得感を形成しながら進められるという点では、自分たちに合った良い進め方だったんじゃないかと振り返っています。
一方で、このやり方でプロジェクトの中盤以降に直面した思わぬ落とし穴は「想像以上に自分たちが決めたことを覚えていないし、記録できていない」ということでした。
たとえば以下のようなことについて、チームで一度は議論したはずなのに「結局どうなったんだっけ...」といったことが増えました。
- 「Go + レイヤードアーキテクチャ」によるWeb API開発する中で、"DBのTable"と"Infrastracture層のロジック"と"ドメインロジック"をどのように対応させるのか(あるいは対応させないのか)
- マイクロサービスを切り出す中で、そのマイクロサービスと既存モノリスの接点と境界をどのように設計すべきか
- コーチの業務終了や担当コーチの変更などによるデータ更新は、物理削除すべきか、削除フラグを持たせるべきか、Archivedテーブルにデータを移すのか
- 期日に対するスコープ合意の中にどのissueまで入れるべきか、どの程度実装を作り込むべきか
こうやって振り返ってみると「こんな大事なことについての認識がバラバラなままで実装してたっけ...？」と思わなくもないのですが...
- 検討段階では細部まで決めきらず、手を動かしながら対応方針を考えたいという姿勢のメンバーが多かったことで、複数の問題を並行して解決する必要があった
- モブプログラミング(紹介記事)での議論では、設計についての合意事項はドキュメントを残すのを忘れがちだった
- SlackのWorking Out Loud(紹介記事) Threadで検討が始まることがあっても、あとから振り返ってわかりやすい体系的な書き方になっていなかった
といった状況に、プロジェクトが終わった今ならば気がつくことができます。
そんなプロジェクトのさなか、この状況を良くするために、チームのメンバーも多く参加する「Design It!」読書会で学んだ"ADR"を利用しはじめたのでした。
実際のADR利用例と、それによって得られたもの
ADRは以下のようにGitHubのissueとして用意し、続くコメントにそれぞれの"レコード"を記録するようにしました。
実際の"レコード"はこんな様子です。
結果、思った以上に、ADRはチームにフィットしたように思います。プロジェクト後に行ったKPTでの振り返りではこんな声もあがりました。
一方で「これってただの"議事録"では？そんなにすごいものなの？」というセルフツッコミも沸々と湧き上がってきます。何が良かったのか、もう少し掘り下げてみたいと思います。
何を記録すべきで、何を記録しなくてよいか...がわかりやすい
「このミーティングでのやりとりは、(すべて)議事録に残しましょう」となると、なかなか気が重い話に思えます。また「議事録係」のような役割を置いてしまうと、その人は議論に参加しにくくなるということが起こりがちです。
「網羅的な設計ドキュメントを書いてから実装に移りましょう」というのも、あまり現実に即しているとは言えません。
ADRは「Design It!」にもあるように、"軽量"な記録です。
誰が何を言ったかを記録する必要はなく、ひとつの設計判断があらゆる条件に耐えることを担保する必要もなければ、プロジェクト全体を網羅するようなドキュメントになる必要もありません(...という想定で運用をしていました)。 チームの一つ一つの意思決定が後から振り返りやすいように記録されていればOK...と考えれば記述のハードルが下がったように思います。実際に、プロジェクト進行が佳境の中では「テンプレートにとらわれずに最低限書いておこう」という運用がされることも多かったです。
設計判断をカジュアルに記録しようという文化の形成
上述したような「何を記録すべきか」という感覚がチームに養われたことで、それが文化となっていく様子も見ることができました。 ADR issueを作って以後...
「それってADRに書いてありましたっけ？」
「じゃあ、これはADRに書くべきですね」
といったやりとりが自然となされるようになりました。
この手の取組みは、皆でやっていく姿勢がなければ持続しにくいので、"ADR"というフレームワークを内面化できたことで文化形成に繋がったのはすごくいい話だったと思っています。
プロジェクトを通しての設計判断の積み重ねが散逸しない
Quipperやチーム特有の事情かもしれませんが、諸々のドキュメンテーションにGitHub issueを多用し、別の情報Stockツールをそれほど利用していない自分たちにとって「このプロジェクトが終わるまで、1つのissueのコメントに設計判断を書き連ねていく」という点も良かったと言えます。複数のissueやGoogle Docsに情報が散らばっている...といったことを避けられたのは、ささやかな嬉しさでした。
※ 個人的には「新しいissueを1つ立てるよりも、issueに1個コメント追加する方が気軽」と思っているので、そういった意味でもこのやり方はありがたかったです...。とはいえ、このあたりはチームやプロジェクトの特性によっても、より適した運用は変わりそうです。
最後に
Quipperのコーチングチームで行っていたADRの運用について書きました。
ここに挙げたのはADR利用の一例と言えます。というのも、社内では別チームが以前よりADRの記録をしていて、僕たちのチームとはやや書き方の方針が違うことから、ある程度は柔軟に運用できる余地があるのだと感じています。 また、複数のチームがADRを日常的に利用するようになったことで、システム全体での設計判断を見通せるようissueに"ADR" labelを付与するなど、組織全体にこの文化が広まっているさなかです。
ドキュメンテーションが得意なチームにおいては参考になる余地が少なかったかもしれませんが、ドキュメンテーションよりも実装に軸足が寄りがちなチームにおいては、意思決定の記録方法の引き出しとして利用してもらえればうれしいです。
