Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
ADRを運用して3年経った僕らの現在地
Search
Takafumi ONAKA
PRO
October 05, 2024
Technology
21
22k
ADRを運用して3年経った僕らの現在地
2024-10-05 YAPC::Hakodate 2024
https://yapcjapan.org/2024hakodate/
Takafumi ONAKA
PRO
October 05, 2024
Tweet
Share
More Decks by Takafumi ONAKA
See All by Takafumi ONAKA
強いチームと開発生産性
onk
PRO
40
17k
1文字エイリアスのすゝめ
onk
PRO
0
57
すこやかなサービス運営のための PWG (Performance Working Group)
onk
PRO
0
910
オブザーバビリティの Primary Signals
onk
PRO
2
5.9k
Cache Stampede
onk
PRO
1
2.2k
ORM - Object-relational mapping
onk
PRO
2
3.7k
デュアルトラックアジャイルとの向き合い方
onk
PRO
5
12k
技術記事を書く&楽しむチームの作り方
onk
PRO
0
1.9k
熊とワルツを
onk
PRO
0
8
Other Decks in Technology
See All in Technology
怖くない!はじめてのClaude Code
shinya337
0
400
【5分でわかる】セーフィー エンジニア向け会社紹介
safie_recruit
0
27k
関数型プログラミングで 「脳がバグる」を乗り越える
manabeai
1
190
fukabori.fm 出張版: 売上高617億円と高稼働率を陰で支えた社内ツール開発のあれこれ話 / 20250704 Yoshimasa Iwase & Tomoo Morikawa
shift_evolve
PRO
2
7.8k
整頓のジレンマとの戦い〜Tidy First?で振り返る事業とキャリアの歩み〜/Fighting the tidiness dilemma〜Business and Career Milestones Reflected on in Tidy First?〜
bitkey
2
16k
DBのスキルで生き残る技術 - AI時代におけるテーブル設計の勘所
soudai
PRO
50
20k
KubeCon + CloudNativeCon Japan 2025 Recap
ren510dev
1
390
AWS Organizations 新機能!マルチパーティ承認の紹介
yhana
1
280
スタートアップに選択肢を 〜生成AIを活用したセカンダリー事業への挑戦〜
nstock
0
210
AI専用のリンターを作る #yumemi_patch
bengo4com
5
4.3k
Operating Operator
shhnjk
1
590
Geminiとv0による高速プロトタイピング
shinya337
1
270
Featured
See All Featured
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
44
2.4k
GraphQLの誤解/rethinking-graphql
sonatard
71
11k
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
PRO
181
54k
Fantastic passwords and where to find them - at NoRuKo
philnash
51
3.3k
Writing Fast Ruby
sferik
628
62k
Imperfection Machines: The Place of Print at Facebook
scottboms
267
13k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
194
16k
Code Review Best Practice
trishagee
69
18k
XXLCSS - How to scale CSS and keep your sanity
sugarenia
248
1.3M
The Cult of Friendly URLs
andyhume
79
6.5k
BBQ
matthewcrist
89
9.7k
Raft: Consensus for Rubyists
vanstee
140
7k
Transcript
ADRを運用して3年経った 僕らの現在地 id:onk 2024-10-05 YAPC::Hakodate 2024 1
自己紹介 • 大仲 能史 a.k.a. id:onk • 芸歴20年目 • 株式会社はてな
◦ チーフエンジニア ◦ 好きなPerlプロダクトは箱庭諸島 ◦ 京都から陸路で来ました 2
3 ADRとは
ADRとは • Architecture Decision Records ◦ アーキテクチャ上の設計判断を記録する ◦ 意思決定を記録、共有する手法 •
2017年ぐらいから流行り始めた • Design It!やソフトウェアアーキテ クチャの基礎に詳しく書いてある 4
ADRとは • アーキテクチャが何故そうなっているかは 記録に残りづらい ◦ コンテキストはコード上に残らない • 最初は口伝で伝わるが、記憶が薄れたり 人が入れ替わったりして、いつか形骸化する ◦
徐々に色褪せていき、意図不明なルールだけが残る 5
ADRとは • ADRと既存のアーキテクチャ文書との違い ◦ 継続的に書き残していくことに重きを置いている ◦ 決定事項だけではなく、コンテキストも書かれる ◦ "軽量"で、カジュアルに書きやすい •
Design Docには設計の詳細も書く ◦ 意思決定に関わる内容だけを書くのがADR 6
7 はてなのプロダクト
はてなのプロダクト • 2001年7月設立 • 15年物のプロダクトも現役 ◦ 2001 人力検索はてな ◦ 2005
はてなフォトライフ、はてなブックマーク ◦ 2006 はてな匿名ダイアリー ◦ 2007 はてなスター 8
はてなのプロダクト • 15年前は完全に他人 ◦ 生き字引たちも記憶が無い • すべてがテキストで残ってはいる ◦ 社内グループウェア最高! •
ただし検索が上手くないとたどり着けない ◦ グループウェアのログ、IRCのログ、Slackのログ、 GitHub Issue/PR、コミットメッセージ、…… 9
10 考古学が必要になる
11 何故こうしたのかが 分かりやすく一覧に 残っていれば……
12 今、開発している 新しいプロダクトも 経緯を追いやすくしたい
13 ADRがドンピシャっぽい
14 ADRの始め方
ADRの始め方 • 導入は難しくない ◦ なんせ"軽量"なドキュメント ◦ テキストの保存場所さえあれば始められる • テンプレートもいっぱいある ◦
https://github.com/joelparkerhenderson/archit ecture-decision-record 15
ADRの始め方 • 導入は難しくない ◦ なんせ"軽量"なドキュメント ◦ テキストの保存場所さえあれば始められる • テンプレートもいっぱいある ◦
https://github.com/joelparkerhenderson/archit ecture-decision-record 16
ADRを保存する場所 • Helpfeel Cosense • GitHub Repo (ソースコードと同じ場所) に置 いたこともあるが、すぐにCosenseになった
• 「書きやすさ」「会話しやすさ」を大事にす るとGitHubは不向きだった 17
ADRをいつ書くのか • 実装内容が自明でないとき • 「設計したぞ」と思うことをしたとき • 迷ったら書きましょう 18
ADRのテンプレート • 作成日・作成者 • ステータス • 問題 • コンテキスト 19
• 決定 • 影響 • 代替案 • 感想コーナー
ADRのテンプレート • ステータス ◦ proposed, accepted, rejected, … • 問題
◦ 問題は何なのか。それはなぜ問題なのか • コンテキスト ◦ 問題が発生する背景は何なのか 20
ADRのテンプレート • 決定 ◦ 問題を解決するために導入するもの。その根拠 • 影響 ◦ この決定による影響やトレードオフ。影響にどう対応 するか
21
22 書き始めたら数年で 全チームに波及した
23 起きた出来事を 8個ほど紹介
24 GitHubが使われない
GitHubが使われない • 下書きをCosenseで、レビューをGitHubで ◦ 下書きの段階で軽く揉む ◦ ある程度書けたらGitHubに持って行き、 「提案済み」ステータスにする ◦ GitHubで改めてレビューし、採択か破棄を決定する
• GitHubに持って行ったのは最初の2件だけ 25
GitHubが使われない • 教訓:ワークフローよりも対話 • 対話したいからADRにしている ◦ 自信が無い ◦ チームの決め事にしたい •
対話するなら、いつもの場所 ◦ いつもの定例、いつもの議事録のそば 26
27 RFC文化の発達
RFC文化の発達 • Requests for Comments • 是非を問う前に有識者のコメントが欲しい ◦ 叩き台の選択肢からガラッと変わることも 28
RFC文化の発達 • テンプレートに議論コーナーができた ◦ インラインや感想コーナーで議論した後、ストック 情報として清書し、後から見返せるドキュメントに • ステータスにRFCが増えた ◦ draft
-> rfc -> proposed -> accepted/rejected 29
30 レビューに時間がかかる
レビューに時間がかかる • やりたいことがあるから提案しているのに、 理想の速度で決定されない • RFCの裏返し ◦ いつまでコメント募集なのか ◦ Proposeしたものはいつどこで決定されるのか
31
レビューに時間がかかる • ステータスに期日を設けた ◦ RFC 〜2024-10-01 ◦ proposed 〜2024-10-05 ◦
accepted/rejected 2024-10-05 • proposedになったらApproverに責任が移る ◦ 責任を持って期日までにaccept or reject 32
レビューに時間がかかる • ADRのレビュータスクをスクラムに乗せた ◦ 普段のタスク管理と同じところに置いて、 常に視界に入るように 33
34 書きすぎる
書きすぎる • 選択肢を丁寧に書きすぎる ◦ 認識が揃っているところは省略されている方が良い ◦ レビューで構えなきゃいけない度合いが誤って伝わる • 選ぶ理由はだいたい分かる ◦
選ばない理由の方が理由があることが多い ◦ 後世ではコンテキストが薄すぎるので「もっと書け」 になるかもしれないが…… 35
書きすぎる • 防衛的になる必要はない ◦ ADRは意思決定を推進するために書くもの 36
書きすぎる • 何が決定的な要因になるかの想定を持つ ◦ 提案が受け入れられる条件は何なのか • 主な判断材料以外の要素は軽く書く ◦ すべての差分を明らかにする必要はない 37
38 書けない
書けない • やりたい、と言ってきたことに対して「ADR をください」を返した後に起きやすい • どこが議論ポイントになるのかの想定を持て てなく、何を書いたら良いか分からない • 壁打ちやペアライティングが必要 39
40 Approverが大変
Approverが大変 • 全方位の知識を要求される ◦ 難しい内容だったり、知らない内容だったり ◦ 自分を判断できる状態に持って行くのに数時間〜数日 かかることも 41
Approverが大変 • 強いテクノロジーマネジメントが必要 ◦ 提案されたら意思決定を下さなければならない ◦ この情報が足りない、を明確に打ち返す必要がある • 現場でレビューが回るなら大丈夫 ◦
技術領域 (c.f. Webフロントエンド) ごとに委譲する ◦ できていないならApproverが頑張ることになる 42
43 下書きで止まる
下書きで止まる • 書き始めたはいいが、完成させられなかった ADRたち • proposedになっていないので accepted/rejectedに到達しない 44
下書きで止まる • 下書きで共有されるのは素晴らしいこと ◦ 隠し持っておくより全然いい ◦ 何度か書きかけると、徐々に気運が高まっていく ◦ 問題の形が徐々に削り出されていく •
Issueと同じく、仕掛品が溜まり続ける ◦ staleなADRは積極的にcloseしていくとヨサソウ 45
46 ADRが使われなくなる
ADRが使われなくなる • 異動や退職で、ADRを出す人、ADRにしてね と言う人がいなくなる • 数ヶ月動かないと、ADRというテンプレート が存在していたことが意識に上らなくなる 47
ADRが使われなくなる • テンプレートが使われない、1箇所に記録が集 まらないだけで、議論は行われている ◦ 昼会ページ等に議事録は残っている • テンプレートに沿っていないと、提案の質は 担保しづらい ◦
問題が明らかでないまま解決案を会話しているとか、 選ばなかった他の選択肢が書かれていないとか 48
49 始める前の期待は 満たせたのか
始める前の期待 • 意思決定がまとまって残っているので ◦ 新メンバーのオンボーディングが楽になる ◦ 未来の運用者が決定の過程を楽に追える • アンチパターンを避けられる ◦
繰り返し何度も議論してしまう ◦ コンテキストが変わったのに変化できない 50
51 意思決定が残っていて 嬉しい
意思決定が残っていて嬉しい • 元々記録はかなり残っていた ◦ 僕らの問題は散らばっていることの方が大きかった • 検索が楽になった! ◦ 雑多な情報を「ADR」で絞り込むと一覧が出る 52
• 今のところ強い嬉しさは少ない ◦ まだ3-4年なので会話した記憶が残っている ◦ 離職率も割と低く、当時の担当者がゼロではない • コンテキストを想像しなくて良いのは最高 ◦ この理由で選んだのであれば理由なくなってるよね、
という確認ができる 意思決定が残っていて嬉しい 53
54 意思決定のアンチパター ンを避けられるか
意思決定のアンチパターンを 避けられるか • そもそも問題があったか自信が無い • 逆に問題が出てきそうな雰囲気が無くもない ◦ 決定した記録が残っているので、変化に躊躇する ◦ 逆にコンテキストが変わったら、その意思決定は
deprecatedとすべきである、と繰り返し伝えていく 55
56 議論に持って行く ハードルは下がった
議論に持って行くハードルが下がった • 提案フローが明らかである ◦ RFC -> propose -> accept/reject ◦
ここに持って行けば絶対に会話して貰える安心感 • 提案のフォーマットも明らかである ◦ 「この問題をこの決定で解く」を書く ◦ 問題が何かを明らかにすることで解決に導く 57
58 まとめ
まとめ • ADRは始めやすい施策である ◦ 軽量であるのが強み • 考えた記録がちゃんと残りやすい ◦ コードの変更にPRを出すようなもので、提案やレ ビューを通じて表出化、共同化される
• 提案フローが明らかになる効果があった ◦ レビューする体制、提案してと言い続ける体制は必要 59