ADRはじめました - エス・エム・エスエンジニアテックブログ

こんにちは！夏ですね。@kimukei です。
今回は、弊プロジェクトのカイポケリニューアルで ADR を導入しましたというお話です。

ADRとは、「Architecture Decision Record」または、「Architectural Decision Records」の略でアーキテクチャ上で重要な決定を記録するドキュメントです。詳しくは「DOCUMENTING ARCHITECTURE DECISIONS」や「Architectural Decision Records」をご覧ください。

また ADR については、以前弊社の酒井が登壇したイベントでも触れられておりますので、こちらの記事もあわせて読んでみてください。 tech.bm-sms.co.jp

ADR を導入しましたってエントリは巷には溢れかえっているので、今回はちょっと趣向を変えて実際に私たちが運用している ADR の形式にそって「ADR を導入する」という意思決定に至った流れを書いてみようと思います。

以下に ADR の実例を示します。

ADR を導入する

ステータス

2024年5月14日 Proposed
2024年5月17日 Accepted

コンテキスト

カイポケリニューアルは、プロジェクトが発足して3年以上経過している。それゆえにすでにコンテキストは分厚いのだが、技術スタックの選定理由や当時の検討のログは散らばり、中には当時の在籍者に聞かないと詳細は不明なものがあり、疑問に思っても疑問が完全に消化しきれないことがある。また、今後新しい技術の採用を考慮する際に、過去の選定理由やトレードオフスライダーを参照できないために、新しい技術の善し悪しの判断が曖昧になる懸念がある。

今後近いうちに、カイポケリニューアルにおいて非同期処理やイベント駆動処理の技術選定が必要になってくることが考えられる。その際の技術選定の議論やコンテキストをまとめておく必要性を感じている。

これらの課題を解消するため ADR を導入することが有効である。また、過去の情報を集めて ADR として再生成することで必要に応じて過去の意思決定も記録しておける。

決定

ADR を導入する。 ADR の目的は、他のチームや新メンバーに技術的な決定の経緯を共有すること。つまり検討内容が完璧である必要はなく経緯を知ることで未検討な部分を後から追加検討したりできる。

アーキテクチャ上重要なものは、なるべく ADR を書く。構造、非機能特性、依存関係、インターフェイス、構築手法の5つの観点で意思決定するものはなるべく ADR に書き起こす。

もし書くべきかどうか迷ったり気になった場合は相談相手としてADR 運用チームを指定できるようにする。運用に慣れてきたらそれぞれのチームに相談やレビューなどを移譲する。

また、過去の意思決定について ADR があったほうがいいんじゃないかというものは GitHub Discussions ページを用意したので、そこにコメントして投票式で得票数の高いものから作っていく。

影響

新しいアーキテクチャや技術の導入の際には、議論の叩き台や決定したことの記録として ADR を書くようになることが想定される。アーキテクチャ上のコンテキストや遵守方法が ADR に集中される。これにより参照性が高まり、新しく Join したメンバーのオンボーディングなどにも利用できる。

遵守方法 (Compliance)

構造、非機能特性、依存関係、インターフェイス、構築手法の5つの観点で意思決定するものはなるべく ADR に書き起こす。新しいアーキテクチャや技術要素だったりを導入する際は ADR を書くことまでをなるべくタスクに含める。 ADR にはゆるめなテクニカルライティングのルールで textlint をかけているのでそのライティングスタイルに沿う。

備考

オリジナルの著者: @kimukei
承認日: 2024/05/17
承認者: ADR運用チーム、開発チーム
置き換え日: n/a
最終更新日: 2024/07/05

こんな感じです！参考にした ADR テンプレートは『ソフトウェアアーキテクチャの基礎 ―エンジニアリングに基づく体系的アプローチ』の第Ⅲ部 19.3 「アーキテクチャデシジョンレコード」や、joelparkerhenderson/architecture-decision-record などです。

管理場所は GitHub 上でモノレポ化¹したリポジトリで docs/adr/ を切ってそこで行っています。 Pull Request に discussion 履歴などが残ることや GitHub Actions があることによるCI/CDの自由度の高さ（フォーマットの遵守もそうだが、GitHub Pages に出力するなど）が便利ですし、最近だと AI の学習のためにこの手のドキュメントとコードをあまり離さないほうが良いかもしれません。ちょうど最近弊社は GitHub Enterprise 化したので GitHub Copilot Enterprise がこの辺のドキュメントを読んでレスポンスをくれるようになりました。

運用してみて

ADR のドラフトを叩き台にしてチームを跨いだ技術選定の議論が行われた

たとえば、最近 SRE チームと開発の1チームでバッチ処理基盤が欲しいので作ろうという話をしていたのですが、その中で議論の叩き台として ADR のドラフトが活用されていました。そして関係者が合意してドキュメントがまとまったら ADR の Pull Request を Ready for review にして ADR 運用チームからレビューをもらうという流れがとても自然でした。

過去の歴史を紡ぐ動きが出てきた

カイポケリニューアルでは、通信に GraphQL を採用しているのですが、当時在籍していたメンバーがその経緯や考えていたことを ADR に書いてきてくれたりしました。また、マイクロサービスアーキテクチャのトポロジーを組んでいる理由や、そもそものカイポケリニューアルに至った背景や決定が再言語化され ADR となりました。

大元の「なぜ」の部分がかなり明確になり、開発の意思決定もよりしやすくなったと感じます！

エンジニア以外の職種でもこのような決定を記録するやり方が広まった

ADR は「Architectural」な顔をしていますが、実際は Decision Record つまり決定の記録フォーマットとしても有用です。 PO や PdM でもProduct Decision Record(PDR) として、似たような決定事項やコンテキストを記録するフォーマットが使われるようになりました。

同じようなフォーマットが使われていると職種を横断してドキュメントを見にいく時も認知負荷を減らしてスッと入ってくるのでいいですね！