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

Slide 1

Slide 1 text

@hanhan1978 ADRを一年運用してみたそのまま口伝で続ける？メルカリ、カオナビ、estieの試行錯誤から学ぶ設計ドキュメントの活用方法 2024/03/05

Slide 2

Slide 2 text

@hanhan1978 ● 富所亮 ● 所属株式会社カオナビ CTO室 BackEnd Re-architecturing Team (BERT) ● 職業バックエンドエンジニア ● ブログ https://blog.hanhans.net ● Yokohama North AM https://anchor.fm/yokohama-north-am 2

Slide 3

Slide 3 text

ここからしばらくはキレイな話

Slide 4

Slide 4 text

ADRとはなにか？

Slide 5

Slide 5 text

Architectural Decision Records

Slide 6

Slide 6 text

細かいお作法とか言われたりするけど

Slide 7

Slide 7 text

ソフトウェアに関連する決定・経緯を記録しておくものこの程度の認識でだいたい合ってる

Slide 8

Slide 8 text

参考1 https://adr.github.io/

Slide 9

Slide 9 text

参考2 ソフトウェアアーキテクチャーの基礎 13章「アーキテクチャー決定」

Slide 10

Slide 10 text

それぞれの組織の都合に合わせてある程度の改造はありだと思うポイントについては後述

Slide 11

Slide 11 text

弊社のADR このテンプレートから新しいADRを作成する

Slide 12

Slide 12 text

● メール送信の方式 ● ディレクトリ階層 ● CIどうしよう？ ● ログの方式どうしよう？例えばこんな内容がADRになる

Slide 13

Slide 13 text

様々な決定事項を書いて溜めておく気軽なノリが大切

Slide 14

Slide 14 text

ところで

Slide 15

Slide 15 text

Q 普通の設計資料と何が違うの？

Slide 16

Slide 16 text

● DesignDoc ● ReadME ● PRD ● 謎のMiro、Figma ソフトウェア開発では何がしか設計資料必要になるよね

Slide 17

Slide 17 text

A 実態はかわらん弊社開発チームもそれぞれドキュメントを書いていた

Slide 18

Slide 18 text

ではなぜADRが必要になるのか？

Slide 19

Slide 19 text

その前に

Slide 20

Slide 20 text

所属するCTO室の役割について

Slide 21

Slide 21 text

横軸のカイゼンチーム［引用］チームトポロジー Chapter 5 4つの基本的なチームタイプコレとコレとコレ

Slide 22

Slide 22 text

広くチームをサポートする役割

Slide 23

Slide 23 text

ADRの話にもどる

Slide 24

Slide 24 text

いわゆるサービス開発 ● 複数チームが同じアプリケーションを同時並行で開発 ● 一部のチームは異なるアプリケーションを単独で開発

Slide 25

Slide 25 text

各チームのドキュメント ● リードが選んだツールを使う ● 用意するドキュメントは自分たちの開発に必要なもの

Slide 26

Slide 26 text

このドキュメント群は良い意味、悪い意味でサイロ化する

Slide 27

Slide 27 text

良い意味 ● チームはメンバーに最適なツールを自分たちで選定（主体性 ● PdMの管理とも関係しておりマネージメントにもつながる ● 自分たちが作ろうとする機能に最適化していて効率がいい

Slide 28

Slide 28 text

悪い意味 ● チーム部外者に読ませる動機がない ● チームまたぎでの統一感はない（利点の裏返し） ● システム全体の設計を記述するのは不適切

Slide 29

Slide 29 text

ADRの役割 ● そもそもチームをまたいた情報共有のために用意している ● 横軸チームのドキュメント配置場所としても適切

Slide 30

Slide 30 text

ADRはみんなのドキュメント

Slide 31

Slide 31 text

統一フォーマットで認知負荷を下げみんなに情報を共有する

Slide 32

Slide 32 text

● 導入者は社内から信頼されている ● 導入者は積極的に活用 ● 気合と根性 ADRによらず、大体のモノゴトと同じ導入のポイント

Slide 33

Slide 33 text

弊社でのADR事例1 ● チームを横断する決定だったので長年放置されていた ● ADRという形で明文化することで問題が具体化できた

Slide 34

Slide 34 text

弊社でのADR事例2 ● デプロイとリリースを分離する機能トグル ● 特に並行開発においてリリースの細かい制御ができて助かる

Slide 35

Slide 35 text

導入前に気づいてなかった利点

Slide 36

Slide 36 text

歴の浅いメンバーが横断的同意を得やすい古参も援助しやすく、新参も使いやすい 🎉🎉🎉🎉　WIN＆WIN　🎉🎉🎉🎉

Slide 37

Slide 37 text

きれいな話終わり

Slide 38

Slide 38 text

ここから本音

Slide 39

Slide 39 text

● 運用・保守しやすいソースコード ● 個別のドキュメント、コメント ● 決定プロセス、経緯の記録ソフトウェアが備えていてほしい

Slide 40

Slide 40 text

● コードつらい ● ドキュメントない ● 決定プロセス、経緯の記録などない ● チケット？そんなぜいた…ry）開発あるある

Slide 41

Slide 41 text

ある程度の改善はできるソースコードだけから読み取れることも多い

Slide 42

Slide 42 text

理由がわからないと解決策が浅くなる

Slide 43

Slide 43 text

● ところどころに条件分岐 ● 意味があるかわからない消せないコード ● 運用対処（データ更新とかね… 浅い解決策は認知負荷を上げる浅い解決策

Slide 44

Slide 44 text

● 運用・保守しやすいソースコード ● 個別のドキュメント、コメント ● 決定プロセス、経緯の記録これが残っていると根本解決の方向性がつけやすいソフトウェアが備えていてほしい

Slide 45

Slide 45 text

ソースコードがきれいなことはもちろん助かる

Slide 46

Slide 46 text

が！！！コードそのものから読み取れない物がある…

Slide 47

Slide 47 text

さらなる本音

Slide 48

Slide 48 text

とりあえず何でもいいから手がかり残しておいてくれ… 無はつらい（正直ADRじゃなくていい）

Slide 49

Slide 49 text

導入障壁になりそうなこと

Slide 50

Slide 50 text

ドキュメントが必要だと思う経験ドキュメント不要派が一定数存在

Slide 51

Slide 51 text

ドキュメントを書く能力が必要 ADR自体の読みやすさは書き手に依存

Slide 52

Slide 52 text

これだけはやめておけ（ADR編）

Slide 53

Slide 53 text

● 気軽に読み書きできないツール（Git） ● 気軽にコメントできないツール ● テンプレートなしでの運用 ● 履歴が取れない Wiki系ツールなら多分大体OK