アーキテクチャ決定記録

コーディングセッション中にアーキテクチャ決定をキャプチャします。決定が Slack スレッド、PR コメント、または誰かの記憶の中だけに存在するのではなく、このスキルは構造化されたADRドキュメントを生成し、コードと並存させます。

いつ有効化するか

• ユーザーが明確に「この決定をログに記録しましょう」または「これについて ADR を作成しましょう」と言った場合
• ユーザーが重要な代替案（フレームワーク、ライブラリ、パターン、データベース、API 設計）の間で選択をした場合
• ユーザーが「われわれは決定した...」または「X を Y の代わりに選んだ理由は...」と言った場合
• ユーザーが「なぜ X を選んだのか？」と尋ねた場合（既存の ADR を読む）
• アーキテクチャトレードオフについて議論する計画段階で

ADR フォーマット

Michael Nygard が提唱した軽量な ADR フォーマットを使用し、AI 支援開発向けに調整したものです:

# ADR-NNNN: [決定のタイトル]

**日付**: YYYY-MM-DD
**状態**: 提案中 | 受理済み | 非推奨 | ADR-NNNN に取って代わられた
**決定者**: [関係者]

## 背景

この決定または変更を促した、われわれが観察した問題は何か？

[現在の状況、制約、影響を受ける要因を 2～5 文で説明]

## 決定

われわれが提案しているまたは実行している変更は何か？

[決定を明確に 1～3 文で記述]

## 検討した代替案

### 代替案 1: [名前]
- **利点**: [メリット]
- **欠点**: [デメリット]
- **選ばなかった理由**: [却下された具体的な理由]

### 代替案 2: [名前]
- **利点**: [メリット]
- **欠点**: [デメリット]
- **選ばなかった理由**: [却下された具体的な理由]

## 影響

この変更により、何がより簡単または困難になるか？

### 積極的な影響
- [メリット 1]
- [メリット 2]

### 消極的な影響
- [トレードオフ 1]
- [トレードオフ 2]

### リスク
- [リスクと軽減策]

ワークフロー

新しい ADR をキャプチャする

決定の瞬間が検出されたら:

1. 初期化（初回のみ） — docs/adr/ が存在しない場合、ディレクトリを作成し、索引表ヘッダーを含む README.md（下記の ADR 索引フォーマットを参照）と手動使用用の空白テンプレートファイル template.md を作成する前に、ユーザーに確認を求めてください。明示的な同意なしにファイルを作成しないでください。
2. 決定の識別 — 実施されている核となるアーキテクチャ選択を抽出する
3. コンテキストの収集 — この決定を促した問題は何か？どのような制約が存在するか？
4. 代替案の記録 — どの他のオプションが検討されたか？なぜそれらが却下されたか？
5. 結果の記述 — トレードオフは何か？何がより簡単／困難になるか？
6. 番号の割り当て — docs/adr/ 内の既存 ADR をスキャンしてインクリメントする
7. 確認と書き込み — ユーザーに確認するため ADR ドラフトを表示します。明示的な承認後のみ docs/adr/NNNN-decision-title.md に書き込みます。ユーザーが拒否した場合、ドラフトを破棄し、ファイルを書き込まないでください。
8. 索引を更新 — docs/adr/README.md に追加する

既存の ADR を読む

ユーザーが「なぜ X を選んだのか？」と尋ねた場合:

1. docs/adr/ が存在するかチェック — 存在しない場合、「このプロジェクトでは ADR が見つかりません。アーキテクチャ決定のログ記録を開始しますか？」と返信
2. 存在する場合、docs/adr/README.md 索引をスキャンして関連エントリを探す
3. 一致する ADR ファイルを読み、コンテキストと決定セクションを提示する
4. 一致するものが見つからない場合、「その決定についての 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 を使用 | 受理済み | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | プライマリデータストアに MongoDB ではなく PostgreSQL を選択 | 受理済み | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | GraphQL ではなく REST API を選択 | 受理済み | 2026-02-01 |

決定検出シグナル

会話内でアーキテクチャ決定を示す以下のパターンに注意してください:

明示的シグナル

• 「X を選びましょう」
• 「Y の代わりに X を使うべきです」
• 「トレードオフは価値がある、なぜなら...」
• 「これを ADR として記録してください」

暗黙的シグナル（ADR を記録することを提案 — ユーザー確認なしで自動作成しないこと）

• 2 つのフレームワークまたはライブラリを比較して結論に至る
• データベーススキーマ設計決定を実施し、理由を記述する
• アーキテクチャパターン間で選択（モノリシック対マイクロサービス、REST 対 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 がこの決定に取って代わりました（常に代替品にリンク）

記録する価値のある決定カテゴリ

カテゴリ	例
技術的選択	フレームワーク、言語、データベース、クラウドプロバイダ
アーキテクチャパターン	モノリシック対マイクロサービス、イベント駆動、CQRS
API 設計	REST 対 GraphQL、バージョニング戦略、認証メカニズム
データモデリング	スキーマ設計、正規化の決定、キャッシング戦略
インフラストラクチャ	デプロイメントモデル、CI/CD パイプライン、監視スタック
セキュリティ	認証戦略、暗号化方法、キー管理
テスト	テストフレームワーク、カバレッジ目標、E2E 対統合テストのバランス
プロセス	ブランチング戦略、レビュープロセス、リリースペース

他のスキルとの統合

• プランニングエージェント: プランナーがアーキテクチャ変更を提案するときは、ADR の作成を提案してください
• コードレビューエージェント: アーキテクチャ変更を導入しているが対応する ADR がない PR にフラグを立ててください