ADR 作成スキル

フロー

1. ADR対象かどうかを判定する（adr-policy を Read し、その判定手順を上から当てる）
2. 「作らない」判定の場合：理由を説明し、それでも作成するか確認する。作らないなら、ポリシーの記録先（その仕組みの本文・コミットの決定記録・決定した Issue）に書く
3. 情報収集：必要情報をユーザーから収集する（不足分のみ質問する）
4. 自動採番：削除済みを含む git 履歴上の最大番号+1を使用（調べ方は「採番の調べ方」を参照）。利用先はテンプレートと git 履歴を共有するため、利用先の最初の ADR 番号はテンプレートの最大番号の次から始まる（意図した結果）
5. ファイル作成：docs/adr/NNN-slug.md（テンプレート: docs/adr/adr-template.md を参照）。既定は軽量版（下記「軽量版で書く」参照）。書き始める前に samples/docs/adr/（ADR の手本。フル版と軽量版の書き分けが見られる）を Read する。samples/ 自体は変更しない
6. 可視化：下記「可視化（必須）」に従い、表・図で構造を一目化する
7. 代替案の絞り込み：下記「代替案に何を載せるか（必須）」に従い、表に載せる案を決める
8. 一覧表を再生成：npm run gen:adr-index を実行し docs/adr/adr-index.md を更新する（表は手で編集しない）

軽量版で書く

軽量版から書き始める。決定が1つなら、TL;DR・コンテキスト・トレードオフ・影響・参照は見出しごと省く。書いている途中で省いた節が必要だと分かったら、その時点で足す。

• 決定 / 採用理由 / 検討した代替案：省けない
• TL;DR / コンテキスト / トレードオフ・影響 / 参照：省いてよい

なぜこうするか。ADR に残すのは判定を通った決定だけなので、書式の重さで書き渋ってよいものは1件も無い。軽い側を既定にすれば、書式を理由に着手が止まらない。逆に代替案の表まで省くと、半年後に同じ案が出たとき却下理由を調べ直すことになり、ADR を書いた意味が消える。だからこの3節は省けない。

可視化（必須）

ADR も他ドキュメント同様、可視化ファーストで書く（docs/policy/documentation-policy.md「可視化されていないドキュメントは怠慢である」）。散文で構造を書かない。書いた節にだけ適用する（省いた節に図表を足さない）。

• 検討した代替案 → 比較表（案／内容／却下理由）。2項目でも表にする。
• トレードオフ・影響 → 表（受け入れる制約・リスク／影響範囲／緩和策）。
• コンテキスト／決定 → フロー・順序依存・状態遷移・前後（旧→新）比較があれば図にする。図は /design-doc-mermaid で作る（自前で Mermaid を書かない）。
• 逆変換テスト：表・箇条書きに戻しても文章を読まずに構造を掴めるなら図にしない（一直線 A→B→C など）。図にしないと決めたら、戻す先（表・箇条書き）で実際に書く。そう判断した理由はユーザーへの回答に書き、ADR 本文には残さない。

代替案に何を載せるか（必須）

代替案は「別セッションでの蒸し返しを防ぐ」ための記録である。検討していない案が却下済みとして並ぶと、記録が事実でなくなる。次の3つを守る。

1. 決定の軸を1文で書き、その軸への別の答えだけを並べる。 軸とは「この ADR が何を選ぶ判断か」（例：「dev へいつ deploy するか」）。軸への答えになっていないもの——別の論点への対処・緩和策・実装手段の違い——は載せない。
2. 人間との対話に出てきた案だけを載せる。 実装中や /devil の反論から自分で思いついた案は載せない。その案が決定の軸（上記1の軸）への答えになっているなら、ADR を書く前に必ず人間へ提示して検討の対象にする（フローの「情報収集」で行う）。軸への答えになっていない案は提示しない。
3. 上限は3件。 4件目が出てきたら、軸の切り方が粗い（複数の決定が1つの ADR に混ざっている）ことを疑い、ADR を分ける。

採番の調べ方

削除済みの番号を再利用すると、その番号を参照している古い Issue・コミットが別の決定を指すことになるため、現存するファイルの最大番号ではなく、git 履歴上（削除済みを含む）の最大番号+1 を使う。

git log --all --pretty=format: --name-only | grep -E '^docs/adr/[0-9]{3}-' | sed -E 's#docs/adr/([0-9]{3})-.*#\1#' | sort -n | tail -1 | awk '{printf "%03d\n", $1+1}'

出力された番号が次の採番。

ファイル作成ルール

• 保存先: docs/adr/NNN-slug.md
  • NNN: ゼロ埋め3桁（例: 007）
  • slug: タイトルから生成した英語スラッグ（例: single-stack）
• テンプレート: docs/adr/adr-template.md を参照すること
• status / date は本文ではなく frontmatter に書く（一覧表 adr-index.md はここから機械生成される）
• status は必ず proposed にする（許容値: proposed / accepted / rejected / deprecated / superseded）
• date: 今日の日付（YYYY-MM-DD）
• 既存 ADR を superseded にする場合は、その ADR の frontmatter に supersededBy: NNN（置換先の番号）を書く

収集する情報

軽量版で省く節の情報は聞かない。必要な情報が不足している場合だけユーザーに質問する：

項目	内容	軽量版
決定内容	何を選択したか	聞く
採用理由	なぜこの選択をしたか	聞く
代替案	決定の軸への別の答えのうち、対話に出た案と却下理由	聞く
コンテキスト	問題の背景、検討した選択肢	省く
トレードオフ	受け入れる制約・リスク、否定した選択肢（表で整理する）	省く
影響	この決定が与える影響	省く
参照	関連ドキュメント・実装ファイル（任意）	省く