設計判断記録（ADR）の作成

恒常的な設計決定を ADR（Architecture Decision Record）として記録します。

本スキルはオンデマンドです。 /define-feature → /create-ticket → /para-impl の定常フローに組み込まれた必須ステップではなく、恒常的な決定が発生したときに人間または上流スキルから明示的に呼ばれます。例外は機能仕様を削除する工程で、削除が不可逆なため promote モードによる昇格要否の判定が必須ステップになります。

本スキルが行わないこと: コミット・ブランチ操作・PR 作成・Issue 起票・既存 ADR の決定内容の書き換え（改訂は追記で行う。後述）。生成・編集したファイルは作業ツリーに残すところまでが責務で、以降は /commit と通常の PR フローに載せてください。

---

入力で動作切替

$ARGUMENTS

入力	モード	動作	出力
promote <機能仕様パス|ディレクトリ...>	昇格判定モード	退役予定の機能仕様を読み、ADR に昇格すべき決定が残っていないかを全件判定する	判定表（対象全件。要人間判定 を含む）＋ 昇格対象があれば ADR ファイル。昇格対象が0件なら ADR なし
それ以外（決定のテーマ、または空）	記録モード	1つの決定を ADR として記録する	ADR ファイル 1件、または既存 ADR への改訂追記。3条件を満たす候補が無ければ ADR なし

• promote の引数にディレクトリを渡した場合は、その直下の *.md を対象一覧に展開する（再帰はしない。サブディレクトリを含めたい場合は明示的に渡す）。パスは複数指定できる（ファイル・ディレクトリの混在可）。
• promote の引数が省略された場合は、対象が特定できないため推測せずユーザーに確認する。
• 記録モードで $ARGUMENTS が空の場合は、記録したい決定をユーザーに質問する。

出力契約: 「ADR なし」は正常な結果

両モードとも、ADR を1件も作らずに終了する分岐が存在する（記録モードは候補0件・3条件を満たす候補が無い・既存 ADR に既出のいずれか、昇格判定モードは昇格対象が0件の場合）。この分岐では:

• ADR パス・ステータスを出力しない。完了報告のそれらの項目は、ADR を作成・改訂した場合にのみ現れる条件付きの項目である。作っていないものを「新規作成した ADR」として報告しない。
• コミットを案内しない（作業ツリーに変更が無いため）。次のステップは、実際にやるべきこと（既存 ADR の確認・要人間判定の解消と再判定など）だけを書く。
• 代わりに、ADR を作らなかったことと、その理由（候補ごとに3条件のどれを満たさなかったか・委ね先、または既出の参照先）を必ず報告する。
• 報告の体裁を埋めるために基準を緩めて ADR を作らない。「作らなかった」という結論を、根拠つきで出せることがこのスキルの正しい振る舞いである。

「候補が0件だった」「候補はあったが3条件を満たさなかった」「既存 ADR に既出だった」はそれぞれ別の状態として書き分ける（順に、入力に決定が含まれていない／判定した結果／すでに記録がある）。

入力を読む工程の共通規律

両モードとも、判定の前に対象と参照先を読む工程がある（仕様ファイル・既存 ADR・関連 Issue/コード）。ここで次の2つを必ず守る:

1. 「読めなかった・判定できなかった」を「該当なし・0件」と同一視しない。 読み取りに失敗した対象は、成功して0件だった対象とは別の状態として保持し、報告に出す。失敗を0件に丸めると、下流の判定が「確認済み」に見えてしまう。
2. N 件を処理する工程の集約値は、件ごとの状態から導く。 内訳の合計が対象件数と一致すること（1件が複数理由に該当しても、件数は対象の集合として数える）。集約値だけを先に組み立てない。

---

共通規約（両モードで守る）

この節が ADR 規約の実行時の正本であり、各モードの手順書（references/）には複製しない。

何を ADR にするか（乱造防止の線引き）

ADR に書くのは「宣言元の Issue を読まなくても理解できる必要がある恒常的決定」だけである。個別機能の検討経緯は Issue に委ね、ADR へ持ち込まない。この線引きを外すと ADR が増えすぎて誰にも読まれなくなり、受け皿として機能しなくなる。

次の3条件をすべて満たすものだけを ADR にする（1つでも欠けたら書かない）:

1. 恒常性: 特定の機能・チケットが終わったあとも効き続け、今後の実装が従い続ける決定である。
2. 非自明性: 結果のコードとテストを読んだだけでは「なぜそうなっているか」を復元できない。
3. 選択性: 妥当な代替案が実在し、却下した理由を残さないと再燃・蒸し返しが繰り返される。

判定に使う1問（迷ったときの決め手）: 「この決定を知らない人・エージェントが、Issue を掘らずにコードだけを見て作業したとき、決定に反する実装をしうるか」。Yes なら ADR、No なら書かない。

