この記事はSEN Product Blog アドベントカレンダー 2024 の5 日目の記事です。

こんにちは！

千株式会社でエンジニアをしている、 daitasuです。

本日は、私のチームで継続的に行っているArchitecture Decision Record (ADR) の仕組みについてお話します。

Architecture Decision Record (ADR)とは

Architecture Decision Record (ADR)とは、ソフトウェアやシステムの設計における意思決定を文書化して残していく手法です。

プロジェクトのアーキテクチャに関する

重要な意思決定やその背景
なぜその選択を取ったかの理由
代替手段(トレードオフ)は何を検討したのか

といったことを記録します。

なぜADRが必要なのか

スタートアップやプロダクトのグロースフェーズ期だと、

半年もあれば全然組織が違うものに変わっていたり、

人の入れ替わりが発生したり、

プロダクトやシステムも大きく方向性がシフトすることも多々あります。

そうしたスピード感のある意思決定のサイクルを進んでいると、

既存システムに触るときに、なぜこうなっているのか を知る人が既に社内に誰もいない
「あれ？これって何でこうしたんだっけ？」と決めたことの背景が忘れてしまう
十分に検討済みでそうなったのか、ひとまずそうしたのか、当時の事情が分からない

といったことも往々にしてあります。

弊社もご多分に漏れず、こうした課題によく直面します。

弊社の主幹事業である「はいチーズ！フォト」というシステムは、 20年ほどの歴史を持つプロダクト です。

しかし、プロダクトとして様々な方向へと変革を進めていたり、

開発組織としても急激にここ数年でスケールしている最中にあります。

そのため、

既存コードの歴史
プロダクト仕様のイレギュラーパターン
社内の特殊運用

といった中々検出が難しいものを探していくことがよくあります。

そうしたときに手助けとなるのが、ドキュメントです。

私自身も今年の4月に入社したのですが、Github 上のPRが丁寧に書かれていたり、Wiki を読んで助けられたことが多くありました。

しかし、各種のドキュメントや仕様書は 線でなく点 で 決まったこと が記載されていることが多く、

なぜそうなったのか
他に何を検討したのか

までは明記されていないことが多いです。

議事録で探し出せるものもありますが、20 年のプロダクトとなると、

探したい フロー情報 を見つけ出す難易度が高く、口頭ベースで決まる物事もあるため、探した結果見つからないということもあります。

ADR は、こうしたプロダクト開発における技術アーキテクチャの意思決定を一定のフォーマットで記録に残すことで、 後の人達 を救うためのドキュメントです。

ADR 文化の変遷

導入期

最初は、弊社の CTO である ytakeさんが「ADR書いていきましょう！」という Doc を展開いただき、そこから各チームでのアーキテクチャの意思決定を特定のフォーマットに沿って記載していきました。

チームが安定していく中で出てきた変化

私たちのチームはリプレイス系の案件を進めているチームで、今年の 5月頃にチームが新設しました。

レガシーシステムのリプレイスが足元の課題だったので、0からの技術選定やアーキテクチャ設計が多く、ADR を書く機会も多くありました。

しかし、こうしたシステム全体の設計に関するものはDocument に残して証跡を残す一方、

チームやPJTが軌道に乗ってくると、このような 大きな意思決定 の機会は減り、どちらかというと毎日のデイリースクラムで出てくるような 相談・共有事項 が増えていき、

小さな意思決定 をすることが増えていきました。

大きな意思決定と小さな意思決定

大きい・小さいは言葉のあやですが、下記のように棲み分けています。

小さな意思決定
- チーム内で完結するような意思決定
- 日々の中で軌道修正が可能な意思決定
大きな意思決定
- 他チーム、他部署を巻き込む必要がある意思決定
- 一度決定すると、変更が困難になる意思決定

課題感

プロダクトの技術選定やPJTにおける特殊仕様のためのアーキテクチャなど、何度か議論が必要なものは Doc に描いて議論して、ADR に過程を残す。

という文化はある程度根付いていました。

一方で、チームの朝会で話題に上がる相談・共有事項は、議論としてはまとまりやすいものが多いのですが、 決まったこと が 朝会の場所(Slack) に残す形となっていたため、過去を遡りにくい形となっていました。

どんな小さな判断も、ADR を書いてトレードオフの精査や思考の過程を残したい
Slack 上でのコミュニケーション上などで決まったものも、 何を議論 して、何が決まったかを未来の人にとって分かりやすくしたい
しかし、相談の敷居が上がることで相談しにくい文化にはしたくない

大きなADRと小さなADRに分けた

私達のチームのプロダクトは、 monorepo 構成で開発をしており、普段の開発は基本的に 1 リポジトリの中にまとまっています。

業務のタスクも Github Project 上で管理を行っており、ここに寄せてしまうのが一番楽に書けるだろうということで、 Github Discussion を使うことにしました。

全社に向けたADR ほどしっかりとしたトレードオフを精査したり、図示化を求めたりということはせず、

あくまでも チームに相談したい という粒度でカジュアルにDoc を書く。

ということを方針にこの形式を取りました。

Discussion の形式はFAQにする
朝会の相談で決定したことを Answer として Mark し、Close する
- もし議論の復活があれば、Unmark してReopen する
議論過程はコメントで追記していく
Discussion の Create と Mark Answered はSlack に通知される
Discussion から派生したタスクは、「Create issue from discussion」よりIssue 化する

このようにすることで、チームの朝会やSlack上で出てきた議論も大きな ADR 同様にドキュメントとして残りやすくなり、後から入るメンバーにとっても経緯を追いやすい形をつくることが出来ました。

振り返り

良かったこと

朝会やSlack上で発生した議論が１つの場所にまとまり、ADRとして 小さな意思決定 も残りやすくなった
技術的意思決定だけでなく、朝会に参加する PdM や Designer の方にもDiscussion に書いて議論する、という流れができて分かりやすくなった
- 「ADR」だけでなく、「プロダクト仕様」「チーム改善」という項目を設けて、事業側と議論する前のチーム内のプロダクト仕様のこまごまとした議論が残るようになった
意思決定が朝会に集約することが多かったが、事前にDiscussions の中で議論ができるようになった

改善したいこと

Github Discussions は、Createと Mark 以外はデフォルトのSlack の /github subscribe では購読できません
- 今のところコメントのフィードがなくても困っていませんが、必要になった場合はそれ用にAction等を用意する必要があります
Discussions に書く文化はできたが、朝会で意思決定するという流れがあり、いつでもDiscussions で会話して決定できるようにしたい
- 朝会は決まったことの確認のみの場にするなどできると、もっとスピード感のある意思決定をしていけそう
Discussion が増えた際の検索性
- 多くなった際の検索性など意識して、Section分けなども検討が必要
小さなADRから大きなADRへの昇華
- 小さなADRを書くことで書きやすさとDoc を書く習慣は生み出しやすいですが、物によっては「これは大きなADRだ」となるときもあります
- 全社的に社内のDoc ツールは過渡期にあり、複数のDoc管理ツールがあったり、閲覧可能範囲がバラバラだったりするので、「大きなADR」をどこに置くべきかなどもまだまだ議論の余地があります