日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード / Architectural Decision Records

Slide 1

Slide 1 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード内山高広 @highwide 2023.07.27 Developers Summit 2023 Summer

Slide 2

Slide 2 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード Agenda | 00 01 02 03 04 About Me & Us アーキテクチャ・デシジョン・レコードとはスタディサプリとADRの出会いそれからのスタディサプリとADR 運用を通して見えてきたもの 2

Slide 3

Slide 3 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード About Me & Us 00 3

Slide 4

Slide 4 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードこんにちは！ ● 内山高広 / @highwide ● スタディサプリでプロダクト基盤のWeb開発を行っている ● 前職でRails開発やエンジニアリングマネージャーを経験した後、現職では何度かの異動を通してRails、React、node.js、GraphQL、Goなどの技術要素を触っている ● 休日はもっぱら3歳の子供と遊んでいる 4

Slide 5

Slide 5 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード今日話す「スタディサプリ」について 5 https://studysapuri.jp/

Slide 6

Slide 6 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード今日話す「スタディサプリ」について 6 スタディサプリブランドには ENGLISHのサービスもありますが、今日は学生の方に主に使っていただいているサービスについて話します。 https://studysapuri.jp/

Slide 7

Slide 7 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードアーキテクチャ・デシジョン・レコードとは 01 7

Slide 8

