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

2024-10-05 YAPC::Hakodate 2024
https://yapcjapan.org/2024hakodate/

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