ADR に書く	ADR に書かない（委ね先）
認証・認可モデルの選択とその適用範囲	個別機能の要件・受入基準（機能仕様 → Issue）
DB スキーマの方針（正規化方針・テナント分離方式・マイグレーション規律）	すでに守っている振る舞い（コードとテストが正）
エラー応答形式・API バージョニングなど契約の原則（個別エンドポイントの仕様ではない）	実装の内部設計・アルゴリズム選択（コードとテストが正）
モジュール依存の方向・レイヤ境界の規律	一度きりの移行・作業の実施記録（PR と git 履歴が正）
採用／不採用を決めた基盤技術・外部サービスとその理由	個別機能の検討経緯・トレードオフの議論（宣言元 Issue）
組織・法令・契約に由来する制約と、その適用方針	恒常的だが自明な事実（コードを読めば分かる構成）

• 迷ったら書かない。ADR にしなかった判断そのものは、Issue・PR 本文に残せば追跡できる。
• 既存 ADR の改訂で足りるなら新規作成しない（後述の「改訂」）。同じ問いに対する答えの更新を別ファイルに分けると、どれが現行かが分からなくなる。

置き場・命名・採番

• 置き場: 既定は docs/adr/。導入先に既存の置き場があればそれに従う — CLAUDE.md に置き場の記載があればそれを使い、無ければ docs/ 配下から adr / decisions / decision-records という名前のディレクトリを Glob で探し、見つかったものを採る。どちらも無ければ既定の docs/adr/ を採る（CLAUDE.md に記載が無いことは別パスの証拠でも、置き場を決められない理由でもない。記載が無いのが既定であり、そこで停止せず既定値へフォールバックする）。
  • 置き場の解決は各モードの最初に1回だけ行い、以降は同じ解決値を使う。本 SKILL・各モードの手順書・テンプレートで <ADR置き場> と書かれている箇所は、すべてこの解決値に置き換えて読み書きすること。採番の走査・ADR の書き出し先・ドキュメントマップの行・完了報告・退役 PR 用の判定表・テンプレートの保存先の説明まで、生成物のすべてが同じ解決値を指す（どこか1箇所でも docs/adr/ を固定で出力すると、別パスのプロジェクトで記録と実体が食い違う）。
• ファイル名: NNNN-slug.md。NNNN は4桁ゼロ埋めの連番、slug は決定内容を表すケバブケース（例: 0002-auth-model.md）。
• 採番: <ADR置き場> の中で NNNN- 形式のファイル名を列挙し、その最大値 + 1。欠番は埋めず、番号は再利用しない（過去の参照 ADR 0007 の指す先が変わらないようにするため）。
  • 対象ディレクトリが存在しない場合は 0001 から始める（ディレクトリはこのとき作成する）。
  • 「存在しない」と「存在するが一覧・読み取りに失敗する」を区別する。 後者では採番せず停止し、失敗理由を添えて報告する。読み取り失敗を「ADR 0件」と同一視すると 0001 から採り直し、既存 ADR を上書きしうる（既存の決定記録の消失は不可逆）。
  • 並列ブランチで同じ番号を採ってしまった場合は、後からマージする側が採り直す（既存 ADR の番号の意味を変えない）。
• ADR 以外の記録（実機検証記録・アーカイブ等）を同じディレクトリに置く場合は、NNNN- で始まらない名前にする（例: archive-2026-08-01-<slug>.md）。日付始まりの 2026-08-01-... は4桁数字＋ハイフンの形が連番と区別できず、採番の走査で誤って最大値として拾われるため使わない。

構成とステータス

ADR の本文は次の4節を必須とし、テンプレート（templates/adr.md）に従う: 背景 / 決定 / 検討した代替案 / 帰結。加えて冒頭にメタ情報（ステータス・日付・関連）を置く。

• 結論を先に読めることを優先する。見出しは決定の要約（結論が読み取れる短文）にし、経緯の長い再現は書かない。

• 該当しない項目は、空欄や「特になし」で埋めずに行ごと・セクションごと削除する（残った見出しは「ここに情報がある」と誤認させる）。

• ステータスの許容値は次の4種:

  値	意味
  Accepted	現行の決定（初版の既定値）。ADR を含む PR のマージが裁可にあたる
  Amended	同じ問いへの答えを改訂した（本文末尾に「改訂」節がある）
  Superseded by ADR NNNN	別 ADR に置き換えられた（本文は歴史的記録として残す）
  Rejected	検討したが採用しなかった（同じ提案の再燃を防ぐために残す）

改訂（既存の決定を覆すとき）

