$30 off During Our Annual Pro Sale. View Details »

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

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

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

Takahiro Uchiyama

July 27, 2023
Tweet

More Decks by Takahiro Uchiyama

Other Decks in Programming

Transcript

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  31. 日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード
    ● 「タイトル/コンテキスト/内容/ステータス/影響...」といったADRの基礎的なテ
    ンプレートを紹介したが、そういったテンプレートを用いないスタイルも多かっ

    ● その場合、意思決定した事柄のみ(「内容」セクションにあたるもの)を記述し
    ている
    ● "形式的なドキュメント"に対比されるADRでの、最低限の"形式"すら活用しな
    い事例とも言える
    31
    使い方事例: テンプレートをあまり利用せずに書く

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    37
    意思決定者以外にも聞いてみた:
    Engineering Manager(EM)

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide