ADR（Architecture Decision Record）について

システムアーキテクチャ

2022年10月10日 作成2022年10月10日 更新

Architecture Decision Record

    概要

    ADR（Architecture Decision Record）について調べた。

    ADRとは

    2011年にMichael Nygardによって紹介されたアーキテクチャに関する決定事項を記録したドキュメントのこと。 cf. cognitect.com - DOCUMENTING ARCHITECTURE DECISIONS

    フォーマット

    Michael Nygardは提案するフォーマットは次の通り。 cf. cognitect.com - DOCUMENTING ARCHITECTURE DECISIONS

    • タイトル
    • コンテキスト
      • 文脈。どういうシーンにおける決定なのか。
    • 決定
      • 決定事項は1つのADRにつき1つが推奨
    • ステータス
      • 提案、承認、非推奨など
    • 結果
      • 決定事項を適用した後にどういう状態になるか、結果のコンテキストについての説明

    ドキュメントは1~2ページ程度の読みやすい長さにする。

    ADRを採用する利点

    • アーキテクチャに関する設計判断についてキャッチアップしやすくなる
    • 明記された決定事項に関する議論頻度の減少
    • チーム内外におけるアーキテクチャの透明性への貢献

    ADRを採用するかどうかの判断

    • チームで繰り返し議論を行うような内容であるか？
    • チームで意思決定した設計について決定事項であるか？
    • ソフトウェア全体に影響がある決定事項であるか？

    などアーキテクチャの何かしらの判断・決定をする際はADRを書く機会がある。

    所感

    • ソフトウェアアーキテクチャの基礎では、
    • ADRを導入しようと思った際は、ADRの導入についてのADRをまずは書いてみるのが良さそう
    • Design Docsと少し雰囲気が違って、ADRの管理はリポジトリでソースコードとともに管理されるのが好まれる雰囲気を感じた
    • ADRを書くか書かないかの判断基準はシンプルにするのが良いと思った
      • チームで議論し、決定したことについては全て書く、など
    • ADRの検索性
      • 運用上ADRを検索したいときにちゃんと検索しやすい工夫があると良いのかもしれない（数が多くなるのであれば）
      • カテゴライズ、タグなど工夫したほうが良さそう

    参考

    関連書籍

    Xにシェアする Facebookにシェアする はてなにシェアする