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

https://offers.connpass.com/event/310086/

そのまま口伝で続ける？メルカリ、カオナビ、estieの試行錯誤から学ぶ設計ドキュメントの活用方法

の登壇資料です。

https://qiita.com/hanhan1978/items/067abd7b28b0807e8c87

Transcript

1. @hanhan1978 ADRを一年運用してみた そのまま口伝で続ける？メルカリ、カオナビ、estieの試行 錯誤から学ぶ設計ドキュメントの活用方法 2024/03/05
2. @hanhan1978 • 富所 亮 • 所属 株式会社カオナビ CTO室 BackEnd Re-architecturing Team (BERT) • 職業 バックエンドエンジニア • ブログ https://blog.hanhans.net • Yokohama North AM https://anchor.fm/yokohama-north-am 2
3. ここからしばらくはキレイな話
4. ADRとはなにか？
5. Architectural Decision Records
6. 細かいお作法とか言われたりするけど
7. ソフトウェアに関連する決定・経緯を 記録しておくもの この程度の認識でだいたい合ってる
8. 参考1 https://adr.github.io/
9. 参考2 ソフトウェアアーキテクチャーの基礎 13章「アーキテクチャー決定」
10. それぞれの組織の都合に合わせて ある程度の改造はありだと思う ポイントについては後述
11. 弊社のADR このテンプレートから新しいADRを作成する
12. • メール送信の方式 • ディレクトリ階層 • CIどうしよう？ • ログの方式どうしよう？ 例えばこんな内容がADRになる
13. 様々な決定事項を書いて溜めておく 気軽なノリが大切
14. ところで
15. Q 普通の設計資料と何が違うの？
16. • DesignDoc • ReadME • PRD • 謎のMiro、Figma ソフトウェア開発では何がしか設計資料必要になるよね
17. A 実態はかわらん 弊社開発チームもそれぞれドキュメントを書いていた
18. ではなぜADRが必要になるのか？
19. その前に
20. 所属するCTO室の役割について
21. 横軸のカイゼンチーム ［引用］チームトポロジー Chapter 5 4つの基本的なチームタイプ コレと コレと コレ
22. 広くチームをサポートする役割
23. ADRの話にもどる
24. いわゆるサービス開発 • 複数チームが同じアプリケーションを同時並行で開発 • 一部のチームは異なるアプリケーションを単独で開発
25. 各チームのドキュメント • リードが選んだツールを使う • 用意するドキュメントは自分たちの開発に必要なもの
26. このドキュメント群は 良い意味、悪い意味でサイロ化する
27. 良い意味 • チームはメンバーに最適なツールを自分たちで選定（主体性 • PdMの管理とも関係しておりマネージメントにもつながる • 自分たちが作ろうとする機能に最適化していて効率がいい
28. 悪い意味 • チーム部外者に読ませる動機がない • チームまたぎでの統一感はない（利点の裏返し） • システム全体の設計を記述するのは不適切
29. ADRの役割 • そもそもチームをまたいた情報共有のために用意している • 横軸チームのドキュメント配置場所としても適切
30. ADRはみんなのドキュメント
31. 統一フォーマットで認知負荷を下げ みんなに情報を共有する
32. • 導入者は社内から信頼されている • 導入者は積極的に活用 • 気合と根性 ADRによらず、大体のモノゴトと同じ 導入のポイント
33. 弊社でのADR事例1 • チームを横断する決定だったので長年放置されていた • ADRという形で明文化することで問題が具体化できた
34. 弊社でのADR事例2 • デプロイとリリースを分離する機能トグル • 特に並行開発においてリリースの細かい制御ができて助かる
35. 導入前に気づいてなかった利点
36. 歴の浅いメンバーが横断的同意を得やすい 古参も援助しやすく、新参も使いやすい 🎉🎉🎉🎉　WIN＆WIN　🎉🎉🎉🎉
37. きれいな話終わり
38. ここから本音
39. • 運用・保守しやすいソースコード • 個別のドキュメント、コメント • 決定プロセス、経緯の記録 ソフトウェアが備えていてほしい
40. • コードつらい • ドキュメントない • 決定プロセス、経緯の記録などない • チケット？そんなぜいた…ry） 開発あるある
41. ある程度の改善はできる ソースコードだけから読み取れることも多い
42. 理由がわからないと解決策が浅くなる
43. • ところどころに条件分岐 • 意味があるかわからない消せないコード • 運用対処（データ更新とかね… 浅い解決策は認知負荷を上げる 浅い解決策
44. • 運用・保守しやすいソースコード • 個別のドキュメント、コメント • 決定プロセス、経緯の記録 これが残っていると根本解決の方向性がつけやすい ソフトウェアが備えていてほしい
45. ソースコードがきれいなことは もちろん助かる
46. が！！！ コードそのものから読み取れない物がある…
47. さらなる本音
48. とりあえず何でもいいから手がかり残 しておいてくれ… 無はつらい（正直ADRじゃなくていい）
49. 導入障壁になりそうなこと
50. ドキュメントが必要だと思う経験 ドキュメント不要派が一定数存在
51. ドキュメントを書く能力が必要 ADR自体の読みやすさは書き手に依存
52. これだけはやめておけ（ADR編）
53. • 気軽に読み書きできないツール（Git） • 気軽にコメントできないツール • テンプレートなしでの運用 • 履歴が取れない Wiki系ツールなら多分大体OK
54. 最後に
55. ADRは横断的な決定事項の記録
56. チームを越えられる
57. 気軽に読み書きできることが大切 街の掲示板を目指せ！