Resilire 開発チームのシード期から始める Architecture Decision Record (ADR) 文化
Resilire Tech Blog は zenn に移行しました
私たちのテックブログをご覧いただきありがとうございます! 2024年から掲載先を zenn に移行しました。是非フォローして最新記事をご覧ください。
これからも 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 の紹介資料もどうぞ。
最後までお読みいただきありがとうございました。:)