| name | adr-reference |
| description | This skill should be used when the user asks about "ADR template", "ADRテンプレート", "ADRの書き方", "ステータスの定義", "Supersedeフロー", "ADR運用ルール", "adr-reference", or when creating/updating ADRs to ensure consistent formatting and structure. |
| version | 0.1.0 |
adr-reference
ADR（Architecture Decision Record）の運用ルール・テンプレート・表記規約をまとめたリファレンス skill。create-adr / adr-ship スキルから参照される。
ADR と reference.md の役割分担
| ドキュメント | 役割 | 更新タイミング |
|---|
ADR (docs/adr/) | 意思決定の「なぜ」を記録する履歴ログ | 意思決定時に作成、以後は原則追記のみ |
docs/reference.md | dotfiles の「今の全体像」を示すスナップショット | 実装が変わるたびに最新化 |
- ADR に「現状の設計」を書きすぎない。設計の全体像は reference.md に書く
- reference.md に「変更理由」を書かない。理由は ADR に書く
ADR テンプレート
# ADR-NNN: タイトル
## ステータス
（Draft / Spike中 / 採用済み / 廃止（ADR-YYY で置換） / 部分廃止（ADR-YYY で一部変更） / 却下）
## 関連 ADR
- 依存: ADR-XXX（〜を前提）
- 関連: ADR-XXX（〜と同じ領域）
（関連がない場合はセクションごと省略）
## コンテキスト
...
## 設計案
### 案A: 〜（採用）
### 案B: 〜（却下）
（単一案の場合は見出しなしで記述）
### 変更が必要なファイル
| ファイル | リポジトリ | 変更内容 |
## 受け入れ条件
→ [issues.md](../issues.md)（ADR-NNN セクション）
設計案セクションの構造ルール
- 独立した選択肢:
### 案A: 〜 / ### 案B: 〜 の H3 見出しで分離する
- 1つの設計内の構成要素: 箇条書きで記述する（見出し分離しない）
- 採用/却下ラベル: 各案の見出しに
（採用） / （却下） を必ず付与する
- 単一案: 代替案がない場合は案の見出しなしで記述してよい
ステータス定義と遷移
| ステータス | 意味 |
|---|
Draft | 検討中。設計案が確定していない |
Spike中 | Draft から派生。設計確定前に検証実装が必要な状態。spike/NNN-description ブランチで作業中 |
Spike完了 | 検証が完了し、知見を ADR に記録済み。設計判断の記録として保持。adr-ship 対象外 |
採用済み | 有効な意思決定。実装済みまたは実装予定 |
廃止（ADR-YYY で置換） | 完全に上書きされた。新しい決定は ADR-YYY を参照 |
部分廃止（ADR-YYY で一部変更） | 一部の決定が上書きされた。残りは引き続き有効 |
却下 | 検討したが採用しなかった |
遷移ルール
Draft → 採用済み: 実装完了時（adr-ship の Step 5）Draft → 却下: 検討の結果、採用しないと決定した場合Draft → Spike中: 設計確定前に検証が必要と判断した場合Spike中 → Spike完了: 知見まとめ完了後（adr-ship は使わない）Spike中 → 却下: 検証の結果、採用しないと決定した場合採用済み → 廃止（ADR-YYY で置換）: 新 ADR が既存の決定を完全に上書きする場合採用済み → 部分廃止（ADR-YYY で一部変更）: 新 ADR が一部の決定のみ上書きする場合
Spike 完了後に設計を確定させる場合は、create-adr で新 ADR を作成し、関連 ADR に Spike ADR を記載する。
Supersede フロー（双方向リンク）
ADR の決定を変更する場合、新旧両方の ADR を更新する。
新 ADR 側
## コンテキスト に「ADR-XXX の決定を変更する」と明記する## 関連 ADR に 依存: ADR-XXX を記載する
旧 ADR 側（完全置換）
## ステータス を 廃止（ADR-YYY で置換） に更新する- ステータスの下に変更された決定の要約を注記する
旧 ADR 側（部分上書き）
## ステータス を 部分廃止（ADR-YYY で一部変更） に更新する- ステータスの下に以下を明記する:
- 変更された決定（ADR-YYY で上書き）
- 引き続き有効な決定
関連 ADR フィールド
| 種別 | 意味 | 例 |
|---|
依存 | この ADR が前提とする ADR | ADR-022 は ADR-023 のネスト構成を前提 |
関連 | 同じ領域の ADR（依存はないが文脈が共通） | ADR-021 と ADR-022 は SSH 関連 |
- 関連がない場合は
## 関連 ADR セクション自体を省略する
- 双方向である必要はない（A が B に依存しても、B に A を記載する必要はない）
矛盾チェックの指針
ADR 作成時（create-adr）に以下を確認する:
- 同コンポーネントの既存 ADR を確認: 同じコンポーネントに関する既存 ADR を Grep で検索し、矛盾する決定がないか確認する
- 依存 ADR の前提確認:
依存 で参照する ADR の決定内容を Read で確認し、前提と矛盾しないか確認する
- 矛盾を発見した場合: Supersede フローに従い、旧 ADR のステータスを更新する
