architecture-decision-record

アーキテクチャ決定記録

ステップ 1：決定内容を確認する

ユーザーに質問します。

記録する必要があるアーキテクチャ上の決定は何ですか？以下を共有してください。

• 決定のタイトル（例：「イベントルーティングを SQS から EventBridge に切り替える」）
• コンテキスト — どのような問題を解決するのか、またはどのような変更を行うのか
• 検討した選択肢（少なくとも 2 つ）— または、代替案の提案を依頼してください

ユーザーがすでに決定内容を説明している場合は、そのまま次に進みます。

重要：コードベースがある場合は、ADR を実装の実態に即したものにするため、必ず最初にコードを分析してください。コードがない場合は、口頭での説明に基づいて進めますが、実装に関するセクションには「コードを確認してください」と記載します。

ステップ 2：現状を調査する

コードベースを分析し、現在の状態を把握します。

必ず以下を調査してください。

• 決定に関連する IaC（CDK、CloudFormation、Terraform）
• 決定を実装している、または決定の影響を受けるアプリケーションコード
• 設定ファイル、依存関係のマニフェスト、環境変数
• コードベースにすでに存在するパターンと規約
• 現在の動作を検証するテスト

決定のコンテキストについて、必ず以下を記録してください。

• 現在の実装：ファイルパスと行番号を示した、現在の実装内容
• 影響を受けるコード：各選択肢で変更が必要になるすべてのファイル
• 統合ポイント：各選択肢が満たす必要のあるインターフェース、API、契約
• 既存コードによる制約：選択肢を制限する言語、フレームワーク、パターン
• 依存関係：現在の実装に依存する他のサービスやコンポーネント

必ず以下を明示してください。

• 各選択肢で変更が必要なコード（定量化する：「選択肢 A は 3 ファイル、選択肢 B は 12 ファイルに影響」）
• 既存の依存関係による互換性の制約
• すでに確立されているパターンのうち、決定に従うべきもの（または、理由を明示して逸脱するもの）
• 変更がステートフルなリソースに影響する場合のデータ移行要件

ステップ 3：根拠に基づいて選択肢を評価する

各選択肢について、具体的な分析を示します。

実装工数 — T シャツサイズではなく、具体的に示します。

• 変更するファイル（一覧）
• 新たに導入する依存関係
• 必要な移行手順
• 選択肢間の推定所要時間の差（例：「移行の複雑さに基づくと、選択肢 A は約 2 週間、選択肢 B は約 6 週間です」）

WA の柱への影響 — 関連する柱のみを対象とし、具体的な理由を示します。

柱	選択肢 A	選択肢 B
{関連する柱}	{影響＋理由＋コードに基づく根拠}	{影響＋理由}

以下を使用します：✅ 良い影響 | ➖ 中立 | ⚠️ トレードオフ | ❌ 悪い影響

両方の選択肢で真に中立となる柱は省略してください。表を埋めるためだけに追加してはいけません。

中立でない評価については、必ず以下を示してください。

• コードの実態に基づき、その選択肢がこの影響をもたらす理由
• メリットやリスクの要因となる具体的な AWS サービス、パターン、またはコードパス
• 一時的なトレードオフ（移行時の負担）か、恒久的なもの（アーキテクチャ上の制約）か

運用への影響 — チームにどのような変更が生じるかを示します。

• 必要となるモニタリング／アラートの変更
• ランブックの更新
• オンコールへの影響
• デプロイ戦略の変更

---STOP--- チェックポイント：選択肢の分析が完了しました — 推奨案を作成する準備ができています

「{decision title}」について、{N} 個の選択肢を評価しました。各選択肢について、実装工数（影響を受けるファイル、移行手順）、WA の柱への影響、運用上の影響を比較しました。

トレードオフの特定、リスクの評価、推奨案を含む最終 ADR の作成に進んでもよろしいですか？

ユーザーが明示的に確認するまで、この時点から先に進んではいけません。

ステップ 4：トレードオフとリスクを明らかにする

推奨する選択肢について、次の点を必ず明示してください。

• 得られるもの — これが今回のワークロードにとって重要である理由を、根拠とともに示します（一般的なメリットではなく）
• 諦めるもの — 制約を踏まえ、それが許容できるかを率直に評価します
• 起こり得る問題 — 実装中または実装後に生じる具体的なリスクと、その緩和策を示します
• 可逆性 — 元に戻すのはどれほど難しいでしょうか。代替手段は何でしょうか。一方向にしか移行できないデータは何でしょうか。

