チームの性質によって変わる ADR との向き合い方と、生成 AI 時代のこれから / How to deal with ADR depends on the characteristics of the team

2025/03/26 「実例！フロントエンドの技術選定とその後を ADR から振り返る」で発表したスライドです。
https://findy-tools.connpass.com/event/347251/

参照したURL

- チームにおける ADR 導入から 1 年経った振り返りと感想 - ROUTE06 Tech Blog
- チーム開発における技術選定の進め方 - ROUTE06 Tech Blog
- アーキテクチャ決定記録（ADR）を活用した要件定義プロセス - ROUTE06 Professional Services
- Corporate Decision Record (CDR) 〜 GitHub を活用した新しい稟議システム｜ ROUTE06
- チーム開発における技術選定の進め方 - ROUTE06 Tech Blog
- ADR で意思決定し、その ADR を破棄して新しく ADR を作成する実例を紹介します - GraphQL クライアントのキャッシュアルゴリズム変更編 - ROUTE06 Tech Blog
- 技術顧問として半年間で感じた会社の成長 - ROUTE06 Tech Blog
- Liam ERD
- Architecture Decision Records - Liam ERD
- liam/frontend/apps/docs/content/docs/contributing/adr at main · liam-hq/liam
- The 70% problem: Hard truths about AI-assisted coding - Medium
- CLINE に全部賭けろ - Zenn
- architecture-decision-record/locales/en/templates/decision-record-template-by-michael-nygard/index.md - GitHub

Transcript