確定済み ADR の本文（背景・決定・代替案・帰結）は書き換えない。 過去に何を根拠に何を決めたかが失われると、ADR の価値そのものが失われるため。

状況	扱い
同じ問いに対する答えが変わった	元 ADR の末尾に ## 改訂（YYYY-MM-DD） 節を追記し、ステータスを Amended にする。冒頭のメタ情報に改訂日と要旨を1行足す
問い自体が変わった（前提・スコープが別物になった）	新しい ADR を作り、元 ADR のステータスを Superseded by ADR NNNN にする（元の本文は残す）
誤字・リンク切れ・表記ゆれの修正	そのまま修正してよい（決定内容に触れないため）

ドキュメントマップへの反映（節がある場合のみ）

現行の /init-project はドキュメントマップ節を生成しない。節が無いのが既定であり、欠落・不備として報告しない（完了報告の 表が無いため未追記 がその既定の状態を表す）。ADR への到達は節ではなく docs/adr/ の探索が担う。

そのプロジェクトに既にドキュメントマップ節があり、かつ初めて ADR を作成した場合のみ、CLAUDE.md の「ドキュメントマップ」に1行追加する（既に行があれば何もしない）:

| 設計判断記録 | <ADR置き場> | 整備済み |

• <ADR置き場> は解決値（既定 docs/adr/）に置き換えて出力する。別パスのプロジェクトで docs/adr/ と書かない。
• 表の列構成が異なるプロジェクトでは、その表の形式に合わせる。ドキュメントマップに相当する表が無い場合は追加せず、その旨を完了報告に含める（CLAUDE.md の構造を勝手に作り変えない）。
• ADR を1件も作らない場合はこの行を作らない（空の受け皿を先に用意すると、エージェントの Glob/Grep に露出するだけで中身が無い）。

---

モード別の参照ファイル

参照ファイルの読み出し（重要）: 参照ファイルは導入先プロジェクトではなくプラグイン配下にある。プラグイン配下は導入先プロジェクトの作業ディレクトリの外にあるため、Read ツールでの読み出しは利用側に allow 設定が無いと拒否される（headless 委譲では許可する相手がいないため、既定で読めない）。読み出しは allowlist 済みの配送経路claude-harness-run read-plugin-doc "<読む対象のプラグインルート相対パス>"（本スキルは参照ファイルを複数持つ。読む箇所で指定されたパスをそのまま渡すこと — 特定の1本に決め打ちしない）で行い、stdout に出た本文を使う。非0 終了は「読まなくてよかった」ではない — 本文を得られていないまま手順を推測して続行せず、stderr のメッセージを添えてその場で停止し報告すること（読めないまま完走すると、書式や停止条件だけが外れた成果物が「成功」に見える）。exit 0 でも終端マーカー === read-plugin-doc END ... complete === が無ければ本文は完結していない — MORE マーカーが出ていれば示された --from-line で続きを取得し、END も MORE も無ければ出力が切り詰められたとみなして同様に停止すること。BEGIN マーカーの root= が「Base directory for this skill」の親ツリー（<root>/skills/<スキル名> が Base directory）と一致しなければ、別バージョンの本文が届いている — ランチャーは同居する最大バージョンを選ぶため旧版 SKILL.md ＋ 新版参照ファイルの混成になりうるので、手順へ進まず同様に停止して報告すること。=== read-plugin-doc ... === の行と read-plugin-doc: で始まる行は配送の制御情報であり本文ではない（テンプレートを埋めて書き出す際に成果物へ含めない）。claude-harness-run: command not found の場合のみ Read ツールへフォールバックし、スキル起動時にコンテキストへ与えられる「Base directory for this skill」を起点に <base>/<読む対象のスキル相対パス> として解決する（Read も拒否された場合は同様に停止して報告し、ランチャー導入を案内すること）。

<!-- 正本: docs/plugin-path-conventions.md -->

モード判定後、下表の「参照ファイル」列のパスを前掲の配送経路で読み出し、その手順に従う（claude-harness-run read-plugin-doc "<下表のパス>"。選んだモードの行のパスを使うこと。Read 直読みは前掲の注記のとおりランチャー未導入時のフォールバックに限る）:

モード	参照ファイル（配送経路へ渡すパス）	手順
記録モード	skills/create-adr/references/record-mode.md	Step R1〜R5
昇格判定モード	skills/create-adr/references/promote-mode.md	Step P1〜P5

---

注意事項

• 機能仕様ドキュメントの作成は /define-feature の責務（要件・その機能のクリティカル設計決定はそちらに書く）。ADR に持ち込むのは、その機能が終わっても効き続ける決定だけ。
• GitHub Issue の作成は /create-ticket の責務。ADR は Issue の代わりではない。
• すでに守っている振る舞いはコードとテストが正。ADR に振る舞いの一覧を書かない。