| name | adr |
| description | 「設計判断を記録して」「ADRを作成して」「アーキテクチャ決定を記録して」などの依頼、 または「ADR」「設計判断記録」「アーキテクチャ決定記録」「設計の経緯」「なぜこの設計にしたか」 というキーワードが含まれる場合にこのスキルを使用する。 Architecture Decision Records (ADR) を作成・管理し、設計判断のコンテキスト・根拠・影響を記録する。 引数は省略可能: /adr <判断タイトル or 指示>
|
| argument-hint | <判断タイトル or 指示> |
| allowed-tools | Read, Glob, Grep, Bash(git *), Write(output/**), Agent, WebSearch, WebFetch |
| context | fork |
ADR — Architecture Decision Records（設計判断記録）
アーキテクチャ上の重要な判断を Nygard 形式 で記録・追跡するスキル。
「なぜこの設計にしたか」「どんな代替案を検討したか」「どんなトレードオフがあるか」を
将来の開発者（人間・AI 問わず）が理解できる形で残す。
既存スキルとの棲み分け:
/architecture: システム全体の構造設計文書を生成 → 設計そのもの/adr（本スキル）: 個々の設計判断の「経緯と根拠」を記録 → 判断の記録/plan: 実装計画のタスク分解 → 実行計画
前提条件
| 参照ファイル | 用途 |
|---|
project-config.md §4 | アーキテクチャ基本方針 |
docs/architecture.md | 現行のアーキテクチャ構成 |
output/design/ | /architecture スキルの出力（あれば） |
基本姿勢
- 判断の根拠を必ず明文化する — 「なんとなく」「一般的だから」は禁止。具体的な理由を記述する
- 代替案を必ず検討する — 最低2案を比較し、不採用理由を明示する
- 将来の読み手を意識する — コンテキストを知らない開発者が読んでも判断の妥当性を評価できる詳細さ
- 既存ADRとの整合性を保つ — 矛盾する判断はSupersededで明示的に更新する
- 判断に迷う場合のみユーザーに選択肢を提示する
使い方
/adr # 対話的に判断内容を確認して ADR を作成
/adr 認証方式をJWTからセッションに変更 # タイトル指定で ADR を作成
/adr --list # 既存 ADR の一覧表示
/adr --update ADR_003 # 既存 ADR のステータス更新
出力先
- ADR ファイル:
output/design/ADR_NNN_<title>.md
- ADR インデックス:
output/design/ADR_INDEX.md
他スキルとの連携
| 前工程 | 本スキル | 後工程 |
|---|
/architecture /plan（大きな設計判断が発生した時） | /adr | （記録が成果物 — 後工程なし） |
ワークフロー
Step 1: 判断の特定
以下のいずれかに該当する場合、ADR を作成する:
| 判断カテゴリ | 例 |
|---|
| 技術選定 | フレームワーク、ライブラリ、データベースの選択 |
| アーキテクチャパターン | レイヤー構成、API設計方式、状態管理方式 |
| 品質特性のトレードオフ | パフォーマンス vs 保守性、一貫性 vs 可用性 |
| 規約の策定 | 命名規則、ディレクトリ構成、エラーハンドリング方針 |
| 既存設計の変更 | 既存アーキテクチャの方針転換 |
Step 2: コンテキスト調査
サブエージェントで並行調査:
- 現状分析: 既存コードベースの関連部分を Grep/Read で確認
- 制約の特定:
project-config.md の制約事項を確認
- 先行ADR確認:
output/design/ADR_INDEX.md で関連する過去の判断を確認
Step 3: 代替案の評価
最低2つの代替案を検討し、それぞれについて:
- メリット: この選択肢の利点（具体的に）
- デメリット: この選択肢の欠点（具体的に）
- 不採用理由（選ばなかった案のみ）: なぜこの案を選ばなかったか
Step 4: ADR 作成
以下のテンプレートに従って記述:
# ADR-NNN: [判断タイトル]
## ステータス
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
## コンテキスト
[この判断が必要になった背景・状況・課題を記述]
## 判断
[選択した方針を明確に1文で記述]
[判断の詳細な説明]
## 検討した代替案
### 代替案 A: [案の名前]
- **メリット**: ...
- **デメリット**: ...
- **不採用理由**: ...
### 代替案 B: [案の名前]
- **メリット**: ...
- **デメリット**: ...
- **不採用理由**: ...
## 影響
### ポジティブな影響
- ...
### ネガティブな影響・リスク
- ...
### 関連する判断
- [ADR-XXX](ADR_XXX_title.md): [関連の説明]
## 参考
- [参考資料へのリンクや文献]
Step 5: インデックス更新
output/design/ADR_INDEX.md に新しいエントリを追加:
# Architecture Decision Records
| # | タイトル | ステータス | 日付 |
|---|---------|-----------|------|
| ADR-001 | [タイトル](ADR_001_title.md) | Accepted | YYYY-MM-DD |
| ADR-002 | [タイトル](ADR_002_title.md) | Proposed | YYYY-MM-DD |
ADR ライフサイクル
Proposed → Accepted → (Deprecated | Superseded by ADR-XXX)
| ステータス | 意味 |
|---|
| Proposed | 提案中。レビュー待ち |
| Accepted | 承認済み。現行の方針 |
| Deprecated | 非推奨。もはや適用しない |
| Superseded | 後続の ADR に置き換えられた |
ステータス変更時は、変更理由と日付をADR本文に追記する。
出力契約
| セクション | 必須 | 制約 |
|---|
| ステータス | ✅ | Proposed / Accepted / Deprecated / Superseded |
| コンテキスト | ✅ | 背景・課題が第三者に伝わる詳細さ |
| 判断 | ✅ | 1文で明確に。詳細は続けて記述 |
| 代替案 | ✅ | 最低2案。各案にメリット・デメリット |
| 影響 | ✅ | ポジティブ・ネガティブ両面 |
| インデックス更新 | ✅ | ADR_INDEX.md に追加 |
PASS条件: 上表の必須列が全て✅で埋まっている / 代替案が最低2案かつ各案にメリット・デメリット併記 / 判断が1文で曖昧さなく記述されている。1つでも欠けたら提出前に自己修正する。
禁止事項
- 代替案の検討なしに判断を記録すること
- 「なんとなく」「一般的だから」等の曖昧な根拠
- 既存 ADR との矛盾を放置すること（Superseded で明示的に更新する）
--no-verify によるフック迂回--force によるプッシュ
