ADRを一年運用してみた/adr_after_a_year

PHPカンファレンス小田原2024の登壇資料です。

https://fortee.jp/phpconodawara-2024/proposal/56218b4f-b724-4199-82f1-67497501a9ef

ADRとはなにか？
なぜ、導入する必要があるのか？
実際に導入してみて苦労したこと
良かったこと、悪かったこと

Transcript

1. ADRを一年運用してみた @hanhan1978 PHPカンファレンス小田原2024
2. @hanhan1978 名前 富所 亮 所属 株式会社カオナビ CTO室 BackEnd Re-architecturing Team (BERT) 職業 バックエンドエンジニア Blog https://blog.hanhans.net Podcast https://anchor.fm/yokohama-north-am 2
3. 目次　
4. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ
5. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ
6. Architectural Decision Records
7. トレンド ここ数年でジワジワと浸透
8. 参考1 https://adr.github.io/
9. 参考2 ソフトウェアアーキテクチャーの基礎 13章「アーキテクチャー決定」
10. 細かいお作法とかあるけど
11. ソフトウェアに関連する 決定・経緯を記録しておくもの
12. 例えばこんな決定・経緯 • メール送信の方式 • ディレクトリ階層 • CIどうしよう？ • ログの方式どうしよう？ • 決済代行どうする？
13. ところで
14. Q 普通の設計資料と何が違うの？
15. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ
16. 色々な名前の資料 プロジェクトによって、あったりなかったり • 要件定義書 • DesignDoc • ReadME • PRD • 謎のMiro、Figma
17. Q 普通の設計資料と何が違うの？（再）
18. A. 自分たちで決める必要がある おれたちのADRの位置付けは自分たちで決める
19. 組織におけるADRの立ち位置は 組織の都合、規模によって変わる
20. たとえば弊社
21. 複数チームによるサービス開発 • 複数チームが同じアプリケーションを同時並行で開発 • 一部のチームは異なるアプリケーションを単独で開発
22. 各チームの固有ドキュメント • リードやPMが選んだツールを使う • 用意するドキュメントは自分たちの開発に必要なもの
23. このドキュメント群は 良い意味、悪い意味でサイロ化する
24. 良い意味 • チームはメンバーに最適なツールを自分たちで選定（主体性 • PdMの管理とも関係しておりマネージメントにもつながる • 自分たちが作ろうとする機能に最適化していて効率がいい
25. 悪い意味 • チーム部外者に読ませる動機がない • チームまたぎでの統一感はない（利点の裏返し） • システム全体の設計を記述するのは不適切
26. そこでADRを使って チーム横断の情報共有
27. ADRの役割 • そもそもチームをまたいた情報共有のために用意している • 横軸チームのドキュメント配置場所としても適切
28. ADRにチームの壁を越えさせる ［引用］チームトポロジー Chapter 5 4つの基本的なチームタイプ
29. ADRはみんなのドキュメント
30. 弊社のADR
31. 弊社のADR
32. 弊社のADR
33. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ
34. テンプレートを用意 コピーしてタイトル変えれば叩き台が完成
35. 統一フォーマットで 認知負荷を下げる
36. ADRの実例
37. 弊社でのADR事例1 • チームを横断する決定だったので長年放置されていた • ADRという形で明文化することで問題が具体化できた
38. 弊社でのADR事例2 • デプロイとリリースを分離する機能トグル • 特に並行開発においてリリースの細かい制御ができて助かる
39. ADRで大切な内容 • コンテキスト • 決定 • コンプライアンス 放っておいたら失われてしまうコトを記録するんだ！！
40. ADRを読みやすくする • 読み手を意識 • 抽象から具体へ • 図
41. ADRを読みやすくする • 読み手を意識 • 抽象から具体へ • 図 読み手はエンジニア以外も含む！ みんなのドキュメント
42. ADRを読みやすくする • 読み手を意識 • 抽象から具体へ • 図 パッとみて把握できるように！
43. 良い文章を書くための参考書 考える技術書く技術 : 問題解決力を伸ばすピラミッド原則
44. 良い文章を書くための参考書 入門 考える技術・書く技術
45. ADRを読みやすくする • 読み手を意識 • 抽象から具体へ • 図 人間は文章を読まない！
46. 図の例
47. 図の例 ときには手書きの図
48. 上手なドキュメントを書くには とにかく書いて練習！
49. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ
50. 通し番号で89まで到達 順調に成長中！ 内容はお見せできなくてすまぬ
51. 広い心で若干の粒度の違いは 受け止めている
52. 導入前に気づいてなかった利点
53. 歴の浅いメンバーが横断的同意を得やすい 古参も援助しやすく、新参も使いやすい 🎉🎉🎉🎉　WIN＆WIN　🎉🎉🎉🎉
54. 成功させるために意識していたこと
55. 大事にしていたポイント • ADRの位置付けを明確化 • 履歴の取れるWikiを採用 • 公式感を大切に • 記述のハードルを下げる
56. 過去の失敗経験
57. アンチパターン • 導入が雑 • Gitによる版管理 • 定型フォーマットが無し • 気軽に見れない
58. 結局一番大切なこと
59. 🔥！！情熱！！🔥
60. 参考文献 Fearless Change アジャイルに効く アイデアを組織に広めるための48のパターン
61. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ
62. ADRは横断的な経緯・決定の記録
63. チームを越えられる
64. ADRはみんなのドキュメント 街の掲示板を目指せ！
65. もっと事例を聞きたい方は...... https://offers.jp/worker_events/connpass_26