却下した選択肢については、次の点を必ず説明してください。

• 主な却下理由（明確な一文で）
• どのような将来の条件になれば、より良い選択肢となるか（具体的なきっかけ）

ステップ 5：ADR を作成する

# ADR-{number}: {Decision Title}

## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-X}

## Date
{YYYY-MM-DD}

## Context

### Problem Statement
{What problem? Why now? What triggered this decision?}

### Current State
{What exists today — with file paths and code references}
- `{file:line}` — {what it does and why it's relevant}
- `{file:line}` — {what it does}

### Constraints
{Derived from codebase analysis — not assumptions}
- {constraint} — Evidence: `{file:line}`

### Decision Drivers
{Ordered by priority — what matters most}
1. {driver} — {why, grounded in business or code reality}
2. {driver} — {why}

## Decision
{One clear statement of what we're doing.}

## Options Evaluated

### Option 1: {name} ← Chosen
- **How it works**: {description}
- **Pros**: {benefits grounded in this codebase's reality}
- **Cons**: {drawbacks with honest assessment}
- **Files affected**: {list with paths}
- **Migration**: {what needs to happen to get from current state to this}
- **Effort**: {specific estimate with basis}

### Option 2: {name} — Rejected
- **How it works**: {description}
- **Pros**: {benefits}
- **Cons**: {primary reason for rejection}
- **Files affected**: {list}
- **Effort**: {estimate}
- **Would choose this if**: {specific future condition}

## Well-Architected Impact

| Pillar | Impact | Evidence |
|--------|--------|----------|
| {pillar} | {✅/⚠️/❌} | {specific reasoning tied to code/architecture} |
{Only pillars with non-neutral impact}

## Trade-offs

### What We Gain
- {benefit} — matters because {evidence from this workload}

### What We Accept
- {drawback} — acceptable because {justification}

### Risks
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| {specific risk} | {Low/Med/High} | {what breaks} | {concrete action} |

## Implementation

### Migration Path
1. {step} — affects `{file}`
2. {step} — affects `{file}`
3. {step} — verify with {test/metric}

### Rollback Plan
{How to undo if this goes wrong — specific steps, not "revert the change"}

### Verification
- {How to confirm the decision is working as expected}
- {Metric or test that validates success}

## Review Triggers
{Specific, measurable conditions — not "if things change"}
- {metric} exceeds {threshold} (e.g., "p99 latency > 500ms")
- {event} occurs (e.g., "team grows beyond 8 engineers")
- {time} passes (e.g., "re-evaluate after 6 months of production data")

ステップ 6：既存の ADR を改訂する

ユーザーから ADR の改訂または更新を求められた場合：

必ず次のことを行ってください。

• 既存の ADR ファイルを読む
• ADR の作成以降、コードベースに何が変わったかを分析する（git log、ファイル差分）
• 決定が現在も妥当か、またはレビューのきっかけとなる条件に該当したかを判断する
• 以前の ADR を置き換える場合は、古い ADR を参照し、何が変わったかを説明する新しい ADR を作成する

ステップ 7：次のステップを提案する

ADR を作成した後、次のように提案してください。

次のことを行いましょうか。

• 選択した案の実装コードを生成する
• 移行スクリプト、または段階的な PR 計画を作成する
• 新しいアーキテクチャを検証するテストを作成する
• 依存する決定について、フォローアップ ADR を作成する
• 既存の ADR に定められたレビューのきっかけとなる条件に該当しているか確認する

調整のガイダンス

• ADR は意思決定の記録であり、売り込み資料ではありません。受け入れにくいものも含め、実際のトレードオフを記録してください。
• コードの根拠が意思決定を裏付けます。「影響するファイルが 3 つ」は「工数が少ない」よりも有用です。
• 具体的な閾値を設けたレビューのきっかけがあれば、6 か月後にも ADR が役立ちます。
• コードがない場合でも ADR には価値がありますが、実装に関する項目は検証が必要であると明記してください。
• 移行経路は ADR の中で最も実行に移しやすいセクションです。誰かが手順に沿って作業できるほど具体的に記述してください。
• 可逆性の記録は重要です。元に戻せない決定ほど、より多くの選択肢を分析してください。
• WA の柱の表に無理に項目を追加しないでください。実質的で、自明ではない影響がある柱だけを含めてください。