0 Architecture Decision Record (ADR) 2024-09-06 第103回NearMe技術勉強会 @yujiosaka

1 ⼊社時にこんなこと思ったことありませんか？ なんでこんな実装になってるんだっけ？

2 ⼊社後にこんなこと思ったことありませんか？ ⾃分なんでこんな実装したんだっけ？

3 どうしてこうなった？ • ⼈が辞めてしまった • ⾃分が忘れてしまった • 誰が決めたことか分からないない

4 昨⽇の⾃分は他⼈ 4

5 なんでこんな実装になってるのか分からない時の対処法 1. 盲⽬的に従う 2. 盲⽬的に変更する

6 なんでこんな実装になってるのか分からない時の対処法 1. 盲⽬的に従う 2. 盲⽬的に変更する

7 コンテキストは常に変化する • 当時と今ではコンテキストも異なり、最適な判断ではなくなっているかも知れない • 今のコンテキストで判断してしまうと、思いがけない問題が発⽣するかも知れない

8 ドキュメントの問題点 常に更新し続けることが難しい ➔ 誰も書きたがらない ➔ 誰も読みたがらない

9 “包括的なドキュメント よりも動くソフトウェアを” – アジャイル宣言 9

10 Architecture Decision Record (ADR) https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions

11 “ 「アーキテクチャ上重要な」決定事項、す なわち構造、⾮機能的特性、依存関係、イン ターフェース、または構築⼿法に影響を与え るものに関する記録を収集して保持しま す。” – Michael Nygard 11

12 Architecture Decision Record (ADR) • Architecture Decision (AD) ‒ システム設計に⼤きな影響を与える意思決定 • Architecture Decision Record (ADR) ‒ ADを記録するためのドキュメント • Architecture Decision Log (ADL) ‒ 組織やプロジェクトのためのADRの集合 • Architecture Knowledge Management (AKM) ‒ 上記全てのための枠組み

13 Architecture Decision Log (ADL) Architecture Knowledge Management (AKM) Architecture Decision Record (ADR) Architecture Decision Record (ADR) Architecture Decision Record (ADR) Architecture Decision Record (ADR) Architecture Decision Record (ADR) Architecture Decision (AD) Architecture Decision (AD) Architecture Decision (AD) Architecture Decision (AD) Architecture Decision (AD)

14 何を書くのか • コンテキスト ‒ 意思決定が下された⽂脈や背景 • 意思決定 ‒ 「採⽤された選択」と「採⽤されなかった選択」の両⽅ • ステータス ‒ 提案中（Proposed）、承認済（Accepted）、却下（Rejected）等 • 結果 ‒ 期待される効果や予想される影響 👑

15 例）1. Record architecture decisions Date: 2024-08-14 ## Status Accepted ## Context We need to record the architectural decisions made on this project. ## Decision We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisi ons). ## Consequences See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

16 ドキュメントとの違い • 簡潔に書く ‒ 1-2ページ以内の短いテキストファイルで記述する • ただのログ ‒ ステータス以外は後から変更しない

17 どこに書くのか • Google Drive • ソースコードレポジトリ • Issueトラッカー • 社内Wiki （オススメ）

18 ソースコードレポジトリをオススメする理由 • エンジニアにとって⼀番⾝近にある • 実装と⼀緒にコミットすることができる • 変更をPRとしてレビューすることができる

19 いつ書くのか ADRを 書きま しょう 今問題が 起きてい ますか？ 完璧な解決 ⽅法はあり ますか？ 解決⽅法の 提案はあり ますか？ それは⼤きな 変更ですか？ そのRFCで 問題は解決 しますか？ RFCを 書きま しょう Yes Yes Yes Yes Yes No https://engineering-atspotify-com.translate.goog/2020/04/when-should-i-write-an-architecture-decision-record/?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=en&_x_tr_pto=wapp

20 誰のために書くのか • プロジェクトのオーナーが変わった時のために書く • 今のチームメイトに感謝してもらうために書く • 将来⼊社する⼈に感謝してもらうために書く • 将来の⾃分に感謝してもらうために書く

