アーキテクチャ決定記録 は何をしますか？
コーディングセッション中に行われるアーキテクチャ上の決定をその場で記録します。決定がSlackスレッド、PRコメント、誰かの記憶の中だけに残るのではなく、コードと共に保管される構造化されたADRドキュメントを生成します。
いつアクティブにするか
- ユーザーが明示的に「この決定を記録して」または「ADRにして」と言った場合
- ユーザーが重要な選択肢（フレームワーク、ライブラリ、パターン、データベース、APIデザインなど）から選択している場合
- ユーザーが「私たちは...と決めた」または「XではなくYを選んだ理由は...」と言った場合
- ユーザーが「なぜXを選んだのか？」と質問した場合（既存のADRを読む）
- アーキテクチャ上のトレードオフが議論されている計画段階中
ADR形式
Michael Nygardが提案し、AI支援開発向けに適応された軽量ADR形式を使用します：
# 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/が存在しない場合、ディレクトリ、インデックステーブルのヘッダーがシードされたREADME.md（下記のADRインデックス形式を参照）、および手動使用のための空の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と統合テストのバランス |
| プロセス | ブランチ戦略、レビュープロセス、リリース頻度 |
他のスキルとの統合
- プランナーエージェント: プランナーがアーキテクチャの変更を提案した場合、ADRの作成を提案します
- コードレビューアーエージェント: 対応するADRなしにアーキテクチャ上の変更を導入するPRにフラグを立てます