What to describe as ADR and what not to describe

[takaokouji]

What to describe as ADR and what not to describe

• Status: accepted
• Deciders: takaokouji
• Date: 2023-01-02T10:10:41:40+0900

Sorry, this is written in Japanese.

なにをADRとして記述して、なにを記述しないのか

ADRを記述することにしたのはいいのですが、すべての意思決定をADRとして記述するのは現実的ではありません。

そこで、なにを記述して、なにを記述しないのかを決めます。

判断基準や制限

• 続けられること
• スモウルビーは余暇をつかって開発しているため、作業時間の全体に限りがあること

選択肢

• 10分で書けそうなものだけADRに記述する
• 1時間で書けそうなものだけADRに記述する
• 意思決定のすべてにADRを記述する

決定

採用: 10分で書けそうなものだけADRに記述する

• 続けられるのを優先した。
• 10分で書けるもの、または10分で書ける程度のメモ書きを残すことにする
• 書き慣れてくると、10分で書ける内容が洗練されてくることを期待したい
• ADRのブランチやコミットメッセージは以下に決めた
  • ブランチ名: adr-%ファイル名から0001などの番号と拡張子を取り除いたもの%
    • 例: adr-what-to-describe-as-adr
  • コミットメッセージ: docs: adr %ファイル名から0001などの番号と拡張子を取り除いたもの% [skip ci]
    • 末尾の [skip ci] は必須
  • PRのタイトルもコミットメッセージと同じものにして、CIをスキップすること

各選択肢の良い点と悪い点

10分で書けそうなものだけADRに記述する

• + 簡単に書けることが前提なので続けられそう
• - 時間がかかりそうなものは中途半端な内容になったり、そもそもADRを残さなかったりする

1時間で書けそうなものだけADRに記述する

• + 10分で書けるものよりは、記録されている内容が増える
• - 手間がかかる
• - 面倒なので続かなくなる

意思決定のすべてにADRを記述する

• + 将来、なぜこうしたのか？を自分が知ることができる
• + なぜこうしたのかを他人が知ることができる
• - 手間がかかる
• - 面倒なので続かなくなる