ADRを運用して3年経った僕らの現在地

Transcript

1. ADRを運用して3年経った 僕らの現在地 id:onk 2024-10-05 YAPC::Hakodate 2024 1

2. 自己紹介 • 大仲 能史 a.k.a. id:onk • 芸歴20年目 • 株式会社はてな

   ◦ チーフエンジニア ◦ 好きなPerlプロダクトは箱庭諸島 ◦ 京都から陸路で来ました 2

3. 3 ADRとは

4. ADRとは • Architecture Decision Records ◦ アーキテクチャ上の設計判断を記録する ◦ 意思決定を記録、共有する手法 •

   2017年ぐらいから流行り始めた • Design It!やソフトウェアアーキテ クチャの基礎に詳しく書いてある 4

5. ADRとは • アーキテクチャが何故そうなっているかは 記録に残りづらい ◦ コンテキストはコード上に残らない • 最初は口伝で伝わるが、記憶が薄れたり 人が入れ替わったりして、いつか形骸化する ◦

   徐々に色褪せていき、意図不明なルールだけが残る 5

6. ADRとは • ADRと既存のアーキテクチャ文書との違い ◦ 継続的に書き残していくことに重きを置いている ◦ 決定事項だけではなく、コンテキストも書かれる ◦ "軽量"で、カジュアルに書きやすい •

   Design Docには設計の詳細も書く ◦ 意思決定に関わる内容だけを書くのがADR 6

7. 7 はてなのプロダクト

8. はてなのプロダクト • 2001年7月設立 • 15年物のプロダクトも現役 ◦ 2001 人力検索はてな ◦ 2005

   はてなフォトライフ、はてなブックマーク ◦ 2006 はてな匿名ダイアリー ◦ 2007 はてなスター 8

9. はてなのプロダクト • 15年前は完全に他人 ◦ 生き字引たちも記憶が無い • すべてがテキストで残ってはいる ◦ 社内グループウェア最高！ •

   ただし検索が上手くないとたどり着けない ◦ グループウェアのログ、IRCのログ、Slackのログ、 GitHub Issue/PR、コミットメッセージ、…… 9

10. 10 考古学が必要になる

11. 11 何故こうしたのかが 分かりやすく一覧に 残っていれば……

12. 12 今、開発している 新しいプロダクトも 経緯を追いやすくしたい

13. 13 ADRがドンピシャっぽい

14. 14 ADRの始め方

15. ADRの始め方 • 導入は難しくない ◦ なんせ"軽量"なドキュメント ◦ テキストの保存場所さえあれば始められる • テンプレートもいっぱいある ◦

    https://github.com/joelparkerhenderson/archit ecture-decision-record 15

16. ADRの始め方 • 導入は難しくない ◦ なんせ"軽量"なドキュメント ◦ テキストの保存場所さえあれば始められる • テンプレートもいっぱいある ◦

    https://github.com/joelparkerhenderson/archit ecture-decision-record 16

17. ADRを保存する場所 • Helpfeel Cosense • GitHub Repo (ソースコードと同じ場所) に置 いたこともあるが、すぐにCosenseになった

    • 「書きやすさ」「会話しやすさ」を大事にす るとGitHubは不向きだった 17

18. ADRをいつ書くのか • 実装内容が自明でないとき • 「設計したぞ」と思うことをしたとき • 迷ったら書きましょう 18

19. ADRのテンプレート • 作成日・作成者 • ステータス • 問題 • コンテキスト 19

    • 決定 • 影響 • 代替案 • 感想コーナー

20. ADRのテンプレート • ステータス ◦ proposed, accepted, rejected, … • 問題

    ◦ 問題は何なのか。それはなぜ問題なのか • コンテキスト ◦ 問題が発生する背景は何なのか 20

21. ADRのテンプレート • 決定 ◦ 問題を解決するために導入するもの。その根拠 • 影響 ◦ この決定による影響やトレードオフ。影響にどう対応 するか

    21

22. 22 書き始めたら数年で 全チームに波及した

23. 23 起きた出来事を 8個ほど紹介

24. 24 GitHubが使われない

25. GitHubが使われない • 下書きをCosenseで、レビューをGitHubで ◦ 下書きの段階で軽く揉む ◦ ある程度書けたらGitHubに持って行き、 「提案済み」ステータスにする ◦ GitHubで改めてレビューし、採択か破棄を決定する

    • GitHubに持って行ったのは最初の2件だけ 25

26. GitHubが使われない • 教訓：ワークフローよりも対話 • 対話したいからADRにしている ◦ 自信が無い ◦ チームの決め事にしたい •

    対話するなら、いつもの場所 ◦ いつもの定例、いつもの議事録のそば 26

27. 27 RFC文化の発達

28. RFC文化の発達 • Requests for Comments • 是非を問う前に有識者のコメントが欲しい ◦ 叩き台の選択肢からガラッと変わることも 28

29. RFC文化の発達 • テンプレートに議論コーナーができた ◦ インラインや感想コーナーで議論した後、ストック 情報として清書し、後から見返せるドキュメントに • ステータスにRFCが増えた ◦ draft

    -> rfc -> proposed -> accepted/rejected 29

30. 30 レビューに時間がかかる

31. レビューに時間がかかる • やりたいことがあるから提案しているのに、 理想の速度で決定されない • RFCの裏返し ◦ いつまでコメント募集なのか ◦ Proposeしたものはいつどこで決定されるのか

    31

