create-adr

# ADR 作成スキル ## フロー 1. ADR対象かどうかを判定する（[adr-policy](../../../docs/policy/adr-policy.md) を 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** を使う。 ```bash 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`（置換先の番号）を書く ## 収集する情報 軽量版で省く節の情報は聞かない。必要な情報が不足している場合だけユーザーに質問する： | 項目 | 内容 | 軽量版 | | ------------ | ------------------------------------------------------ | ------ | | 決定内容 | 何を選択したか | 聞く | | 採用理由 | なぜこの選択をしたか | 聞く | | 代替案 | 決定の軸への別の答えのうち、対話に出た案と却下理由 | 聞く | | コンテキスト | 問題の背景、検討した選択肢 | 省く | | トレードオフ | 受け入れる制約・リスク、否定した選択肢（表で整理する） | 省く | | 影響 | この決定が与える影響 | 省く | | 参照 | 関連ドキュメント・実装ファイル（任意） | 省く |