Slide 8 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードアーキテクチャ・デシジョン・レコード(ADR) ● "Architectural Decision Record" ● 「テキストベースの軽量なテンプレートを使用して、アーキテクチャ上の設計判断を記録する」ドキュメント形式のこと ● "膨大な量のドキュメントになる傾向"がある形式的なドキュメンテーションに対比されることも多い 8 参考「Design It!」(O'Reilly)

Slide 9

Slide 9 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードフォーマット例 ## タイトル ## コンテキスト ## 内容 ## ステータス (下書き/提案済み/承認済み/廃止/非推奨) ## 影響 9

Slide 10

Slide 10 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード example ## タイトル新規システムのアーキテクチャには CQRSを採用する ## コンテキスト新規システムの性能要件を鑑みて Bobからの提案によってチームで議論した。 ## 内容新規システムのアーキテクチャには CQRSを採用する。Command側のデータストアはEvent Sourcingパターンを利用し、個々の Eventのスナップショットを形成する Viewを別途用意して、Query側のシステムはそれを参照する。 ## ステータス承認済み ## 影響現在のプロトタイプの実装はほぼ利用できないことが確定する。 10

Slide 11

Slide 11 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード Michael Nygard氏による紹介(2011) 11 https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions

Slide 12

Slide 12 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード Technology Radarにて「Adopt」(採用) 12 https://www.thoughtworks.com/en-br/radar/techniques/lightweight-architecture-decision-records

Slide 13

Slide 13 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード CLIツールもある 13

Slide 14

Slide 14 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード CLIツールもある 14

Slide 15

Slide 15 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードスタディサプリとADRの出会い 02 15

Slide 16

Slide 16 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードスタディサプリとADRの出会い ● 社内の「Design It!」(O'Reilly)の読書会で存在を知る ● 読書会に参加していた複数名が従事するプロジェクトにて、活用できるのでは？との声が上がった 16

Slide 17

Slide 17 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 2年前に開発ブログに書いた記事 17 https://blog.studysapuri.jp/entry/architecture_decision_records

Slide 18

Slide 18 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード当時の課題 ● Ruby on Railsで書かれたモノリスなシステムから1つの機能をGoによるマイクロサービスに移行させていた ● 「自分たちで決めたはずの設計判断が、開発中十分に振り返れるほどは記録できていない」ことに気づく ● 「結果的にどうしたか」を記録していたとしても、「なぜそうしたのか」は失われがち ○ ex: 「なんで物理削除でもなく、削除フラグでもなく、Archivedテーブルによる削除」を実装したんだっけ？ 18

Slide 19

Slide 19 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ADRがもたらしたもの 19

Slide 20

Slide 20 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードプロジェクトを通しての意思決定が散逸しない ● スタディサプリ特有の事情として、諸々のドキュメンテーションにGitHub issueを多用している ● 「このプロジェクトが終わるまで、1つのissueのコメントに意思決定を書き連ねていく」という点がよかった ● 複数のページに情報が散らばっているという状態を避けられた 20

Slide 21

Slide 21 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード「何を記録すべきで何を記録しなくてよいか」が明確に ● 「全てのMTGの全てのやりとりは議事録に残しましょう」も「網羅的な設計ドキュメントを書いてから実装に移りましょう」も現実に即していなかった ● 「チームで意思決定をしたら、それを書きましょう」の明確さが記述のハードルを下げた 21

Slide 22

Slide 22 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード意思決定をカジュアルに記録しようという文化の形成 ● 「何を記録すべきか」という感覚がチームに養われたことで、それが文化となっていった ● ADRという概念が生まれ定着したことで、「それってADRに書いてありましたっけ？」「じゃあ、これはADRに書くべきですね」というコミュニケーションが自然となる ● 「意思決定にhookして記録を残す」が習慣になることで、もちろん設計判断は振り返りやすくなった 22

Slide 23

Slide 23 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードシンプルながらも、振り返りでは「革命」との言葉も 23

Slide 24

Slide 24 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ADR導入以後のスタディサプリ 03 24

Slide 25

Slide 25 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードスタディサプリを取り巻く状況 ● ここ数年でマイクロサービス化が進む ● CTOや組織全体のリードアーキテクトはおらず、チームが裁量を持って個々のサービスについての意思決定を行うことが多い ○ ex: 設計手法/ライブラリ選定/言語選定/ etc… 25

Slide 26

Slide 26 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードチームが裁量を持つからこそADRの使い方にも特色が ● ADRの利用有無や細かい使い方にもチームごとの特色が見られた ● 別の言い方をすれば、チームごとにカスタマイズの余地があるドキュメンテーション手法と言えるかもしれない ● 現場でのADRの使い方をいくつか紹介したい 26

Slide 27

Slide 27 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● 先のブログでは「1つのissueのコメントにADRを書き連ねていく」やりかたを紹介したが、「1つのissueに1つの意思決定を書く」という使い方をとるチームもあった ● その場合もissueに"ADR" labelを付与して、情報が散逸しにくい工夫はなされていた 27 使い方事例: 「1つのissueにまとめる」vs「1つのissueに1つのADR」

Slide 28

Slide 28 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード28 [例]「1つのissueにまとめる」

Slide 29

Slide 29 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード29 [例]「1つのissueに1つのADR」

Slide 30

Slide 30 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● 1つのissueに1つのADRとすると、当然個々の議論がissueの中でしやすくなるので、"承認済み"にまだ至っていないADRについての議論がやりやすくなるというメリットも見られた ● 「ソフトウェアアーキテクチャの基礎」(O'Reilly)においては、"RFC"(Request For Comments)というステータスでのADR運用についても提案されており、 issueで議論しやすいことから、そういった取り組みもしやすいと言える 30 「1つのissueに1つのADR」のメリット

Slide 31

Slide 31 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● 「タイトル/コンテキスト/内容/ステータス/影響...」といったADRの基礎的なテンプレートを紹介したが、そういったテンプレートを用いないスタイルも多かった ● その場合、意思決定した事柄のみ(「内容」セクションにあたるもの)を記述している ● "形式的なドキュメント"に対比されるADRでの、最低限の"形式"すら活用しない事例とも言える 31 使い方事例: テンプレートをあまり利用せずに書く

Slide 32

Slide 32 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード32 [例] 設計判断の内容についてのみ記すADR これで用が足りる場合も多いので、「意思決定を記録する」ことのハードルを下げるためには便利なやり方かもしれない。

Slide 33

Slide 33 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● たとえば「チームの編成方針」「自動生成コードのPR reviewに関する決め事」など、システムの"Architectural"な意思決定というよりは、組織についての意思決定や、チームの開発フローについての意思決定についての"ADR" も見られた ● ADRというツールによって「チームで意思決定したら記録しよう」が内面化されたことで、"Decision Record"自体に価値があることが認められているとも言える 33 使い方事例: 「"A"DR」にこだわらないことも

Slide 34

Slide 34 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード34 [例] "A"にこだわらない"ADR"

Slide 35

Slide 35 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● New Joinerに対して「このシステムを理解したいならば、ADRを読むといいよ」「このADRとこのADRは特に読んでみてください」という使い方 ● 特に「なんでこの設計なんだろう」「どうしてこのSaaSをつかっているんだろう」といった、New Joinerが感じがちな"Why"に応えられるドキュメントとして有用 35 使い方事例: オンボーディングでの活用

Slide 36

Slide 36 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードアーキテクチャ上の意思決定を直接的に下す開発者以外にもADRの活用について聞いてみた 36

Slide 37

Slide 37 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● メンバーの動向全てを追えないEMにとって、「ADR」という概念があることによって、メンバーが開発するシステムの最低限の動向が追いやすくなった ● また、自分が追いかけるために読むだけでなく「ADRの作成お願いします！」というコミュニケーションもADRという概念を共有できているからこそできている 37 意思決定者以外にも聞いてみた: Engineering Manager(EM)

Slide 38

Slide 38 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● 発表のネタ的には、PdMからも「ADRがあって便利なんです！」という声が聞けることをちょっと期待して聞いてみた ○ 実際は「そんなに見てないです」「気にしてないです」という声が多数集まった😂 ● 開発者のアーキテクチャ上の意思決定は、外部から見た振る舞いを変更するようなものではないことが多いと感じた ● 結果としてスタディサプリにおいては「ADRは主に開発者のためのもの」という側面が見えてきた 38 意思決定者以外にも聞いてみた: Product Manager(PdM)

Slide 39

Slide 39 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ADRは全てのドキュメントを代替したか (もちろんNo) 39

Slide 40

Slide 40 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード40 組織で定着しているドキュメント運用の例: ※ ADRではカバーしきれないもの ● チームのWorking Agreement ● サービスのDesign Doc / Production Readiness Checklist ● 仕様を網羅するような重厚長大なドキュメント

Slide 41

Slide 41 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● 「チームでの働き方などの合意を記録をしておきましょう」という使い方がなされている ● システムのアーキテクチャに関わらない意思決定がなされたときに書かれることが多い (⇔先程見たような"A"にこだわらないADRもある) 41 ADR以外の定着しているドキュメント例: チームのWorking Agreement 意思決定 ADR Working Agreement その決定は... 作成更新システムのアーキテクチャに関わる？チームでの動き方に関わる？

Slide 42

Slide 42 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード42 [例] チームのWorking Agreement

Slide 43

Slide 43 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● 開発者がサービスをプロダクションにリリースするにあたっては以下の運用がされている ○ コードを書く前にDesign Docを書く ○ リリースする前にProduction Readiness Checklistを埋める ● Production Readiness Checkにあたっては、当然「個々の意思決定の記録」ではなく、体系的に網羅された情報のチェックが必要 ● SREからすると、運用にあたってあとからサービス特性を確認する際は、 ADRよりもこれらのドキュメントの方が有用であることも多い 43 ADR以外の定着しているドキュメント例: Design Doc / Production Readiness Checklist

Slide 44

Slide 44 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード初期検討 44 意思決定 Production Readiness Checklist 初期開発意思決定意思決定意思決定エンハンス開発 ADR ADR ADR ADR Design Doc Design Doc / Production Readiness Checklist

Slide 45

Slide 45 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード45 参考: Design Doc / Production Readiness Checklist https://blog.studysapuri.jp/entry/2020/01/30/production-rea diness-with-all https://blog.studysapuri.jp/entry/2019/06/07/080000

Slide 46

Slide 46 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● ADRのような軽量なドキュメントがあれば、重厚長大なドキュメントを一切書かなくてよい...というわけではない😭 ● たとえば、技術的チャレンジを伴うような設計/実装をした場合「明示的な意思決定がなされないまま」結果論的にアーキテクチャができあがっていくこともある ● PdMやカスタマーサポートの方と協業する中で、いま時点での網羅的な仕様を参照しないと業務がやりにくいときもある 46 ADR以外の定着しているドキュメント例: 仕様を網羅するような重厚長大なドキュメント

Slide 47

Slide 47 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード [例] 私が書いた"重厚長大"なドキュメント 47 社内で開発されるModular monolith基盤(社内呼称: "qmonolith")の使い方について執筆。 ● ADR登場以前の意思決定が追いにくくなっていた ● Modular monolithという当時慣れなかった設計に込められた意図を明確にしないとコードを書きづらいといった背景から、重厚長大なドキュメントを書いた。

Slide 48

Slide 48 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード48 中学学習講座の「ミッション機能」が複雑化する中で、「開発者がコードを追って仕様を確認する」運用に無理が生じてきて執筆。明確な"意思決定"(=ADR)のみを追えば仕様がわかるようなものでもなかったので、現状のコードを読んで網羅的な仕様を記述。 [例] 私が書いた"重厚長大"なドキュメント

Slide 49

Slide 49 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ADRを運用していての課題 49

Slide 50

Slide 50 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード課題: 「意思決定にhookして記録する」のだが、なんだかんだ言って、書くのを忘れてしまう 50 こないだの"意思決定" なんだっけ？

Slide 51

Slide 51 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード対策案: 「承認済み」"以前"のステータスをうまく使う 51 「意思決定した」タイミングで記録を残す(post hook)だけでなく、「これから意思決定する」タイミング(pre hook) でも、ADRをうまく活用できると、記録を忘れるリスクは減りそう。

Slide 52

Slide 52 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード課題: 過去のADRを「廃止」扱いにするのは難しい 52 この何気なく行った意思決定が、過去の「意思決定 #1」を破棄することに繋がるものだった ...と気づくのは、実は難しい。シンプルなテキストベースの記録だからこそ、「過去の ADRに関係しそう」という気づきは人間に委ねられがち。引き続き対応を検討したい。 ADR 意思決定 #1 意思決定 #1を更新する意思決定意思決定 #2 意思決定 #1を破棄する意思決定

Slide 53

Slide 53 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード運用を通して見えてきたもの 04 53

Slide 54

Slide 54 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード「意思決定にhookして記録する」という文化の定着 54 今..."意思決定"したな...。 …じゃあ、"ADR"書かなきゃ！「ドキュメントを書く工程」を明確に置かないアジャイルな開発において、いまドキュメントを書かなくてはいけないという動機づけに

Slide 55

Slide 55 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● これまでのスタディサプリ開発において、形式的なドキュメントを書くことは強く重視されてこなかったが、意思決定にhookして軽量な記録を残すADRはマッチした ● 「ドキュメントを書く工程」を明示的に置かず、アジャイルな「意思決定」を繰り返す多くの開発現場にADRはマッチするはず ● スタディサプリの使い方が直接マッチせずとも、カスタマイズの余地がある懐の広さと、軽量ゆえのスモールスタートのしやすさを感じる 55 「ADR」はどんな開発現場のためのものか

Slide 56

Slide 56 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ADRとはある種の"イベントソーシング" 56 意思決定 Event TABLE Create 意思決定#1 Update 意思決定#1 Create 意思決定#2 Delete 意思決定#1 意思決定 TABLE 意思決定 #1 意思決定 #2 ステートソーシングなデータ「データの現在の状態だけを格納する代わりに、追加専用ストアを使用して、そのデータに対して実行された一連のすべてのアクションを記録」するパターン https://learn.microsoft.com/ja-jp/azure/architecture/patterns/event-sourcing イベントソーシングなデータ Create Update Delete

Slide 57

Slide 57 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードイベントソーシングによるアーキテクチャ同様 Viewにおいては工夫が必要な側面も 57 https://learn.microsoft.com/ja-jp/azure/architecture/patterns/event-sourcing

Slide 58

Slide 58 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードイベントソーシングによるアーキテクチャ同様 Viewにおいては工夫が必要な側面も 58 「意思決定」というイベントの積み重ねが記録されている一方で、いま時点での有効な全体像を見る"View"が必要になることも形式的/ 網羅的ドキュメント ADR 意思決定 #1 意思決定 #1を更新する意思決定意思決定 #2 意思決定 #1を破棄する意思決定

Slide 59

Slide 59 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● スタディサプリでは導入以後、チームがその運用をカスタマイズさせながら、開発者の意思決定の記録に欠かせないツールとして、ADRを活用してきた ● 「意思決定にhookして軽量な記録を残す」という文化は、多くのアジャイルな開発現場にマッチするはず ● 一方で、ADRが全てのドキュメントを代替するわけではなく、あくまでも個々の意思決定というEventのスナップショットでしかないことに留意する必要はある 59 ADRまとめ:

Slide 60

Slide 60 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード「アーキテクチャ」とは"意思決定"という Eventが積み重なったもの。意思決定の記録のハードルを下げることは、アーキテクチャを作りあげることのハードルを下げることだと信じています。 60

Slide 61

Slide 61 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコードご清聴ありがとうございました 61

Slide 62

Slide 62 text

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ● ADR プロセス - AWS ● アーキテクチャ決定レコードの概要 - Google Cloud ● 実践ADR - kawasima ● イベントソーシングパターン - Microsoft ● npryce/adr-tools - GitHub ● joelparkerhenderson/architecture-decision-record - GitHub ● 「Design It!」(O'Reilly) ● 「ソフトウェアアーキテクチャの基礎」 (O'Reilly) 62 参考資料