32. レビューに時間がかかる • ステータスに期日を設けた ◦ RFC 〜2024-10-01 ◦ proposed 〜2024-10-05 ◦

    accepted/rejected 2024-10-05 • proposedになったらApproverに責任が移る ◦ 責任を持って期日までにaccept or reject 32

33. レビューに時間がかかる • ADRのレビュータスクをスクラムに乗せた ◦ 普段のタスク管理と同じところに置いて、 常に視界に入るように 33

34. 34 書きすぎる

35. 書きすぎる • 選択肢を丁寧に書きすぎる ◦ 認識が揃っているところは省略されている方が良い ◦ レビューで構えなきゃいけない度合いが誤って伝わる • 選ぶ理由はだいたい分かる ◦

    選ばない理由の方が理由があることが多い ◦ 後世ではコンテキストが薄すぎるので「もっと書け」 になるかもしれないが…… 35

36. 書きすぎる • 防衛的になる必要はない ◦ ADRは意思決定を推進するために書くもの 36

37. 書きすぎる • 何が決定的な要因になるかの想定を持つ ◦ 提案が受け入れられる条件は何なのか • 主な判断材料以外の要素は軽く書く ◦ すべての差分を明らかにする必要はない 37

38. 38 書けない

39. 書けない • やりたい、と言ってきたことに対して「ADR をください」を返した後に起きやすい • どこが議論ポイントになるのかの想定を持て てなく、何を書いたら良いか分からない • 壁打ちやペアライティングが必要 39

40. 40 Approverが大変

41. Approverが大変 • 全方位の知識を要求される ◦ 難しい内容だったり、知らない内容だったり ◦ 自分を判断できる状態に持って行くのに数時間〜数日 かかることも 41

42. Approverが大変 • 強いテクノロジーマネジメントが必要 ◦ 提案されたら意思決定を下さなければならない ◦ この情報が足りない、を明確に打ち返す必要がある • 現場でレビューが回るなら大丈夫 ◦

    技術領域 (c.f. Webフロントエンド) ごとに委譲する ◦ できていないならApproverが頑張ることになる 42

43. 43 下書きで止まる

44. 下書きで止まる • 書き始めたはいいが、完成させられなかった ADRたち • proposedになっていないので accepted/rejectedに到達しない 44

45. 下書きで止まる • 下書きで共有されるのは素晴らしいこと ◦ 隠し持っておくより全然いい ◦ 何度か書きかけると、徐々に気運が高まっていく ◦ 問題の形が徐々に削り出されていく •

    Issueと同じく、仕掛品が溜まり続ける ◦ staleなADRは積極的にcloseしていくとヨサソウ 45

46. 46 ADRが使われなくなる

47. ADRが使われなくなる • 異動や退職で、ADRを出す人、ADRにしてね と言う人がいなくなる • 数ヶ月動かないと、ADRというテンプレート が存在していたことが意識に上らなくなる 47

48. ADRが使われなくなる • テンプレートが使われない、1箇所に記録が集 まらないだけで、議論は行われている ◦ 昼会ページ等に議事録は残っている • テンプレートに沿っていないと、提案の質は 担保しづらい ◦

    問題が明らかでないまま解決案を会話しているとか、 選ばなかった他の選択肢が書かれていないとか 48

49. 49 始める前の期待は 満たせたのか

50. 始める前の期待 • 意思決定がまとまって残っているので ◦ 新メンバーのオンボーディングが楽になる ◦ 未来の運用者が決定の過程を楽に追える • アンチパターンを避けられる ◦

    繰り返し何度も議論してしまう ◦ コンテキストが変わったのに変化できない 50

51. 51 意思決定が残っていて 嬉しい

52. 意思決定が残っていて嬉しい • 元々記録はかなり残っていた ◦ 僕らの問題は散らばっていることの方が大きかった • 検索が楽になった！ ◦ 雑多な情報を「ADR」で絞り込むと一覧が出る 52

53. • 今のところ強い嬉しさは少ない ◦ まだ3-4年なので会話した記憶が残っている ◦ 離職率も割と低く、当時の担当者がゼロではない • コンテキストを想像しなくて良いのは最高 ◦ この理由で選んだのであれば理由なくなってるよね、

    という確認ができる 意思決定が残っていて嬉しい 53

54. 54 意思決定のアンチパター ンを避けられるか

55. 意思決定のアンチパターンを 避けられるか • そもそも問題があったか自信が無い • 逆に問題が出てきそうな雰囲気が無くもない ◦ 決定した記録が残っているので、変化に躊躇する ◦ 逆にコンテキストが変わったら、その意思決定は

    deprecatedとすべきである、と繰り返し伝えていく 55

56. 56 議論に持って行く ハードルは下がった

57. 議論に持って行くハードルが下がった • 提案フローが明らかである ◦ RFC -> propose -> accept/reject ◦

    ここに持って行けば絶対に会話して貰える安心感 • 提案のフォーマットも明らかである ◦ 「この問題をこの決定で解く」を書く ◦ 問題が何かを明らかにすることで解決に導く 57

58. 58 まとめ

59. まとめ • ADRは始めやすい施策である ◦ 軽量であるのが強み • 考えた記録がちゃんと残りやすい ◦ コードの変更にPRを出すようなもので、提案やレ ビューを通じて表出化、共同化される

    • 提案フローが明らかになる効果があった ◦ レビューする体制、提案してと言い続ける体制は必要 59