ADRを使用する

コンテキスト

本プロジェクトではアーキテクチャの決定、構築、改善を行うため、以下の点でADRが必要になる。

  • アーキテクチャの意思決定のプロセスに透明性と規律を与えるため
  • アーキテクチャの意思決定が一方的に決定されることを防ぐため
  • 以前のアーキテクチャの意思決定が効果的であったか評価するため
  • 周囲の状況の変化に合わせて再度検討する必要があるのかを判断するため
  • 新規にアサインされたメンバに対してアーキテクチャの意思決定の記録を提示するため

 

ADRの詳しい情報は以下を参照

 

決定事項

アーキテクチャに関する決定をすべてADRによってドキュメントし、決定内容を記録する。手順は以下。

  1. 提案内容をドキュメント化する。作成時はステータスが「提案中」。提案はADRを作った人または作るプロセスにかかわった人が行う。
  2. 関係者で内容を話し合う。話し合う内容に合わせてドキュメントを更新。
  3. 関係者でドキュメントを「受理」または、「廃止」にする合意をとる。合意に至った過程も合わせて記述。
  4. 「受理」された場合、決定事項に合わせてソースコードを変更する。
  5. 「廃止」された場合、決定事項の内容をソースコードに反映しない。
  6. 再検討する場合、新規にADRを作成し、古いADRを参照する。そのため、ADRは一切破棄しない。

ADRは以下の内容で管理し、更新に合わせて対象のリポジトリに含めソースコードと同様Gitで管理する。

  • 書式
    • Mark Down ファイル
  • 配置場所
    • 対象リポジトリ内の doc/adr ディレクトリ
  • ファイル名
    • adr-<３桁の数字>-<タイトル>
    • ３桁の数字は連番で一意

 

ADRの対象は「ソフトウェアの複数箇所に関係する内容」かつ「プロジェクト固有の意思が入った内容」に限る。

ADRは原則、以下の内容に沿って記述する

  • タイトル
    • ADRのタイトル -「ADR : 」から始め、内容を簡潔に表現
  • コンテキスト
    • この決定を必要とする理由
    • 取り巻く状況・技術・社会的背景
    • 選択肢
  • 決定事項
    • 実現方法
    • 採用する技術・設計思想
    • 決定に至った理由
    • 決定に至らなかった理由
  • ステータス
    • ADRの状態
    • 下の表のラベルのいずれか
  • 結果
    • ADRを適用した後の結果を記述

 

ラベル 内容
提案中 同意がなされていない状態
受理 同意がなされている状態
廃止 変更あるいは取り消しされている状態

ステータス

受理

結果