Slide 1
Slide 1 text
ADRを運用して3年経った
僕らの現在地
id:onk
2024-10-05 YAPC::Hakodate 2024
1
Slide 2
Slide 2 text
自己紹介
● 大仲 能史 a.k.a. id:onk
● 芸歴20年目
● 株式会社はてな
○ チーフエンジニア
○ 好きなPerlプロダクトは箱庭諸島
○ 京都から陸路で来ました
2
Slide 3
Slide 3 text
3
ADRとは
Slide 4
Slide 4 text
ADRとは
● Architecture Decision Records
○ アーキテクチャ上の設計判断を記録する
○ 意思決定を記録、共有する手法
● 2017年ぐらいから流行り始めた
● Design It!やソフトウェアアーキテ
クチャの基礎に詳しく書いてある
4
Slide 5
Slide 5 text
ADRとは
● アーキテクチャが何故そうなっているかは
記録に残りづらい
○ コンテキストはコード上に残らない
● 最初は口伝で伝わるが、記憶が薄れたり
人が入れ替わったりして、いつか形骸化する
○ 徐々に色褪せていき、意図不明なルールだけが残る
5
Slide 6
Slide 6 text
ADRとは
● ADRと既存のアーキテクチャ文書との違い
○ 継続的に書き残していくことに重きを置いている
○ 決定事項だけではなく、コンテキストも書かれる
○ "軽量"で、カジュアルに書きやすい
● Design Docには設計の詳細も書く
○ 意思決定に関わる内容だけを書くのがADR
6
Slide 7
Slide 7 text
7
はてなのプロダクト
Slide 8
Slide 8 text
はてなのプロダクト
● 2001年7月設立
● 15年物のプロダクトも現役
○ 2001 人力検索はてな
○ 2005 はてなフォトライフ、はてなブックマーク
○ 2006 はてな匿名ダイアリー
○ 2007 はてなスター
8
Slide 9
Slide 9 text
はてなのプロダクト
● 15年前は完全に他人
○ 生き字引たちも記憶が無い
● すべてがテキストで残ってはいる
○ 社内グループウェア最高！
● ただし検索が上手くないとたどり着けない
○ グループウェアのログ、IRCのログ、Slackのログ、
GitHub Issue/PR、コミットメッセージ、……
9
Slide 10
Slide 10 text
10
考古学が必要になる
Slide 11
Slide 11 text
11
何故こうしたのかが
分かりやすく一覧に
残っていれば……
Slide 12
Slide 12 text
12
今、開発している
新しいプロダクトも
経緯を追いやすくしたい
Slide 13
Slide 13 text
13
ADRがドンピシャっぽい
Slide 14
Slide 14 text
14
ADRの始め方
Slide 15
Slide 15 text
ADRの始め方
● 導入は難しくない
○ なんせ"軽量"なドキュメント
○ テキストの保存場所さえあれば始められる
● テンプレートもいっぱいある
○ https://github.com/joelparkerhenderson/archit
ecture-decision-record
15
Slide 16
Slide 16 text
ADRの始め方
● 導入は難しくない
○ なんせ"軽量"なドキュメント
○ テキストの保存場所さえあれば始められる
● テンプレートもいっぱいある
○ https://github.com/joelparkerhenderson/archit
ecture-decision-record
16
Slide 17
Slide 17 text
ADRを保存する場所
● Helpfeel Cosense
● GitHub Repo (ソースコードと同じ場所) に置
いたこともあるが、すぐにCosenseになった
● 「書きやすさ」「会話しやすさ」を大事にす
るとGitHubは不向きだった
17
Slide 18
Slide 18 text
ADRをいつ書くのか
● 実装内容が自明でないとき
● 「設計したぞ」と思うことをしたとき
● 迷ったら書きましょう
18
Slide 19
Slide 19 text
ADRのテンプレート
● 作成日・作成者
● ステータス
● 問題
● コンテキスト
19
● 決定
● 影響
● 代替案
● 感想コーナー
Slide 20
Slide 20 text
ADRのテンプレート
● ステータス
○ proposed, accepted, rejected, …
● 問題
○ 問題は何なのか。それはなぜ問題なのか
● コンテキスト
○ 問題が発生する背景は何なのか
20
Slide 21
Slide 21 text
ADRのテンプレート
● 決定
○ 問題を解決するために導入するもの。その根拠
● 影響
○ この決定による影響やトレードオフ。影響にどう対応
するか
21
Slide 22
Slide 22 text
22
書き始めたら数年で
全チームに波及した
Slide 23
Slide 23 text
23
起きた出来事を
8個ほど紹介
Slide 24
Slide 24 text
24
GitHubが使われない
Slide 25
Slide 25 text
GitHubが使われない
● 下書きをCosenseで、レビューをGitHubで
○ 下書きの段階で軽く揉む
○ ある程度書けたらGitHubに持って行き、
「提案済み」ステータスにする
○ GitHubで改めてレビューし、採択か破棄を決定する
● GitHubに持って行ったのは最初の2件だけ
25
Slide 26
Slide 26 text
GitHubが使われない
● 教訓：ワークフローよりも対話
● 対話したいからADRにしている
○ 自信が無い
○ チームの決め事にしたい
● 対話するなら、いつもの場所
○ いつもの定例、いつもの議事録のそば
26
Slide 27
Slide 27 text
27
RFC文化の発達
Slide 28
Slide 28 text
RFC文化の発達
● Requests for Comments
● 是非を問う前に有識者のコメントが欲しい
○ 叩き台の選択肢からガラッと変わることも
28
Slide 29
Slide 29 text
RFC文化の発達
● テンプレートに議論コーナーができた
○ インラインや感想コーナーで議論した後、ストック
情報として清書し、後から見返せるドキュメントに
● ステータスにRFCが増えた
○ draft -> rfc -> proposed -> accepted/rejected
29
Slide 30
Slide 30 text
30
レビューに時間がかかる
Slide 31
Slide 31 text
レビューに時間がかかる
● やりたいことがあるから提案しているのに、
理想の速度で決定されない
● RFCの裏返し
○ いつまでコメント募集なのか
○ Proposeしたものはいつどこで決定されるのか
31
Slide 32
Slide 32 text
レビューに時間がかかる
● ステータスに期日を設けた
○ RFC 〜2024-10-01
○ proposed 〜2024-10-05
○ accepted/rejected 2024-10-05
● proposedになったらApproverに責任が移る
○ 責任を持って期日までにaccept or reject
32
Slide 33
Slide 33 text
レビューに時間がかかる
● ADRのレビュータスクをスクラムに乗せた
○ 普段のタスク管理と同じところに置いて、
常に視界に入るように
33
Slide 34
Slide 34 text
34
書きすぎる
Slide 35
Slide 35 text
書きすぎる
● 選択肢を丁寧に書きすぎる
○ 認識が揃っているところは省略されている方が良い
○ レビューで構えなきゃいけない度合いが誤って伝わる
● 選ぶ理由はだいたい分かる
○ 選ばない理由の方が理由があることが多い
○ 後世ではコンテキストが薄すぎるので「もっと書け」
になるかもしれないが……
35
Slide 36
Slide 36 text
書きすぎる
● 防衛的になる必要はない
○ ADRは意思決定を推進するために書くもの
36
Slide 37
Slide 37 text
書きすぎる
● 何が決定的な要因になるかの想定を持つ
○ 提案が受け入れられる条件は何なのか
● 主な判断材料以外の要素は軽く書く
○ すべての差分を明らかにする必要はない
37
Slide 38
Slide 38 text
38
書けない
Slide 39
Slide 39 text
書けない
● やりたい、と言ってきたことに対して「ADR
をください」を返した後に起きやすい
● どこが議論ポイントになるのかの想定を持て
てなく、何を書いたら良いか分からない
● 壁打ちやペアライティングが必要
39
Slide 40
Slide 40 text
40
Approverが大変
Slide 41
Slide 41 text
Approverが大変
● 全方位の知識を要求される
○ 難しい内容だったり、知らない内容だったり
○ 自分を判断できる状態に持って行くのに数時間〜数日
かかることも
41
Slide 42
Slide 42 text
Approverが大変
● 強いテクノロジーマネジメントが必要
○ 提案されたら意思決定を下さなければならない
○ この情報が足りない、を明確に打ち返す必要がある
● 現場でレビューが回るなら大丈夫
○ 技術領域 (c.f. Webフロントエンド) ごとに委譲する
○ できていないならApproverが頑張ることになる
42
Slide 43
Slide 43 text
43
下書きで止まる
Slide 44
Slide 44 text
下書きで止まる
● 書き始めたはいいが、完成させられなかった
ADRたち
● proposedになっていないので
accepted/rejectedに到達しない
44
Slide 45
Slide 45 text
下書きで止まる
● 下書きで共有されるのは素晴らしいこと
○ 隠し持っておくより全然いい
○ 何度か書きかけると、徐々に気運が高まっていく
○ 問題の形が徐々に削り出されていく
● Issueと同じく、仕掛品が溜まり続ける
○ staleなADRは積極的にcloseしていくとヨサソウ
45
Slide 46
Slide 46 text
46
ADRが使われなくなる
Slide 47
Slide 47 text
ADRが使われなくなる
● 異動や退職で、ADRを出す人、ADRにしてね
と言う人がいなくなる
● 数ヶ月動かないと、ADRというテンプレート
が存在していたことが意識に上らなくなる
47
Slide 48
Slide 48 text
ADRが使われなくなる
● テンプレートが使われない、1箇所に記録が集
まらないだけで、議論は行われている
○ 昼会ページ等に議事録は残っている
● テンプレートに沿っていないと、提案の質は
担保しづらい
○ 問題が明らかでないまま解決案を会話しているとか、
選ばなかった他の選択肢が書かれていないとか
48
Slide 49
Slide 49 text
49
始める前の期待は
満たせたのか
Slide 50
Slide 50 text
始める前の期待
● 意思決定がまとまって残っているので
○ 新メンバーのオンボーディングが楽になる
○ 未来の運用者が決定の過程を楽に追える
● アンチパターンを避けられる
○ 繰り返し何度も議論してしまう
○ コンテキストが変わったのに変化できない
50
Slide 51
Slide 51 text
51
意思決定が残っていて
嬉しい
Slide 52
Slide 52 text
意思決定が残っていて嬉しい
● 元々記録はかなり残っていた
○ 僕らの問題は散らばっていることの方が大きかった
● 検索が楽になった！
○ 雑多な情報を「ADR」で絞り込むと一覧が出る
52
Slide 53
Slide 53 text
● 今のところ強い嬉しさは少ない
○ まだ3-4年なので会話した記憶が残っている
○ 離職率も割と低く、当時の担当者がゼロではない
● コンテキストを想像しなくて良いのは最高
○ この理由で選んだのであれば理由なくなってるよね、
という確認ができる
意思決定が残っていて嬉しい
53
Slide 54
Slide 54 text
54
意思決定のアンチパター
ンを避けられるか
Slide 55
Slide 55 text
意思決定のアンチパターンを
避けられるか
● そもそも問題があったか自信が無い
● 逆に問題が出てきそうな雰囲気が無くもない
○ 決定した記録が残っているので、変化に躊躇する
○ 逆にコンテキストが変わったら、その意思決定は
deprecatedとすべきである、と繰り返し伝えていく
55
Slide 56
Slide 56 text
56
議論に持って行く
ハードルは下がった
Slide 57
Slide 57 text
議論に持って行くハードルが下がった
● 提案フローが明らかである
○ RFC -> propose -> accept/reject
○ ここに持って行けば絶対に会話して貰える安心感
● 提案のフォーマットも明らかである
○ 「この問題をこの決定で解く」を書く
○ 問題が何かを明らかにすることで解決に導く
57
Slide 58
Slide 58 text
58
まとめ
Slide 59
Slide 59 text
まとめ
● ADRは始めやすい施策である
○ 軽量であるのが強み
● 考えた記録がちゃんと残りやすい
○ コードの変更にPRを出すようなもので、提案やレ
ビューを通じて表出化、共同化される
● 提案フローが明らかになる効果があった
○ レビューする体制、提案してと言い続ける体制は必要
59