/da-adr — 判断を、見つけてもらえる場所に書く

このスキルが書くのは ADR 1 本だけ。ソース・スキーマ・マイグレーション・設定は触らない。実装を始めず、判断の出どころの spec や計画も編集しない。

結論に加え、その結論を使える範囲と、条件が変わったときに確かめ直すことを残す。過去の選択を、後続の人が従い続ける要件にしない。

ツリーから置き場所を推すと、誰も読まないディレクトリに整った ADR ができる。ADR の置き場所はリポジトリごとの事実なので、spec_system と同じくプロファイルに置く。

実行条件

1 行でも満たさなければ即座に止まり、どの条件かを報告する。続けない。

3 つの条件。ADR に書くのは、難しい（妥当なエンジニアが逆を選びうる）、文脈なしでは驚く（コードを読んだ新規参加者が「なぜこうなのか」と聞く）、トレードオフがある（実際に何かを諦めた）判断である。1 つでも欠ければ change の design ドキュメントかコミットメッセージに書く。たいていの判断はどれかが欠ける。

ワークフロー上の位置

読むファイル

常に読む

条件つきで読む

「念のため」全部を読むことは禁止。

手順

Step 1. 置き場所を解決する（選ばない）

プロファイルから adr_system を読む。ADR がありそうに見えるからディレクトリを選ぶことはしない。ツリーは移行途中のことがあり、そうなると整ったファイルが誰も見ない実在の場所に黙って落ちる。

kind: colocated なら、ADR は支配するコードの隣、roots のいずれかの中に置く。選んだサブツリーと理由を書く。kind: directory なら唯一のルートの下に置く。

Step 2. 既存の ADR を探す

タイトルではなく対象で探す。同じ判断の ADR が別名であると記録が割れ、どちらの半分も単独では誤りでない。

rg -l "<the entity, table, endpoint or rule>" --glob 'ADR.*' --glob 'docs/**'
git log --oneline -20 -- '**/ADR.*'

この判断を扱うものがあれば、同じ判断の説明を整えるのか、判断自体を選び直すのかを区別する。説明の更新では、当時の根拠を後日の知識で上書きしない。判断を選び直す場合は、以前の判断と根拠を残し、置き換えた範囲・理由・新旧の関係を明示する（supersede）。ファイルを分けるかはリポジトリの規則に従い、食い違う判断を黙って並べない。

Step 3. 選び直せる判断の記録として書く

${CLAUDE_SKILL_DIR}/reference/final-design.md に従う。読み手、削る書き方、下書きを終える前の確認がある。da-spec と共有しているが、ADR では判断時点の根拠と、後日の確認・判断の置き換えを区別して残す。

そのうえで ${CLAUDE_SKILL_DIR}/reference/adr-shape.md に沿って並べる。見出しは既存の形に合わせながら、守るべき条件・優先したこと・前提にした仮定や見込みを区別し、採用時に未確認だったものを明記する。結論、比較した代替案、失うもの、適用範囲、再検討の引き金と確認事項をつなげ、変化を確認する担当と確認の機会も残す。未定なら未定と書き、担当や確認方法を補作しない。後日の実装確認や計測は、当時の判断理由とは分けて書く。

同ファイルの「業務全体と判断の前提」に従い、業務の目的・完了条件と今回の判断の範囲を前提や判断の節へ組み込む。資料にある情報は聞き直さず、未確認事項がどの判断を変えうるかと確認先を残す。判断を支える根拠が足りなければ、その判断を確定事項として補わず上流の検討へ戻す。

このスキル固有の規則が 1 つある。真剣に検討した代替案は、すべて却下した代替案として書く。却下案の無い ADR は判断ではなく説明である。案は、それを退けた判断の節の末尾（### N-k. 却下した代替案）に置き、「手に入るもの」「採らなかった理由」「勝つ条件」の 3 点で書く。採らなかった理由も本文の理由も、あるべき設計として何が正しいかを仕組みまで書き、同じ change の spec・design の決定を根拠にしない（spec は ADR から導かれるので、引くと理由が循環する）。書き方は adr-shape.md の「理由の書き方」と「却下した代替案」にある。まだ本番に出ていない判断は、同じファイルの「リリース前の ADR」に従い、開発中の変遷を書かない。

Step 4. すべての名前を裏付ける

バッククォートの識別子（ファイル、テーブル、カラム、クラス、フラグ）は、書く前に存在を確かめる。改名されたシンボルがあると、ADR は権威があるように読まれて誤る。読み手が探す羽目になる場所は path/file.ts:L42 で示す。

Step 5. 日本語の ADR なら表示を確かめる

CommonMark は、日本語の句点・読点の直後の ** を閉じない（right-flanking の規則を満たさず、アスタリスクがそのまま出る）。句読点は太字の外に出す。

根拠の扱い

• 直接確かめたことだけを報告する。
• 場所は path/to/file.ts:L42 で示す。
• 根拠が無いときは「確認できなかった」と書く。判断者が引き受けた未確認の前提は本文に明記し、AI が推定した理由は当時の根拠として扱わない。
• 事実と推論をはっきり分ける。
• 外部についての主張には URL を付ける。

出力

解決した場所に、既存の ADR と同じ形のファイルを 1 本。

そのうえで次の順で報告する。

1. 置き場所 —— どのプロファイルから解決したか。解決できなければ欠けているものと質問
2. 新規か更新か —— パス。更新なら既にあった内容
3. 3 つの条件をどう満たしたか —— 各 1 行
4. 未決のこと —— 引き受けた未確認の前提は本文に残す。判断が決まらない不足情報は質問し、結論や理由を補作しない

完了条件

• 置き場所はツリーの見た目ではなくプロファイルから来た
• 書く前に adr_system.rules を読んだ
• 同じ対象の既存 ADR を探し、更新か新規かを理由つきで書いた
• 却下した代替案は、それを退けた判断の節の末尾にあり、すべてに「手に入るもの」「採らなかった理由」「勝つ条件」がある
• adr-shape.md のチェックリストを通る。題が結論を述べ、問い・要約・節が 1 つの § 番号を共有する
• 条件・優先事項・仮定や見込みが区別され、結論を使える範囲が分かる
• 業務全体に対する今回の範囲が分かり、判断に影響する未確認事項と確認先が残っている
• 再検討の引き金に、先に確かめることと比較し直す選択肢があり、確認する担当・機会が分かる（未定なら明記した）
• 当時の根拠と後日の確認が分かれ、判断の置き換えがあれば新旧の関係を残した
• バッククォートの識別子はすべて存在を確かめた
• 解決した場所の外には何も書いておらず、実装も始めていない

次に

判断が属する change に /executing-plans を掛ける。ADR は残り続ける記録で、change は作業である。