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

2023年7月27日「Developers Summit 2023 Summer」にて
「日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード」というタイトルで「ADR」について発表した資料です

Transcript

1. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 日々の意思決定の積み重ねを記録する アーキテクチャ・デシジョン・レコード 内山高広 @highwide 2023.07.27 Developers Summit 2023 Summer
2. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード Agenda | 00 01 02 03 04 About Me & Us アーキテクチャ・デシジョン・レコードとは スタディサプリとADRの出会い それからのスタディサプリとADR 運用を通して見えてきたもの 2
3. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード About Me & Us 00 3
4. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード こんにちは！ • 内山 高広 / @highwide • スタディサプリでプロダクト基盤のWeb開発を行っている • 前職でRails開発やエンジニアリングマネージャーを経験した後、現職では何 度かの異動を通してRails、React、node.js、GraphQL、Goなどの技術要素 を触っている • 休日はもっぱら3歳の子供と遊んでいる 4
5. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 今日話す「スタディサプリ」について 5 https://studysapuri.jp/
6. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 今日話す「スタディサプリ」について 6 スタディサプリブランドには ENGLISHのサービスもありま すが、今日は学生の方に主に 使っていただいているサービス について話します。 https://studysapuri.jp/
7. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード アーキテクチャ・デシジョン・レコードとは 01 7
8. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード アーキテクチャ・デシジョン・レコード(ADR) • "Architectural Decision Record" • 「テキストベースの軽量なテンプレートを使用して、アーキテクチャ上の設計 判断を記録する」ドキュメント形式のこと • "膨大な量のドキュメントになる傾向"がある形式的なドキュメンテーションに 対比されることも多い 8 参考「Design It!」(O'Reilly)
9. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード フォーマット例 ## タイトル ## コンテキスト ## 内容 ## ステータス (下書き/提案済み/承認済み/廃止/非推奨) ## 影響 9
10. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード example ## タイトル 新規システムのアーキテクチャには CQRSを採用する ## コンテキスト 新規システムの性能要件を鑑みて Bobからの提案によってチームで議論した。 ## 内容 新規システムのアーキテクチャには CQRSを採用する。Command側のデータストアはEvent Sourcingパ ターンを利用し、個々の Eventのスナップショットを形成する Viewを別途用意して、Query側のシステム はそれを参照する。 ## ステータス 承認済み ## 影響 現在のプロトタイプの実装はほぼ利用できないことが確定する。 10
11. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード Michael Nygard氏による紹介(2011) 11 https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
12. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード Technology Radarにて「Adopt」(採用) 12 https://www.thoughtworks.com/en-br/radar/techniques/lightweight-architecture-decision-records
13. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード CLIツールもある 13
14. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード CLIツールもある 14
15. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード スタディサプリとADRの出会い 02 15
16. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード スタディサプリとADRの出会い • 社内の「Design It!」(O'Reilly)の読書会で存在を知る • 読書会に参加していた複数名が従事するプロジェクトに て、活用できるのでは？との声が上がった 16
17. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 2年前に開発ブログに書いた記事 17 https://blog.studysapuri.jp/entry/architecture_decision_records
18. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 当時の課題 • Ruby on Railsで書かれたモノリスなシステムから1つの機能をGoによるマイ クロサービスに移行させていた • 「自分たちで決めたはずの設計判断が、開発中十分に振り返れるほどは記 録できていない」ことに気づく • 「結果的にどうしたか」を記録していたとしても、「なぜそうしたのか」は失われ がち ◦ ex: 「なんで物理削除でもなく、削除フラグでもなく、Archivedテーブル による削除」を実装したんだっけ？ 18
19. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ADRがもたらしたもの 19
20. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード プロジェクトを通しての意思決定が散逸しない • スタディサプリ特有の事情として、諸々のドキュメンテーションにGitHub issueを多用している • 「このプロジェクトが終わるまで、1つのissueのコメントに意思決定を書き連 ねていく」という点がよかった • 複数のページに情報が散らばっているという状態を避けられた 20
21. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 「何を記録すべきで何を記録しなくてよいか」が明確に • 「全てのMTGの全てのやりとりは議事録に残しましょう」も「網羅的な設計ド キュメントを書いてから実装に移りましょう」も現実に即していなかった • 「チームで意思決定をしたら、それを書きましょう」の明確さが記述のハード ルを下げた 21
22. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 意思決定をカジュアルに記録しようという文化の形成 • 「何を記録すべきか」という感覚がチームに養われたことで、それが文化と なっていった • ADRという概念が生まれ定着したことで、「それってADRに書いてありまし たっけ？」「じゃあ、これはADRに書くべきですね」というコミュニケーションが 自然となる • 「意思決定にhookして記録を残す」が習慣になることで、もちろん設計判断 は振り返りやすくなった 22
23. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード シンプルながらも、振り返りでは「革命」との言葉も 23
24. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ADR導入以後のスタディサプリ 03 24
25. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード スタディサプリを取り巻く状況 • ここ数年でマイクロサービス化が進む • CTOや組織全体のリードアーキテクトはおらず、チームが裁量を持って個々 のサービスについての意思決定を行うことが多い ◦ ex: 設計手法/ライブラリ選定/言語選定/ etc… 25
26. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード チームが裁量を持つからこそADRの使い方にも特色が • ADRの利用有無や細かい使い方にもチームごとの特色が見られた • 別の言い方をすれば、チームごとにカスタマイズの余地があるドキュメンテー ション手法と言えるかもしれない • 現場でのADRの使い方をいくつか紹介したい 26
27. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • 先のブログでは「1つのissueのコメントにADRを書き連ねていく」やりかたを 紹介したが、「1つのissueに1つの意思決定を書く」という使い方をとるチー ムもあった • その場合もissueに"ADR" labelを付与して、情報が散逸しにくい工夫はなさ れていた 27 使い方事例: 「1つのissueにまとめる」vs「1つのissueに1つのADR」
28. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード28 [例]「1つのissueにまとめる」
29. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード29 [例]「1つのissueに1つのADR」
30. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • 1つのissueに1つのADRとすると、当然個々の議論がissueの中でしやすく なるので、"承認済み"にまだ至っていないADRについての議論がやりやすく なるというメリットも見られた • 「ソフトウェアアーキテクチャの基礎」(O'Reilly)においては、"RFC"(Request For Comments)というステータスでのADR運用についても提案されており、 issueで議論しやすいことから、そういった取り組みもしやすいと言える 30 「1つのissueに1つのADR」のメリット
31. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • 「タイトル/コンテキスト/内容/ステータス/影響...」といったADRの基礎的なテ ンプレートを紹介したが、そういったテンプレートを用いないスタイルも多かっ た • その場合、意思決定した事柄のみ(「内容」セクションにあたるもの)を記述し ている • "形式的なドキュメント"に対比されるADRでの、最低限の"形式"すら活用しな い事例とも言える 31 使い方事例: テンプレートをあまり利用せずに書く
32. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード32 [例] 設計判断の内容についてのみ記すADR これで用が足りる場合も多いので、 「意思決定を記録する」ことのハード ルを下げるためには便利なやり方 かもしれない。
33. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • たとえば「チームの編成方針」「自動生成コードのPR reviewに関する決め 事」など、システムの"Architectural"な意思決定というよりは、組織について の意思決定や、チームの開発フローについての意思決定についての"ADR" も見られた • ADRというツールによって「チームで意思決定したら記録しよう」が内面化さ れたことで、"Decision Record"自体に価値があることが認められているとも 言える 33 使い方事例: 「"A"DR」にこだわらないことも
34. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード34 [例] "A"にこだわらない"ADR"
35. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • New Joinerに対して「このシステムを理解したいならば、ADRを読むといい よ」「このADRとこのADRは特に読んでみてください」という使い方 • 特に「なんでこの設計なんだろう」「どうしてこのSaaSをつかっているんだろ う」といった、New Joinerが感じがちな"Why"に応えられるドキュメントとして 有用 35 使い方事例: オンボーディングでの活用
36. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード アーキテクチャ上の意思決定を直接的に下す 開発者以外にもADRの活用について聞いてみた 36
37. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • メンバーの動向全てを追えないEMにとって、「ADR」という概念があることに よって、メンバーが開発するシステムの最低限の動向が追いやすくなった • また、自分が追いかけるために読むだけでなく「ADRの作成お願いします！」 というコミュニケーションもADRという概念を共有できているからこそできてい る 37 意思決定者以外にも聞いてみた: Engineering Manager(EM)
38. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • 発表のネタ的には、PdMからも「ADRがあって便利なんです！」という声が聞 けることをちょっと期待して聞いてみた ◦ 実際は「そんなに見てないです」「気にしてないです」という声が多数集 まった😂 • 開発者のアーキテクチャ上の意思決定は、外部から見た振る舞いを変更する ようなものではないことが多いと感じた • 結果としてスタディサプリにおいては「ADRは主に開発者のためのもの」という 側面が見えてきた 38 意思決定者以外にも聞いてみた: Product Manager(PdM)
39. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ADRは全てのドキュメントを代替したか (もちろんNo) 39
40. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード40 組織で定着しているドキュメント運用の例: ※ ADRではカバーしきれないもの • チームのWorking Agreement • サービスのDesign Doc / Production Readiness Checklist • 仕様を網羅するような重厚長大なドキュメント
41. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • 「チームでの働き方などの合意を記録をしておきましょう」という使い方がなさ れている • システムのアーキテクチャに関わらない意思決定がなされたときに書かれる ことが多い (⇔先程見たような"A"にこだわらないADRもある) 41 ADR以外の定着しているドキュメント例: チームのWorking Agreement 意思決定 ADR Working Agreement その決定は... 作成 更新 システムの アーキテクチャに関わる？ チームでの動き方に関わる？
42. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード42 [例] チームのWorking Agreement
43. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • 開発者がサービスをプロダクションにリリースするにあたっては以下の運用 がされている ◦ コードを書く前にDesign Docを書く ◦ リリースする前にProduction Readiness Checklistを埋める • Production Readiness Checkにあたっては、当然「個々の意思決定の記 録」ではなく、体系的に網羅された情報のチェックが必要 • SREからすると、運用にあたってあとからサービス特性を確認する際は、 ADRよりもこれらのドキュメントの方が有用であることも多い 43 ADR以外の定着しているドキュメント例: Design Doc / Production Readiness Checklist
44. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 初期検討 44 意思決定 Production Readiness Checklist 初期開発 意思決定 意思決定 意思決定 エンハンス開発 ADR ADR ADR ADR Design Doc Design Doc / Production Readiness Checklist
45. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード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
46. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • ADRのような軽量なドキュメントがあれば、重厚長大なドキュメントを一切書 かなくてよい...というわけではない😭 • たとえば、技術的チャレンジを伴うような設計/実装をした場合「明示的な意 思決定がなされないまま」結果論的にアーキテクチャができあがっていくこと もある • PdMやカスタマーサポートの方と協業する中で、いま時点での網羅的な仕様 を参照しないと業務がやりにくいときもある 46 ADR以外の定着しているドキュメント例: 仕様を網羅するような重厚長大なドキュメント
47. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード [例] 私が書いた"重厚長大"なドキュメント 47 社内で開発されるModular monolith基盤(社内呼称: "qmonolith")の使い方について執筆。 • ADR登場以前の意思決定が追いにくくなっていた • Modular monolithという当時慣れなかった設計に込め られた意図を明確にしないとコードを書きづらい といった背景から、重厚長大なドキュメントを書いた。
48. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード48 中学学習講座の「ミッション機能」が複雑化する中で、「開発 者がコードを追って仕様を確認する」運用に無理が生じてき て執筆。 明確な"意思決定"(=ADR)のみを追えば仕様がわかるような ものでもなかったので、現状のコードを読んで網羅的な仕様 を記述。 [例] 私が書いた"重厚長大"なドキュメント
49. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ADRを運用していての課題 49
50. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 課題: 「意思決定にhookして記録する」のだが、 なんだかんだ言って、書くのを忘れてしまう 50 こないだの"意思決定" なんだっけ？
51. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 対策案: 「承認済み」"以前"のステータスをうまく使う 51 「意思決定した」タイミングで記録を残す(post hook)だけでなく、 「これから意思決定する」タイミング(pre hook) でも、ADRをうまく活用できると、 記録を忘れるリスクは減りそう。
52. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 課題: 過去のADRを「廃止」扱いにするのは難しい 52 この何気なく行った意思決定が、過去の「意思決定 #1」を破棄することに繋がるものだった ...と気づくの は、実は難しい。 シンプルなテキストベースの記録だからこそ、「過去の ADRに関係しそう」という気づきは人間に委ねられが ち。 引き続き対応を検討したい。 ADR 意思決定 #1 意思決定 #1を更新する意思決定 意思決定 #2 意思決定 #1を破棄する意思決定
53. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 運用を通して見えてきたもの 04 53
54. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 「意思決定にhookして記録する」という文化の定着 54 今..."意思決定"したな...。 …じゃあ、"ADR"書かなきゃ！ 「ドキュメントを書く工程」を明確に置かないアジャイル な開発において、いまドキュメントを書かなくてはいけ ないという動機づけに
55. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • これまでのスタディサプリ開発において、形式的なドキュメントを書くことは強 く重視されてこなかったが、意思決定にhookして軽量な記録を残すADRは マッチした • 「ドキュメントを書く工程」を明示的に置かず、アジャイルな「意思決定」を繰り 返す多くの開発現場にADRはマッチするはず • スタディサプリの使い方が直接マッチせずとも、カスタマイズの余地がある懐 の広さと、軽量ゆえのスモールスタートのしやすさを感じる 55 「ADR」はどんな開発現場のためのものか
56. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 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
57. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード イベントソーシングによるアーキテクチャ同様 Viewにおいては工夫が必要な側面も 57 https://learn.microsoft.com/ja-jp/azure/architecture/patterns/event-sourcing
58. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード イベントソーシングによるアーキテクチャ同様 Viewにおいては工夫が必要な側面も 58 「意思決定」というイベントの積み重ねが記録され ている一方で、いま時点での有効な全体像を見 る"View"が必要になることも 形式的/ 網羅的 ドキュメント ADR 意思決定 #1 意思決定 #1を更新する意思決定 意思決定 #2 意思決定 #1を破棄する意思決定
59. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • スタディサプリでは導入以後、チームがその運用をカスタマイズさせながら、 開発者の意思決定の記録に欠かせないツールとして、ADRを活用してきた • 「意思決定にhookして軽量な記録を残す」という文化は、多くのアジャイルな 開発現場にマッチするはず • 一方で、ADRが全てのドキュメントを代替するわけではなく、あくまでも個々の 意思決定というEventのスナップショットでしかないことに留意する必要はある 59 ADRまとめ:
60. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード 「アーキテクチャ」とは"意思決定"という Eventが積み重なったもの。 意思決定の記録のハードルを下げるこ とは、アーキテクチャを作りあげること のハードルを下げることだと信じていま す。 60
61. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード ご清聴ありがとうございました 61
62. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード • ADR プロセス - AWS • アーキテクチャ決定レコードの概要 - Google Cloud • 実践ADR - kawasima • イベントソーシングパターン - Microsoft • npryce/adr-tools - GitHub • joelparkerhenderson/architecture-decision-record - GitHub • 「Design It!」(O'Reilly) • 「ソフトウェアアーキテクチャの基礎」 (O'Reilly) 62 参考資料