アーキテクチャ決定記録 (ADR) は何をしますか？
コーディングセッション中に行われたアーキテクチャ上の決定を記録します。決定がSlackのスレッドやPRのコメント、誰かの記憶の中にしか存在しないのではなく、このスキルは構造化されたADRドキュメントを生成し、コードと共に管理します。
いつ有効化するか
- ユーザーが明示的に「この決定を記録して」や「ADRにして」と言った場合
- ユーザーが重要な選択肢（フレームワーク、ライブラリ、パターン、データベース、API設計）の中から選択した場合
- ユーザーが「〜に決めた」や「XではなくYを選んだ理由は〜」と言った場合
- ユーザーが「なぜXを選んだのか」と尋ねた場合（既存のADRを読む）
- 計画フェーズでアーキテクチャ上のトレードオフについて議論している場合
ADRの形式
Michael Nygardが提案した軽量ADR形式を、AI支援開発向けに適応したものです：
# ADR-NNNN: [決定タイトル]
**日付**: YYYY-MM-DD
**ステータス**: proposed | accepted | deprecated | superseded by ADR-NNNN
**決定者**: [関与した人]
## コンテキスト
この決定や変更の動機となっている問題は何ですか？
[状況、制約、影響する力を2〜5文で記述]
## 決定
提案および/または実行する変更は何ですか？
[決定を明確に1〜3文で記述]
## 検討した代替案
### 代替案1: [名前]
- **メリット**: [利点]
- **デメリット**: [欠点]
- **採用しなかった理由**: [却下した具体的な理由]
### 代替案2: [名前]
- **メリット**: [利点]
- **デメリット**: [欠点]
- **採用しなかった理由**: [却下した具体的な理由]
## 結果
この変更により、何が容易になり、何が困難になりますか？
### 肯定的な影響
- [利点1]
- [利点2]
### 否定的な影響
- [トレードオフ1]
- [トレードオフ2]
### リスク
- [リスクとその軽減策]
ワークフロー
新しいADRの記録
決定の瞬間が検出された場合：
- 初期化（初回のみ） —
docs/adr/が存在しない場合、ユーザーに確認を求めてからディレクトリ、インデックステーブルヘッダー（下記ADRインデックス形式参照）が記されたREADME.md、および手動使用のための空のtemplate.mdを作成します。明示的な同意なしにファイルを作成しないでください。 - 決定の特定 — 行われている中核的なアーキテクチャ上の選択を抽出します
- コンテキストの収集 — どのような問題がきっかけとなったか？どのような制約があるか？
- 代替案の文書化 — 他にどのような選択肢が検討されたか？なぜ却下されたか？
- 結果の記述 — トレードオフは何か？何が容易になり、何が困難になるか？
- 番号の割り当て —
docs/adr/内の既存のADRを確認し、番号をインクリメントします - 確認と書き込み — ドラフトのADRをユーザーに提示してレビューを求めます。明示的な承認があった場合のみ
docs/adr/NNNN-decision-title.mdに書き込みます。ユーザーが拒否した場合、ファイルを作成せずにドラフトを破棄します。 - インデックスの更新 —
docs/adr/README.mdに追記します
既存のADRの読み取り
ユーザーが「なぜXを選んだのか」と尋ねた場合：
docs/adr/が存在するか確認 — 存在しない場合、「このプロジェクトにはADRが見つかりません。アーキテクチャ決定の記録を開始しますか？」と応答します。- 存在する場合、
docs/adr/README.mdインデックスをスキャンして該当するエントリを探します - 一致するADRファイルを読み込み、「コンテキスト」と「決定」のセクションを提示します
- 一致するものが見つからない場合、「その決定に関するADRは見つかりませんでした。今すぐ記録しますか？」と応答します。
ADRディレクトリ構造
docs/
└── adr/
├── README.md ← 全ADRのインデックス
├── 0001-use-nextjs.md
├── 0002-postgres-over-mongo.md
├── 0003-rest-over-graphql.md
└── template.md ← 手動使用のための空のテンプレート
ADRインデックス形式
# アーキテクチャ決定記録
| ADR | タイトル | ステータス | 日付 |
|-----|---------|----------|------|
| [0001](0001-use-nextjs.md) | フロントエンドフレームワークとしてNext.jsを使用 | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | プライマリデータストアとしてMongoDBではなくPostgreSQL | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | GraphQLではなくREST API | accepted | 2026-02-01 |
決定検出のシグナル
会話の中でアーキテクチャ上の決定を示す以下のパターンに注意してください：
明示的なシグナル
- 「Xにしよう」
- 「YではなくXを使うべき」
- 「トレードオフに見合う価値があるのは〜だから」
- 「これをADRとして記録して」
暗黙的なシグナル（ADRの記録を提案 — ユーザーの確認なしに自動生成しないでください）
- 2つのフレームワークやライブラリを比較し、結論に達する
- データベーススキーマ設計の選択を理由と共に行う
- アーキテクチャパターン（モノリス vs マイクロサービス、REST vs GraphQL）を選択する
- 認証/認可戦略を決定する
- 代替案を評価した上でデプロイメントインフラを選択する
優れたADRの条件
推奨事項
- 具体的に — 「ORMを使う」ではなく「Prisma ORMを使う」
- なぜを記録する — 何を選んだかよりも、その根拠が重要
- 却下した代替案を含める — 将来の開発者は何が検討されたかを知る必要がある
- 結果を正直に述べる — すべての決定にはトレードオフがある
- 簡潔に保つ — ADRは2分で読めるようにする
- 現在形を使う — 「Xを使う予定」ではなく「Xを使う」
避けるべきこと
- 些細な決定を記録しない — 変数名の付け方やフォーマットの選択にADRは不要
- 長文を書かない — コンテキストセクションが10行を超える場合は長すぎる
- 代替案を省略しない — 「ただ選んだだけ」は有効な根拠ではない
- 遡って記録する際にマークを付けない — 過去の決定を記録する場合は、元の日付を記載する
- ADRを古いまま放置しない — 置き換えられた決定は、その代替を参照する
ADRのライフサイクル
proposed → accepted → [deprecated | superseded by ADR-NNNN]
- proposed: 決定は議論中であり、まだ確定していない
- accepted: 決定は有効であり、遵守されている
- deprecated: 決定はもはや関連しない（例：機能が削除された）
- superseded: 新しいADRがこれを置き換える（常に代替をリンクする）
記録する価値のある決定の分類
| カテゴリ | 例 |
|---|---|
| 技術選択 | フレームワーク、言語、データベース、クラウドプロバイダー |
| アーキテクチャパターン | モノリス vs マイクロサービス、イベント駆動、CQRS |
| API設計 | REST vs GraphQL、バージョニング戦略、認証メカニズム |
| データモデリング | スキーマ設計、正規化の判断、キャッシュ戦略 |
| インフラストラクチャ | デプロイメントモデル、CI/CDパイプライン、監視スタック |
| セキュリティ | 認証戦略、暗号化アプローチ、シークレット管理 |
| テスト | テストフレームワーク、カバレッジ目標、E2E vs 統合テストのバランス |
| プロセス | ブランチ戦略、レビュープロセス、リリースサイクル |
他のスキルとの連携
- プランナーエージェント: プランナーがアーキテクチャの変更を提案した場合、ADRの作成を提案する
- コードレビューエージェント: 対応するADRなしにアーキテクチャ上の変更を導入するPRにフラグを立てる