Architecture Decision Records に記述する内容のメモ

ADR(Architecture Decision Records: アーキテクチャディシジョンレコード) とは

テキストベースの軽量なテンプレートを使用して、アーキテクチャ上の設計判断を記録するもの。 設計判断を記録し履歴を残すことで、現在の実装に至った理由とその過程を結びつけて提供できる。

記述内容のテンプレート例

１つのADR には、１つの設計判断を記述する。 内容は短く保ち、1~2ページくらいに収まるようにする。

タイトル

整理番号と説明的なタイトル

ステータス

ADR の状態(下書き、提案済み、承認済み、廃止、非推奨など)

コンテキスト

判断がどんな状況で行われたかの説明(事実ベース)

内容

行った判断の内容説明

影響

判断がシステム、ステークホルダー、チームの状況をどのように変える or 変えたかの説明

運用について

記載するかどうかの判断基準のヒント

• 影響範囲が直接的または広範囲なもの
• 開発進行に影響を与えるもの
• ビジネス上または技術上の制約
• 品質特性に影響を与えるもの

更新

• 判断が置き換えられたり、変更されたりしたときは、古いレコードへの参照を記述する
• 運用した結果、判明した影響があれば、「影響」のところに追記する

感想

• もしPR(Pull Request) ベースで「ステータス」を管理するなら
  • PR の性質上、下記は重複するので省いて良いかもしれない
    • 下書き -> Draft PR などの作業中
    • 提案済み -> PR のレビュー依頼
    • 承認済み -> PR をマージされた場合
  • 取り扱うのは下記のみで良いかもしれない
    • 有効
    • 廃止
    • 非推奨

参考文献

• Design It! p. 302-305