create-adr

# ADR 作成スキル ## フロー 1. ADR対象かどうかを判定する（下記「判定基準」参照） 2. 対象外の場合：理由を説明し、それでも作成するか確認する 3. 情報収集：必要情報をユーザーから収集する（不足分のみ質問する） 4. 自動採番：`docs/adr/` の既存ファイルを確認し、最大番号+1を使用 5. ファイル作成：`docs/adr/NNN-slug.md`（テンプレート: `docs/adr/adr-template.md` を参照）。既定は軽量版（下記「軽量版で書く」参照）。書き始める前に `samples/docs/design/adr/`（ADR の手本。フル版と軽量版の書き分けが見られる）を Read する。`samples/` 自体は変更しない 6. 可視化：下記「可視化（必須）」に従い、表・図で構造を一目化する 7. 代替案の絞り込み：下記「代替案に何を載せるか（必須）」に従い、表に載せる案を決める 8. 一覧表を再生成：`npm run gen:adr-index` を実行し `docs/adr/adr-index.md` を更新する（表は手で編集しない） ## 軽量版で書く 軽量版から書き始める。決定が1つで、後から変えても安いなら、TL;DR・コンテキスト・トレードオフ・影響・参照は見出しごと省く。書いている途中で省いた節が必要だと分かったら、その時点で足す。 - **決定 / 採用理由 / 検討した代替案**：省けない - **TL;DR / コンテキスト / トレードオフ・影響 / 参照**：省いてよい なぜこうするか。全部埋めるのが既定だと、小さい決定は「ADR にするほどではない」と見送られ、どこにも記録が残らない。書式の重さが記録を失わせるなら、軽い側を既定にする。逆に代替案の表まで省くと、半年後に同じ案が出たとき却下理由を調べ直すことになり、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` の反論から自分で思いついただけの案は載せない。載せる価値があると考えるなら、ADR を書く前に人間へ提示して検討の対象にする（フローの「情報収集」で行う）。 3. **上限は3件。** 4件目が出てきたら、軸の切り方が粗い（複数の決定が1つの ADR に混ざっている）ことを疑い、ADR を分ける。 ## ADR判定基準 設計上の決定はすべて ADR に残す。重さは書式で調整する（対象から外さない）。 - **技術スタック・アーキテクチャパターン・インフラ・セキュリティアプローチの選択、その他あとから変えるのが高コストな決定**：フル版 - **それ以外の設計上の決定（あとから変えても安いもの）**：軽量版 次のものは ADR にしない。 | ADR にしないもの | 見分け方 | 代わりにどうするか | | ----------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------ | | 判断していないもの | 代替案が1つも書けない（選択肢が実質1つ） | 何も書かない | | 他に SSOT があるもの | コードの書き方（`.claude/rules/`）・判断基準（`docs/policy/`）・いまの構造（`docs/design/`）・設定値 | そちらに書く | | 既存 ADR と同じ軸の決定 | 既存 ADR の「決定の軸」への別の答えになっている | その ADR を更新するか supersede する | 判定が難しい場合は、対象外にせず軽量版で残す。 ## ファイル作成ルール - 保存先: `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`（置換先の番号）を書く ## 収集する情報 軽量版で省く節の情報は聞かない。必要な情報が不足している場合だけユーザーに質問する： | 項目 | 内容 | 軽量版 | | ------------ | ------------------------------------------------------ | ------ | | 決定内容 | 何を選択したか | 聞く | | 採用理由 | なぜこの選択をしたか | 聞く | | 代替案 | 決定の軸への別の答えのうち、対話に出た案と却下理由 | 聞く | | コンテキスト | 問題の背景、検討した選択肢 | 省く | | トレードオフ | 受け入れる制約・リスク、否定した選択肢（表で整理する） | 省く | | 影響 | この決定が与える影響 | 省く | | 参照 | 関連ドキュメント・実装ファイル（任意） | 省く |