Resilire 開発チームのシード期から始める ADR 文化 | Resilire Tech Blog
アーキテクチャの意思決定を記録するプラクティス
サプライチェーンリスク管理クラウドサービスResilireに技術アドバイザーとして参画している @ahomu でございます。今日はリアーキテクチャの開発で師走を大々満喫中の皆さまに代わって、ADR (Architecture Decision Records) 文化と運用の実態をご紹介します。
ADR (Architecture Decision Record) とは？
ADRはその名のとおりアーキテクチャに関する意思決定の記録を残すためのドキュメントです。意思決定の内容や背景と経緯、根拠などが記されます。その場において認識の共有に役立つのはもちろん、あとから設計を見直したり議論したりするときにも意思決定の記録が役立ちます。
原典?として挙げられるのは Michael Nygard 氏のブログ記事でしょうか。日本国内でケーススタディが展開されるようになったのは近年の印象ですが、この記事の日付みると2011年であり実はそれなりに以前からあるプラクティスだったと言えます。私自身、不勉強で近年まで知らなかったのと、実際に運用されている光景はResilireが初見でした。
Architectural Decisionを踏まえたADRの周辺解説はインフィニットループさんの記事
ADR – アーキテクチャ上の設計判断を記録しよう で特に詳説されていましたのでこちらもご覧いただくと良いです。（おすすめ）
他社さまの ADR ケーススタディ
ちょうどAdvent Calendarの季節なのもあって、各社からも新しいケース紹介の記事が出ていました。他にもたくさんの記事があることを承知していますが、ここでは一部をご紹介させてください。
- スタディサプリさん
- 〜その意思決定を刻め〜「アーキテクチャ・デシジョン・レコード(ADR)」を利用した設計の記録
- ADRの名前が拡がったのは特にこの記事がきっかけではないでしょうか
- ZOZOさん
- バイセルさん
- ROUTE06さん
- チーム開発における技術選定の進め方
- ADRのチーム内運用はROUTE06さんの事例は特に参考にさせていただきました（とのこと）
- ニフティさん
- 一休さん
Resilie 開発チームの ADR 運用
Reslireではリポジトリルートから docs/adr の位置に下記のようなマークダウンドキュメント群が整備されています。既に結構な分量が蓄積しているので読み応えがあります。
内容はファイル名から感じ取ってください。
adr
├── README.md
├── backend
│ ├── 001-backend-go-framework.md
│ ├── 002-grpc-systemcontrol-handling.md
│ ├── 003-write-and-read-db-instances.md
│ ├── 004-grpc-design-spec.md
│ └── ...
├── development
│ ├── 001-adr-adoption.md
│ ├── 002-open-api-tag-rules.md
│ ├── 003-tools-for-editing-open-api-schema.md
│ ├── 004-release-flow.md
│ └── ...
├── frontend
│ ├── 001-generouted-adoption.md
│ ├── 002-react-query-adoption.md
│ ├── 003-react-router-dom-adoption.md
│ ├── 004-react-adoption.md
│ └── ...
├── spec
│ ├── 001-handling-timezone.md
│ ├── 002-uri-naming-conventions.md
│ ├── 003-unification-of-list-sorting.md
│ ├── 004-adopting-idaas.md
│ └── ...
└── template.md
development カテゴリーはリリースフローや、コードがマージされるまでの取り決め、spec カテゴリーは仕様上の取り決めなど、ソフトウェアのアーキテクチャに限らない様々なチームの意思決定が記録されています。ADRのスコープをどこまで拡げるかは先に紹介した各社の事例でもまちまちの印象ですが、Resilireではこのように運用しています。
記述フォーマット
本稿執筆時点では次のようなフォーマットがテンプレートファイルとして用意されています。基本的には Documenting architecture decisions - Michael Nygard に沿ったフォーマットですね。
# {TITLE}
## Status
<!-- Format
<Date> <Status: 承認 or 廃止>
-->
{DATE} <承認 or 廃止>
## Background
<!-- この決定に至っての経緯/課題を記述してください -->
## Decision
<!-- 決定事項を記述してください -->
<!-- 他の選択肢があった場合、採用しなかった理由を記述してください -->
## Impact
<!-- この決定をするにあたっての影響内容を記述してください -->
## Compliance
<!-- この決定を守れているか確認する方法を記述してください -->
Resilie 開発チームに根付いた ADR 文化
ResilireにおけるADRの原点を見つけるべくSlackの奥地で見つけてきたのが2023年3月頃のこちらの投稿です。
程なくして ADR の導入を意思決定する ADR がリポジトリにPull Requestされてマージされていました。後世のために、という狙いのとおりジョインしたメンバーがコントリビュートするための最初の手がかりとして当時のADRが役に立っています。
ADR を運用する強い意志が感じられる Slack
自然とADRを書くという習慣が見てとれます。
ADRの有用性を実感し、過去にさかのぼって適用されている様子も見つけました。
:adr: というemojiと共に新しいADRに対するわくわくが表明されています。
実際に書いたり読んだりした感想
わたしもResilireを見習って別の場所でADRに取り組んでいますが、アーキテクチャの検討段階で前提条件や選択肢の棚卸しをすること自体が思考の整理になるのでとても良い習慣だと感じました。
Resilireのコードベースを理解する上でも各種のADRに最初に目を通すことで全体像や方針を掴むことができて、コードリーディングがスムーズになりました。以前に新しくジョインされた方と話したときもADRのおかげでスムーズに開発に入れたというコメントもありましたし情報資産としてうまくワークしているようです。
あなたも Resilire で ADR を書きませんか
ということでソフトウェアエンジニア採用を絶賛強化中なので、興味を持った方は下記からぜひどうぞ！
Product & Technologyの紹介資料もどうぞ。
最後までお読みいただきありがとうございました。:)
Discussion