21 adr-tools $ adr new Implement as Unix shell scripts doc/architecture/decisions/0001-implement-as-unix-shell-scripts.md $ cat doc/architecture/decisions/0001-implement-as-unix-shell-scripts.md # 2. Implement as Unix shell scripts Date: 2024-08-14 ## Status Accepted ## Context The issue motivating this decision, and any context that influences or constrains the decision. ## Decision The change that we're proposing or have agreed to implement. ## Consequences What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated. https://github.com/npryce/adr-tools

22 事例 • Spotify ‒ When Should I Write an Architecture Decision Record • Google Cloud ‒ Architecture decision records overview • Azure ‒ Architecture decision record • AWS ‒ Using architectural decision records to streamline technical decision-making for a software development project

23 実際に運⽤してみた① 全く定着しなかった 考えられる理由： • 設計者と実装者は必ずしも⼀致しないため、 実装者がPR作成時にADRを書こうと思い⽴つことがなかった • 変更の提案は別のところ（GitHub Issue）で⾏っていたので、 そこで議論を尽くしたことをわざわざADRに書き写すのが⾯倒臭かった • 書いたところでいつ誰に読まれるのか分からないから モチベーションが湧かなかった

24 実際に運⽤してみた② 今度はうまく⾏った 得られた効果： • ADRの質と量が向上した • 情報共有がうまくなった • 新⼊社員が初めてコードを⾒たときに悪態をつくことが減った • TechLeadだけでなく、社員全員が意思決定に関われるようになった • ドキュメントを書く習慣がついて、ドキュメント全体の質が上がった

25 TIPS 25

26 チケットの受け⼊れ条件にADRを加える • 意思決定を下した設計者と実装者は 必ずしも⼀致しない • 実装者がついでにADRも記述するのが⼿ 取り早いが、⾃分で意思決定を下したわ けではないからそこまで意識が回らない • チケットを作成した設計者が、忘れられ ないように受け⼊れ条件に追加する • スクラムのリファインメントでも、 「その機能はADR書いた⽅がいいね」 等の指摘を出し合う # Motivation ISMS認証を取得するために、管理画⾯の操 作ログを保存しなければならない # Current behavior 管理画⾯でサービスに影響を与える変更が⾏ われても、誰が操作したのか分からない # Expected behavior AsyncLocalStorageにユーザー名を保存し、 ユーザー名と更新内容を記録する # Acceptance criteria 単体テスト パフォーマンステスト ADR追加

27 オンボーディングタスクで直近のADRを読んでもらう • オンボーディングタスクには「オンボー ディングドキュメントを読む」や「テス トのシナリオを読む」等のタスクがある • それらのタスクの⼀つとして、直近（※ 全てではない）のADRを読んでもらい、 過去の意思決定のコンテキストを掴んで もらう # Motivation NearMeでの意思決定プロセスに慣れ親しむ NearMeの設計の意図を汲み取る # Expected behavior 以下のディレクトリから最新20のADRを読む https://github.com/…/doc/architecture # Acceptance criteria 読み終わったらチケットをCloseする

28 スプリント中に追加されたADRを振り返る

29 変更提案からADRを使⽤する ステータスにProposed（提案された）を追加する • Proposed ‒ 提案中で皆の意⾒を求める。RFCとも呼ばれる • Accepted ‒ 採⽤された • Rejected ‒ 提案された（Proposed）が採⽤されなかった • Deprecated ‒ 過去に採⽤されたが、現在では実効⼒がない • Superseded ‒ 別のADRによって置き換わった。       「Superseded by 005」のように使われる

30 ADRをGitHub Discussionsと同期させる https://github.com/marketplace/actions/adr-sync

31 ADRをGitHub Discussionsと同期させる 課題 変更提案をgitのレポジトリに追加しても、コメントは書けないから議論が盛り上がらない 機能 • gitのレポジトリでADRが追加‧変更されたらGitHub Discussionsにも同期させる • ステータス（Proposed、Accepted、etc.）をラベルにして同期させる • 特定のステータス（Accepted、Deprecated、etc.）の議論は⾃動で閉じる

32 ADRをGitHub Discussionsと同期させる 使い⽅ name: Synchronize ADR on: push: branches: - main jobs: sync-adr: runs-on: ubuntu-latest steps: - name: Run ADR Sync Action uses: yujiosaka/adr-action@v1 with: discussion-category: ADR env: GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}

33 ADRをGitHub Discussionsと同期させる イメージ

34 Thank you