ADR(Architecture Decision Record、設計上の決定を記録する文書)の書き方について、実務経験を踏まえた提言記事です。筆者はADRの経緯記述は実際にはあまり読み返されないと指摘し、Railsプロジェクトでの経験から、「なぜそう決めたか」という経緯を詳細に書くことは非現実的だと主張します。時間が経つと前提条件はすぐに古くなり、無意味になってしまうためです。
筆者が重視するのは、経緯ではなく「現在の決定」を常に最新の状態に保つことです。「経緯が古いのは無害ですが、決定が古いのは有害です」という言葉の通り、ADRのテンプレートは「決定(結論)」「現状(Single Source of Truth)」「経緯(一行のみ)」の3要素で十分だと提案しています。筆者は最後に「凝った履歴より、今日も正しい一行を」と締めています。
出典が伝えている要点
- 筆者は、ADRの経緯記述は実際にはあまり読み返されないと主張している
- 筆者は、ADRの前提条件は時間とともにすぐに古くなると主張している
- 筆者は、経緯が古くなることは無害だが、決定が古くなることは有害だと主張している
- 筆者は、ADRにおいて重要なのは経緯ではなく現在の決定を最新の状態に保つことだと主張している
- 筆者は、ADRのテンプレートとして「決定(結論)」「現状(Single Source of Truth)」「経緯(一行のみ)」の3要素を推奨している
- 筆者はRailsプロジェクトの実務経験を踏まえてこの主張をしている
原文より
経緯が古いのは無害ですが、決定が古いのは有害です。
凝った履歴より、今日も正しい一行を。
出典: zenn.dev