Zenn
Closed6

Architectural Decision Records（ADR） 実践備忘録

Fuminori SakamotoFuminori Sakamoto

Architectural Decision Records または Architecture Decision Records（通称 ADR）を実践してみての備忘録諸々。
このスクラップ投稿時点では、既に実践してしばらく経った状態で、この備忘録はリアルタイムなメモではなく振り返りながら書いたもの。

Fuminori SakamotoFuminori Sakamoto

※ 参考文献: Design It!

目的や背景

  • Why にフォーカスしたドキュメントを残したい
  • 設計判断の共有・分析のハードルを下げたい
  • 現状のアーキテクチャに関するコンテキストを、その過程と結び付けて（第三者に）提供したい

ADRとは何なのか？

「アーキテクチャ上の設計判断と意思決定の履歴を、テキストベースの軽量なテンプレートを使用して記録するもの」

享受できるメリット

  • 設計判断をチームの責任において記録できる
  • 重要な設計判断をリポジトリに保存することで、コードに近い場所に置いておける
  • 他の生成物と組み合わせて、全体的な説明戦略を作成できる
  • 歴史を記録することで、設計の進化に関する展望を得られる
  • チーム全体を設計プロセスに巻き込める
  • ADRテンプレートを提供することで、チームメンバーのアーキテクチャ思考を訓練できる
  • 標準の開発発ツールと既存のピアレビューワークフローを使って、設計判断をピアレビューできる

引用集

TECHNOLOGY RADAR でadoptされた際（2018/05）の投稿より

  • 将来のチームメンバーのためにも、また外部からの監視のためにも、特定の設計上の決定を記録することが重要です
  • Lightweight Architecture Decision Recordsは、重要なアーキテクチャ上の決定事項を、その背景や結果とともに記録するための手法です
  • これらの詳細をwikiやWebサイトではなく、ソースコントロールに保存することをお勧めします。ほとんどのプロジェクトでは、この手法を使わない理由はないでしょう

Infrastructure as Code, 2nd Edition より

  • インフラストラクチャーのコードだけが必要なドキュメントであることはほとんどありません。ハイレベルなドキュメントは、コンテキストや戦略に役立ちます。システムの側面を理解する必要があるが、技術スタックを知らないステークホルダーがいるかもしれません。
  • このような他のタイプのドキュメントをコードとして管理したい場合もあります。多くのチームでは、ADR（Architecture Decision Records）をマークアップ言語で記述し、ソースコントロールで管理しています。
  • コードからアーキテクチャ図やパラメータリファレンスなどの有用な資料を自動的に生成することができます。これを変更管理パイプラインに組み込むことで、誰かがコードに変更を加えるたびにドキュメントを更新することができます。

The GitHub Blog「Why Write ADRs」 より

  • ADRは、新しいチームメイトがコードベースとそれが時間の経過とともにどのように進化してきたかを理解するために作業するときに、新しいチームメイトを支援するためのものです。
  • 決定したことについての自己発見、反省プロセス　ではありません
  • プルリクエストのタイトルと説明に書き込んだ内容を拡張することで、大規模なシステムでパッチまたは差分がどのように機能するかについて、チームメートに詳細情報を提供します。
  • 決定事項を書き留めておくことで、現在のチームメイトだけでなく、チームが成長していく過程で加わってくるメンバーにも伝えやすくなります。
  • プルリクエストを提出する前にADRを作成することで、プルリクエストをレビューするチームからより良いプルリクエストのレビューを得ることができます。
Fuminori SakamotoFuminori Sakamoto

疑問メモ

  • コードベース とは多くの場合GitHubを想定していると思われるが、複数のリポジトリに跨るような内容の場合はどのように残すのが良いか？
    • 当該リポジトリの範疇に収まる内容にして、関連リポジトリのADRにはリンクを記載する？
      • 更新発生時に複数リポジトリのADRを同時メンテするのは大変そうだが？
  • 「Pull Request のdescriptionにWHYを書く」でも良いのか？それともADRは別ファイル化すべきか？（その理由は？）
  • GitHub Wiki に書く、でも良いか？
  • IaC本にあった「コードからアーキテクチャ図やパラメータリファレンスなどの有用な資料を自動的に生成」する具体的な手段やツールがあったりするのか？
Fuminori SakamotoFuminori Sakamoto

何を書くのか？

  • 重要なアーキテクチャ上の設計判断とその判断の背景および影響
  • 1 ADR につき1つの設計判断を記述

設計判断 を文字起こしする際の指針/ヒント

  • その判断は、他のコンポーネントやチームに直接的な影響を与える
  • システムが一つ以上の品質特性にどう影響するかが、その判断によって良くも悪くも変わる
  • その判断は、ビジネス上または技術上の制約によってなされたものだ
  • その判断は、フレームワークや技術の選択のような、広範囲にわたる重大な影響を持つ
  • その判断は、チームの開発方法やデリバリー方法を根本的に変えるものだ

記述例

# タイトル（Title）
  ADR番号と説明的なタイトル

## コンテキスト（Context）
  判断がどんな状況で行われたかを説明

## 決定（Decision）
  行った判断の内容を説明

## ステータス（Status）
  下書き、提案済、承認済、廃止、非推奨

## 結果 / 影響（Consequences）
  決定がシステム、ステークホルダー、チームの状況をどのように変えるか？あるいは変えたか？を説明

参考事例

joelparkerhenderson/architecture-decision-record

  • architecture-decision-record/examples
    • 内容によってフォルダを分け、そのフォルダ配下に index.md というファイルを配置している
      • （ファイル名を README.md にしていないのは、何らかの意図があるのだろうか？）
  • こちら にその他テンプレ集が複数紹介されている

arachne-framework/architecture

Fuminori SakamotoFuminori Sakamoto

疑問メモ

  • ステータス という時間や状況次第で変化する項目を含んでおり、GitHubでADRを実践する場合はその変化の履歴まで見やすい形で残したければ（Wikiよりも）独立したファイルにするのがベターか？
    • 独立したファイルにすれば、履歴は残るし、それ自体をpull requestでレビューする事も出来る
    • 一方で「機能追加や修正の際のpull requestのdescription欄にADRっぽい事（特にWhy）を書く」という案との優劣判断が難しい
このスクラップは2021/06/23にクローズされました