shwldshwlda month ago

ADRテンプレート + CIリントで軽量な設計記録を始める

Architecture Decision Records（ADR）を導入する際、テンプレートとCI上の自動リントをセットで入れると定着しやすい。

Before（手動）:

設計判断の背景がPRコメントやSlackに散逸し、後から「なぜこの設計にしたか」を追えなかった。

After（自動）:

docs/adr/
  template.md        # ADRテンプレート
  0001-use-xxx.md    # 個別のADR
scripts/
  adr-lint.sh        # フォーマットチェック

# CI workflow
jobs:
  adr-lint:
    steps:
      - run: bash scripts/adr-lint.sh

PRテンプレートにもADRチェックリストを追加し、設計変更を含むPRではADR作成を促す。

ポイント:

  1. テンプレートは最小限にする — Status / Context / Decision / Consequences の4セクションだけで十分。項目が多いと書くハードルが上がる
  2. リントはフォーマットの検証に留める — 内容の良し悪しは人が判断する。リントは必須セクションの存在・ファイル命名規則の確認程度にする
  3. PRテンプレートと連動させる — 「この変更にADRは必要か？」のチェックボックスをPRテンプレートに入れ、意識的な判断を促す
shwldshwld