2021/06/30

ADRはじめました

菅野幸助

こんにちは、クラッソーネでエンジニアをしている菅野です。
ここ数日Kindleにて『鬼滅の刃』を一気読みしたので、これで世間の話題にもなんとかついていける気がしてます(遅)

私はここ数ヶ月ほど新規プロダクトの開発に関わっているのですが、
まっさらな開発プロジェクトということもあり、概ねゼロベースの技術選定を行なっていました。

その過程で ADR という手法を用いて技術的な意思決定に関するドキュメントを残す取り組みを行なってきたので、本エントリでは弊社での事例を紹介できればと思います。

ADR is 何？

Architectural Decision Records の略で、アーキテクチャ上の意思決定についてその背景や・経緯も含めて書き記して言語化しておこうというドキュメントとその手法を指します。

現時点でADR自体には明確にこれという形式・フォーマットが規定されているわけではないようですが、中でも Lightweight Architecture Decision Records というタイプが過去にTechnology Raderで Adopted になっていて、一定の権威付けがされているようです。

Lightweight Architecture Decision Recordsについて

以下の5つの項目で構成される軽量なADRフォーマットで、わたしたちのチームでもこちらを採用しています。

title (タイトル)
status (ステータス)
context (コンテクスト)
decision (決定)
consequences (結果)

参考

弊プロジェクトでの事例

さて、ここからは実際に試してみた経過を事例としてお伝えしていきたいと思います。

位置付けとその狙い

まず、当社におけるADRの運用ですが、「アーキテクチャ上の」要素に限らず、プロジェクトに関わるあらゆる技術的な意思決定や利用ツールの選定を対象としました。
そのためリポジトリ内ではなく、全社で管理しているドキュメント管理サービスにADRを配置することにしています。この点は原義からすると多少離れたものになっているかもしれません。

また発足当初は2~3名の規模ではじまったチームでしたが、新規プロダクトということで 大きな機能要件も不明瞭で、かつ短期的にも人員の入れ替わりや増減が予想されたため 、以下のことを主な狙いとして取り組むことにしました。

精緻な内容を目指さす、とにかくカジュアルにドキュメントを残していく
- ただしコンテクストを極力ダンプしていくことは大切
あとからチーム全体でふりかえりを行うことで、情報共有と今後の改善に活かす
- 後述しますがこの点はかなり重要だったと思います

運用

以上のことを念頭に折に触れてLightweight ADRの形式でドキュメントを残していました。

特に執筆の基準や固定化した運用ルールは定めずにカジュアルな運用を目指しました。
コードレビューの中でレビュアーが指摘事項として執筆を依頼することもあれば、書いたADRに対してコンテクストを詳細にしてくれといったプチレビューが入ることもあった気がします。

その結果「rubocopでの accepts_nested_attributes_for の利用是非」といった細かいものから「デザインツールの選定」に至るまで、大小様々なエントリが作られていきました。

Jobアダプタを選定した際のエントリ例

Jobアダプタを選定した例

ふりかえりの実施

さて、チーム発足から3~4ヶ月程度が経過して、プロジェクトもマイルストーンとなるタイミングを迎えました。
そこでこれまで書き溜めていたADRの数々について、チーム全体で集まって同期的なふりかえりを実施しました。

先述の通りLADRには「結果」の項目があり、その意思決定がチームやプロダクトに何をもたらしたのかをみんなで話し合って「良かった点」「課題点」を思い思いに記載していきます。

案の定チームの顔ぶれも発足当初から大きく変わっていたため、当時の背景を振り返りつつ、その中で「チームとしての思考/判断」に言及しながらひとつひとつ良し悪しをディスカッションしていきます。
この作業は非常に楽しくもあり、また情報共有・文脈共有の観点からも有益でもあったと感じています。

ただし「結果」と言いながら、実際のところその内容も 特定時点でのスナップショットでしかない ので、「ログ欠損」を抑制するため今後も必要に応じて継続的なふりかえりを行っていく必要性はありそうです。

まとめ

以上みてきた通り、このエントリではADRという手法を新規開発プロジェクトで小さく導入してきた事例を紹介してきました。
その中で個人的に感じた利点と反省点を最後に記しておきたいと思います。

利点

乱暴に言ってしまえば意思決定というイベントの ただのログ であるため、一度書いてしまえば完全にメンテナンスフリーであること
- マニュアルや仕様書など、一定のメンテナンスコストを要するものに比べるとこの利点は大きいと感じます
LADRに関して、導入・定着のハードルがかなり低い
- 簡素ながらもツボを押さえた形式のため、日ごろからドキュメントを書く習慣のあるチームであればすぐに定着できるのではないかと思います
途中参入のメンバーにもチームやプロダクトの連続的な背景を共有しやすいこと
- 通常の技術ドキュメントが現時点での「What」や「How」を記述するものだとしたら、過去のコンテクストや「Why」を可視化するドキュメント群はそれらを補完するものとして非常に有力だと感じます

反省点

フォーマットを間違えて運用していた
- status の項を完全に無視して運用してしまっていました。 これは恥ずかしい。
- とはいえカジュアル運用という意味ではさほど難を感じなかった(ゆえに発見が遅れた側面も...)
ふりかえり時期はあらかじめ個別に想定しておけるとよかったかもしれない
- どれくらいで結果が見えてきそうかは個別の決定内容によって異なるはずなので、大枠のふりかえりの時期も起票時点で決めておけるとより良く運用できそうだと感じています
より詳細なコンテクストが書けるとよさそう
- ドキュメントの性質上、 この情報が弱いと決定内容の評価が片手落ちになってしまうケースもあるため 、ここは唯一シビアにみるべき内容なのだという印象を持っています