ADR の基本

なぜ書くか

• 「なぜそうしたか」が忘れられない: 3ヶ月後の自分や新メンバーが「なぜRedisじゃなくてDynamoDB?」を追える
• 同じ議論の再発を防ぐ: 「過去に同じ検討をしてこういう理由で却下した」と参照できる
• 設計変更時の影響範囲が分かる: 関連ADRを辿ることで決定の連鎖が見える
• オンボーディングが楽: 新メンバーが ADR を読めば過去の判断が分かる

いつ書くか (判断基準)

書く対象 (例):

• 新規ライブラリ・フレームワーク採用
• DB選定・スキーマ設計の大きな変更
• 認証方式・認可モデルの選定
• 通信プロトコル選定 (REST / GraphQL / gRPC)
• アーキテクチャパターン選定 (モノリス / マイクロサービス)
• インフラ・クラウドサービス選定
• 重要なライブラリの破壊的アップグレード

書かない対象 (例):

• 細かい命名規則 (.cursor/rules/20-coding-style.mdc で十分)
• 個別関数の実装方針 (コードコメントで十分)
• 一時的な調査 (必要なら z_docs/scratch/ の個人メモで十分)

迷ったら書く。あとから「ADRにすべきだった」より「ADRがあって良かった」のほうが多い。

配置・命名

• ディレクトリ: docs/adr/
• ファイル名: NNNN-<slug>.md (NNNN は連番、4桁ゼロ埋め)
• 例: 0001-use-postgres.md / 0002-adopt-fastapi.md / 0003-replace-celery-with-sqs.md
• 索引: docs/adr/README.md に一覧 (ステータス・タイトル・リンク)

ADR の運用

ADR ステータス

• Proposed: 提案中、レビュー待ち
• Accepted: 採用決定、現在の方針
• Deprecated: 非推奨だが特に置き換えなし
• Superseded by ADR-NNNN: 別のADRに置き換えられた (古いほうも残す)

重要: ADR は 追記方式。既存ADRを書き換えるのではなく、新しいADRで上書き (Superseded) する。

docs/adr/template.md

# ADR-NNNN: <タイトル>

- Date: YYYY-MM-DD
- Status: Proposed | Accepted | Deprecated | Superseded by ADR-MMMM
- Deciders: [氏名 / チーム]
- Related: [関連ADR, Issue, PR]

## Context (背景)

なぜこの決定が必要なのか。
- 解決したい問題
- 制約 (技術的・組織的・予算的)
- 関係するステークホルダー

## Decision (決定)

何を決めたか。具体的に。
- 採用した選択肢
- 採用した理由 (Context との対応)

## Consequences (結果・影響)

### Positive (良い結果)
- 期待される効果
- 解決される問題

### Negative (悪い結果・トレードオフ)
- 受け入れるコスト
- 新たに発生する課題

### Neutral (中立、副次的な影響)
- 注意点
- 周辺への影響

## Alternatives Considered (検討した他案)

### Option A: <別案>
- 概要
- メリット
- デメリット
- 採用しなかった理由

### Option B: <別案>
- ...

## References (参考資料)

- [公式ドキュメント](URL)
- [比較記事](URL)
- 関連Issue: #123

ADRの書き出しプロンプト

まずドラフトを素早く起こしたいときは ADR生成ツール で Markdown 叩き台を作ってから、この章のテンプレートと照らして調整すると早い。

新規ADRを起票します。

【テーマ】
[例: Redis を使うべきか、別の選択肢があるか]

【現状】
[なぜ検討が必要になったか、関連するコンテキスト]

【作業】
docs/adr/ に新規ADRファイルを作成してください。
- 連番 NNNN は既存ADRの最大値+1
- ファイル名: NNNN-<slug>.md (slug は英小文字+ハイフン)
- フォーマットは docs/adr/template.md に従う
- Status は Proposed として作成 (レビュー後に Accepted に変更する想定)

検討した代替案を最低3つ挙げ、それぞれのメリット・デメリット・採用しなかった理由を書いてください。
私が後で判断するための材料として、推測ではなく検証可能な事実に基づいて書いてください。

ADRに昇格すべきかの判断

docs/<feature>/04_tech_decisions.md に書いた内容のうち、

• 機能を超えてプロジェクト全体に影響する
• 後から変更が困難 (DB変更、認証方式変更等)
• ステークホルダー間の議論があった

ものは ADRに昇格 (新規ADR起票 + 04_tech_decisions.md から docs/adr/NNNN-*.md へリンク)。

docs/adr/README.md の例

# Architecture Decision Records

| ADR | Title | Status | Date |
|---|---|---|---|
| [0001](./0001-use-postgres.md) | Use PostgreSQL as primary DB | Accepted | 2026-04-01 |
| [0002](./0002-adopt-fastapi.md) | Adopt FastAPI for backend | Accepted | 2026-04-05 |
| [0003](./0003-replace-celery-with-sqs.md) | Replace Celery with AWS SQS | Proposed | 2026-05-10 |
| [0004](./0004-tdd-as-team-standard.md) | TDD as team standard | Accepted | 2026-05-12 |

新規ADR起票時はこの表に追記すること。