1. チームの性質によって変わる ADR との向 き合い方と、生成 AI 時代のこれから Hirotaka Miyagi / @MH4GF 2025/03/26 実例！フロントエンドの技術選定とその後を ADR から 振り返る 1
2. Hirotaka Miyagi / @MH4GF GraphQL, GitHub Actions, 静的解析が好き ROUTE06, inc. Liam ERD という OSS の ER 図自動生成ツールを開発 中 自己紹介 2
3. ADR とは？ についてはこの発表では省略します 3
4. 1. ROUTE06 と ADR 2. 2 つのプロジェクトでの運用事例 商社向け SaaS ... 大規模受託開発プロジェクト 開発者向けツール ... 新規事業プロジェクト 3. 生成 AI 時代の ADR と技術選定 4. Appendix: ADR のオレオレベストプラクティス アジェンダ 4
5. ROUTE06 と ADR 5
6. 会社名 株式会社ＲＯＵＴＥ０６ 住所 東京都千代田区丸の内一丁目 6-5 丸の内北口ビルディング 9F 設立 2020年1月 資本金 1 億円 取締役 遠藤崇史 (代表) 事業内容 エンタープライズソフトウェアサービス・プロフェッショナルサービス 法務顧問 アンダーソン・毛利・友常法律事務所 会社概要 6
7. 2022 年頃から一つのチームで運用開始 事業上新規立ち上げの機会も多く、プロジェクトも多いことから丁寧にドキュメントを残す 文化があり、ADR は文化にマッチした 現在は多くのチームで運用中 会社のブログでも何件か ADR の記事を公開している チームにおける ADR 導入から 1 年経った振り返りと感想 - ROUTE06 Tech Blog チーム開発における技術選定の進め方 - ROUTE06 Tech Blog アーキテクチャ決定記録（ADR）を活用した要件定義プロセス - ROUTE06 Professional Services ROUTE06 と ADR 7
8. 全社的なオペレーションに GitHub を採用しており、経理や人事のメンバーも Pull Request を出す 社内の稟議システムも ADR のエッセンスを取り入れ GitHub 上で行っている ROUTE06 では今年度から GitHub を活用した新しい稟議システムの運用を開始しました。 ソフトウェア開発において技術やアーキテクチャ選定で活用される Architectural Decision Record (ADR) の思想と手法に習い、会社運営に関わる意思決定のログ (申請/承認/回覧) を 記録する仕組みを構築し、Corporate Decision Record (CDR) と命名しております。 少額の経費申請から大型投資や資金調達まで、管理職の権限と責任に基づくあらゆる承認 が CDR を介して行われるようになりました。 ref: Corporate Decision Record (CDR) 〜 GitHub を活用した新しい稟議システム｜ ROUTE06 ROUTE06 と ADR 8
9. 「理論的根拠に対する強固な共通の理解を作るための ADR」 私のチームは、私がテックリードになる前から、技術選定の経緯や結果をドキュメントと して残す ADR が実践されていました。新しくチームに参加した人から「素晴らしい」や 「助かる」といった声を聞くのでこれは十分に機能しているでしょう。 しかし、私は ADR にはもっと多くのことを表現できる可能性があると考えており、具体的 には ADR で「理論的根拠に対する強固な共通の理解を作る」ことはできないか試していま す。そして、ADR を Pull request にして、レビューで議論し、最終的にコミットメントで きる場合は Approve してもらうことで、マイケルの「決定された行動方針に対する高度の コミットメント、およびその理論的根拠に対する強固な共通の理解」を実現することがで きると考えています。 ref: チーム開発における技術選定の進め方 - ROUTE06 Tech Blog 同僚の好きな言葉 1 9
10. 「ADR は意思決定を破棄するための技術」 ADR を破棄し、新しく意思決定をし直すことは、その領域に対して解像度が高まったこと を示す大きな価値 「誤り」や「変更」は失敗ではなく、さらに深まった知見とともに新しい ADR を作り出す 重要なプロセス ADR がすでにあって過去の意思決定の経緯がわかっているからこそ、新しい意思決定を自 信を持って進めることができる 同僚の好きな言葉 2 10
11. この二つを伝えられたら終わりなんですが、それだけだと登 壇の意味がないので、自分が所属していた 2 つのチームで の ADR の運用事例を紹介します プロジェクト 1: 商社向け SaaS・受託開発プロジェクト・チーム規模 12-15 人 プロジェクト 2: 開発者向けツール・新規事業プロジェクト・チーム規模 5-7 人 11
12. 受託開発プロジェクト Vite 製の SPA, GraphQL を利用し API リクエストをする Web アプリケーション ページ数や機能数が多く長期間のプロジェクト・フロントエンド/バックエンドでチームと して分離していた フロントエンド開発メンバーだけで最大 15 人 (10 人チーム +5 人チーム) プロジェクト 1 - プロジェクトの特徴 12
13. 1 年でフロントエンドだけで 50 の ADR ライブラリやツールの選定理由 エラーハンドリングなどの実装方針 ディレクトリ設計 ドメインに関わる仕様 プロジェクト 1 - 実際に書いた ADR 13
14. 実際の ADR の中身の一部をブログに公開しているので、そちらも合わせてご覧ください！ ADR で意思決定し、その ADR を破棄して新しく ADR を作成する実例を紹介します - GraphQL クライアントのキャッシュアルゴリズム変更編 - ROUTE06 Tech Blog プロジェクト 1 - 実際に書いた ADR 14
15. 比較的詳細まで ADR として記載していた 事業の性質: プロジェクトの性質上長期間保守することが予想された 関係者の多さ: 開発に参加するメンバーも多く、共通理解を深めやすくしたい 2023 年の業界動向: Web フロントエンドではそれぞれの領域でデファクトスタンダードと なっている構成が確立されておらず、複数の選択肢から判断する状況が多かった プロジェクト 1 - 運用方針 15
16. GitHub リポジトリにマークダウンファイルとして格納 テックリードに限定せず、全員で ADR を書く 調査 Issue を担当した人が執筆 Pull Request 上で議論し、マージされたら Accepted とする Issue 上で調査 → PoC 実装 → ADR 追加 PR の作成 → 本実装 のワークフロー プロジェクト 1 - 運用方法 16
17. 技術顧問の hiroppy さんと定期的に ADR を振り返る会を実施 「運用してみてどう？」 「そもそもこれってどういう意味？」などを議論し、チームの共通 理解をさらに深める ROUTE06 社ではなにかの意思決定をするときに ADR を作りメンバーの承認を得るフロー があり、どういう経緯で導入されたのかがわかります。この会でもその ADR を再度議論し たり、今後組織やコードベース自体が大きくなっていくので、どのようにスケールしやす い構成や仕組みを作っていくかをみんなで考えています。 ref: 技術顧問として半年間で感じた会社の成長 - ROUTE06 Tech Blog プロジェクト 1 - 運用方法 17
18. 新規メンバーのオンボーディングスピード向上 プルリクエストのレビューなどでの共有が容易に 「コンテキストやトレードオフの内容が勉強になる」 「数は多いが、必要な時に読めば良 いので気にならない」という声も ADR を書くことに対するメンバーのハードルが高いのは否めない プロジェクト 1 - 振り返り 18
19. 0→1・開発ツール・OSS・1 チームでフロントエンドだけでなく全領域を担当 DB スキーマファイルから ER 図を自動生成するツール(事業化に向けた開発も進行中) フルスタックエンジニア 5~7 人 プロジェクト 2: プロジェクトの特徴 19
21. ADR の数: 20(OSS として公開していない プロトタイプ版のプロダクトの ADR も含 む) ライブラリの選定理由 特定ロジックの実装方針 プロジェクト 2: 実際に書いた ADR 21
22. OSS なので、ADR もパブリックに公開しています。こちらも合わせてご覧ください！ https://liambx.com/docs/contributing/adr https://github.com/liam- hq/liam/tree/main/frontend/apps/docs/content/docs/contributing/adr プロジェクト 2: 実際に書いた ADR 22
23. ADR の数は控えめ スピードを優先し「特に懸念がなければ前プロジェクト踏襲」で進めた 0→1 の開発であり、変更が多いと予想されたため 大半のメンバーが前プロジェクト経験者であり、共通理解がすでにあった 新しいメンバーから「これってなんでこういうことになっているんですか」と聞かれたタイ ミングで ADR として書き直す プロジェクト 2: 運用方針 23
24. プロジェクト 1（商社向け SaaS） プロダクトの性質上、長期間保守が予想される 関わるメンバーが多く、共通理解を作るのが難しい状況 デファクトスタンダードなライブラリが決まっていない状況 → 詳細かつ多数の ADR は価値を生んだ プロジェクト 2（開発者向けツール） PMF 前の 0→1 の開発で、スクラップアンドビルドが求められていた 大半のメンバーが前プロジェクト経験者で、主要領域以外は前プロジェクトを踏襲 チームメンバーの共通理解が作りやすい状況 → 少数の ADR でも十分な価値を生んだ 2 つのプロジェクトの比較 24
25. チームが置かれた状況によって ADR の運用方法は変わる プロダクトのフェーズや性質・メンバーの人数・メンバーの経験など 目的は「理論的根拠に対する強固な共通理解を作る」であり、チームに最適な運用方法を模 索する 2 つのプロジェクトの比較: まとめ 25
26. 生成 AI 時代の ADR と技術選定 (妄想も含まれます) 26
27. (Google 翻訳)シニアエンジニアが Cursor や Copilot などの AI ツールを使っている様子を見ると、魔法のように見えます。彼らは数 分で機能全体をスキャフォールディングし、テストとドキュメントを完成させます。しかし、よく観察すると、重要なことに気付く でしょう。彼らは AI の提案をそのまま受け入れているのではなく、常に次のことを行っています。 生成されたコードをより小さく、焦点を絞ったモジュールにリファクタリングする AI が見逃したエッジケースの処理を追加する 型定義とインターフェースの強化 アーキテクチャ上の決定に疑問を抱く 包括的なエラー処理の追加 言い換えれば、彼らは長年かけて苦労して得たエンジニアリングの知恵を AI の出力を形作り、制限するために応用しているのです。 AI は彼らの実装を加速させていますが、彼らの専門知識こそがコードの保守性を維持しているのです。 若手エンジニアは、こうした重要なステップを見逃してしまうことがよくあります。AI の出力をすぐに受け入れてしまうため、私が 「トランプのカードハウス」と呼ぶコードができあがってしまいます。これは、完成しているように見えても、現実世界のプレッシ ャーで崩れてしまうコードです。 ref: The 70% problem: Hard truths about AI-assisted coding - Medium 生成 AI 時代の ADR - AI コーディングツールとプログラマ 27
28. Cline AI 時代のプログラマに必要なこと このように整理できるはず。 コンテキストを記述する能力 ドメインを記述する能力 AI の性能に対する直感 AI に対する直感以外は、適切なモジュール分割、境界づけられたコンテキストの抽出であり、ユビキタス言語の構 築、DDD であり、ドメインエキスパートとしての実装対象の抽象化能力ではないか。 結局自分は .clinerules に結構な量の指示を書いており、これを自分の能力に合わせて構築できるのがプログラミン グのドメインエキスパートとしての価値だと感じている。 ref: CLINE に全部賭けろ - Zenn 生成 AI 時代の ADR - AI コーディングツールとプログラマ 28
29. 開発スピードの向上のために AI にコードを書いてもらう機会は増加するが、まだ AI はジュ ニアエンジニアレベルの判断しかできず、セキュリティ・パフォーマンス・保守性などの問 題を解決するために人間の補助が必要 AI コーディングツールに暴走させず、適切な制約の中で高速に作業を進められるようにす るためには、プログラマのアーキテクティング能力は依然として重要になる 静的解析・自動テスト・型定義・モジュール分割・ドキュメンテーション 生成 AI 時代の ADR - AI コーディングツールとプログラマ 29
30. → 2025 年春としては、ADR はどんどん書くべきだと考える ADR は意思決定のスナップショットドキュメントであり、現在のソースコードからは読み 取れない「なぜ」を表す トレードオフや、選ばなかった選択肢とその理由 この情報は AI コーディングツールに「なぜこの実装方針にすべきか」を伝える効率的な手 段 コード生成だけでなく、 「今」のアーキテクチャドキュメントを生成 AI に品質高く書いても らうためにも重要 Cline の Memory Bank のセットアップにも一連の ADR を渡して整理してもらってい る 生成 AI 時代の ADR - 高品質なコンテキストとしての ADR 30
31. ADR はその価値は理解されやすいものの、実際に書くまでのハードルが高く導入されないことも多い しかしドキュメント化こそ生成 AI が得意な領域であり、生成 AI と対話しながら書くことでハードルは 下げられる よく使うプロンプトは以下で、あくまで自分の思考の整理と言語化に利用する 〇〇についてのADR を書きます。以下は私のメモで、あなたは以下のメモを整理し、深掘りをし、疑問点があれば私に質問してください。 テンプレートに従って記載してください。 ## 私のメモ - xxx - yyy ## ADR テンプレート ~~~ 今こそ ADR を運用し始めて欲しい 生成 AI 時代の ADR - ADR を書く敷居の低減 31
32. Appendix: ADR のオレオレベストプラクティス 32
33. GitHub リポジトリに配置することを推奨 PR のレビューフローに載せることができ、行単位でのレビューが可能 AI コーディングツールへの受け渡しが容易(@メンションでコンテキストに渡せる) ADR のベストプラクティス - 配置場所 33
34. Michael Nygard 氏のテンプレートが必要十分 architecture-decision-record/locales/en/templates/decision-record-template-by- michael-nygard/index.md - GitHub ステータスは Accepted と Rejected を中心に使う 提案中は PR が Open な状態 マージされたら Accepted ADR のベストプラクティス - フォーマット 34
35. ナンバリングより日付ベースを推奨 001-adr-title.md ではなく 2025-01-01-adr-title.md 並行での複数の意思決定が進んでいる場合、ナンバリングだとコンフリクトが起きや すかった 運用後から過去の意思決定を記載する場合も容易 ADR のベストプラクティス - フォーマット 35
36. 個人的には運用がある程度回ってから書く方針で良いと考えている 事前の検証だけでは運用上の課題に気づけないことが多く、課題を解決してから ADR を書 く 調査・PoC→ 本実装 → 少数メンバーで運用 →ADR にまとめる ADR のベストプラクティス - ADR を書くタイミング 36
37. 基本は上書きせず、新しい ADR を作成し意思決定を変更する 個人的には大筋を変えないのであれば細かい上書きはして良いと考える 大筋ではないが細かい問題が出てきてしまうのはよくある 実装詳細まで書かないなどのテクニックはあるものの... この問題を防ぐためにも、ADR を書くタイミングは運用がある程度回ってからが良い と考えている ADR のベストプラクティス - Approve 後の上書きについて 37
38. ご清聴ありがとうございました! 38