mongolyyのブログ

開発(Javascript, Typescript, React, Next.js)や開発手法(スクラム, アジャイル)、勉強したことについて色々書ければと。

ADR(Architecture Decision Records)について考えてみた

開発プロセス

はじめに

こんにちはメーカーでソフトウェアエンジニアとして働いているモンゴルです。
前々から、外部のコーチから「ADR(Architecture Decision Records)いいでー」と教えてもらっていたのですが、忙しさを理由に、なかなか作れていませんでした。

しかし、来月からメンバーが加わるということで、これは「ADRを作るチャンス！」と強く感じましたので、今のうちに調べて、自分だったらこう作るなーというところを妄想しておきたいと思います。

参考にしたサイト

fintan.jp

cognitect.com

github.com

考えた内容

ADRに書くスコープ

  • 開発者 のみ に関することで共有すること
    • 開発者以外にも関わることは、他メンバーもわかるドキュメント共有ツールに書く
  • 複数箇所で出現すること
  • プロジェクト固有のこと

ディレクトリ構成

ADRを作成する際は、以下のディレクトリの関連するディレクトリ配下に配置する

- docs/
   └ adr/
      ├ 1_process/          # 開発プロセスについて
      ├ 2_architecture/     # アーキテクチャについて
      ├ 3_code/             # コードについて
      └ 4_ui/               # 画面、挙動について

メンバーそれぞれからADRが出てくることが予想されるので、出しやすくするために、ジャンルを分けてみました。

テンプレート

ファイル名はXXX.mdにします。
XXXの先頭はフォルダ名の1桁目になります。

# {題目}

(話し合いをしていれば) 
- 日付
  - 2021/08/24
- 参加者
  - A
  - B

## ステータス

## コンテキスト

## 決定事項

## 結果

それぞれの内容について

  • 題目
    • 内容を簡潔に
  • ステータス
    • もやみ提起/提案中/承認/見送り/廃止
      • もやみ提起は素案なし
      • 提案中は素案あり
      • 承認は必須と推奨という、強制力が異なるものに分けることも検討したが、やめる
      • もやみ提起/見送りというのは、私のプロジェクトでADRを出しやすくするためにステータスを足してみる
  • コンテキスト
    • この決定を必要とする理由や、どういった選択肢があるか書く
  • 決定事項
    • 実現方法
    • 採用する技術・設計思想
    • 決定に至った理由、至らなかった理由
  • 結果
    • ADRを適用した後の結果を記述

ADRが決まるプロセス

パターン①：問題提起型

  1. 誰かが気になったことを書く
  2. 後日、議論しながら更新
  3. 皆でレビュー

パターン②：提案型

  1. 誰かがこうした方がいいのではということを書く
  2. 後日、議論しながら更新
  3. 皆でレビュー

パターン②：事後登録型

  1. 気になったことについて議論が起きる
  2. 議論中、議論後に誰かが内容を記載して登録
  3. 皆でレビュー

おわりに

まだADR導入していないですが、自分の中で整理できたと思います。 早くチームに導入してみたいなと思いました。