adr-reference

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）に以下を確認する:

1. 同コンポーネントの既存 ADR を確認: 同じコンポーネントに関する既存 ADR を Grep で検索し、矛盾する決定がないか確認する
2. 依存 ADR の前提確認: 依存 で参照する ADR の決定内容を Read で確認し、前提と矛盾しないか確認する
3. 矛盾を発見した場合: Supersede フローに従い、旧 ADR のステータスを更新する