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