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 参考資料