ストーリー

ADRのフォーマット

Michael Nygard形式

# ADR-NNN: タイトル

## ステータス
提案 / 承認済み / 非推奨 / 却下

## コンテキスト
なぜこの決定が必要になったか。背景、制約、前提条件を記述。

## 決定
何を決定したか。明確かつ具体的に記述。

## 根拠
なぜその決定をしたか。トレードオフの分析、比較検討の結果を記述。

## 検討した代替案
却下した選択肢とその理由。

## 影響
この決定がもたらす影響（ポジティブ・ネガティブ両方）。

ADR作成の原則

ADR作成の5原則:

  ① 1つのADRに1つの決定
    -- 複数の決定を混ぜない

  ② コンテキストを詳細に
    -- 半年後の自分（や新メンバー）が読んでも理解できるレベルで

  ③ 代替案を必ず記載
    -- 「検討した結果却下した」ことの記録が最も価値がある
    -- 将来同じ議論の繰り返しを防ぐ

  ④ イミュータブル
    -- ADRは変更しない。状況が変わったら新しいADRを作成し、
       古いADRを「非推奨」ステータスに更新

  ⑤ バージョン管理
    -- Gitリポジトリで管理。コードと同じPR/レビュープロセスを適用

NexPayのADR例

ADR-001: マイクロサービスアーキテクチャの採用

# ADR-001: マイクロサービスアーキテクチャの採用

## ステータス
承認済み (2026-01-10)

## コンテキスト
NexPayは決済、送金、投資の3つのドメインを持つフィンテックプラットフォームである。
以下の要件がある:
- 各ドメインの独立したデプロイとスケーリング
- PCI DSSスコープの最小化（カード情報を扱うサービスの分離）
- 20名以上の開発チームによる並行開発
- 99.99%の可用性（部分障害時の縮退運転）

## 決定
DDDの境界づけられたコンテキストに基づくマイクロサービスアーキテクチャを採用する。

## 根拠
1. PCI DSSスコープの分離: Payment + Tokenization Serviceのみが監査対象
2. チームの自律性: 各チームが担当サービスを独立にデプロイ可能
3. 障害分離: 投資サービスの障害が決済に影響しない設計
4. スケーリング: 決済サービスのみをピーク時に5倍にスケール可能

## 検討した代替案
- モノリス: チーム規模と独立デプロイの要件を満たせない
- モジュラーモノリス: デプロイの独立性が得られない。PCI DSSスコープが全体に
- サーバーレス: 決済のレイテンシ要件（コールドスタート問題）に不適

## 影響
+ チームの自律性と開発速度の向上
+ PCI DSSコンプライアンスコストの削減
- 分散システムの運用複雑性の増大（Istio, サービスメッシュが必要）
- サービス間通信の信頼性確保が必要（Circuit Breaker, Saga等）
- 運用チーム（SRE）の強化が必要

ADR-002: 決済サービスにイベントソーシングを採用

# ADR-002: 決済サービスにイベントソーシングを採用

## ステータス
承認済み (2026-01-12)

## コンテキスト
決済サービスには以下の要件がある:
- 完全な監査証跡（PCI DSS、資金決済法の要件）
- 任意の時点での残高再計算（障害復旧時）
- 決済の全ライフサイクルの追跡（承認→確定→返金）

## 決定
決済サービスにイベントソーシング + CQRSパターンを採用する。

## 根拠
1. 法的要件: すべての状態変更がイミュータブルなイベントとして記録される
2. 障害復旧: イベントの再生により任意時点の状態を復元可能
3. 分析基盤: イベントストリームをデータレイクに流すことで分析基盤を構築

## 検討した代替案
- CRUD + 監査テーブル: 実装は簡単だが、状態の復元が困難
- Change Data Capture: 既存DBの変更を検出するが、ビジネスイベントの意味が失われる

## 影響
+ 完全な監査証跡を自然に実現
+ イベント駆動アーキテクチャとの親和性
- 実装の複雑性増大（イベントストア、プロジェクション、スナップショット）
- スキーマ進化の管理が必要（Schema Registry導入）
- チームの学習コスト（イベントソーシングの経験者が少ない）

ADR-003: 認証基盤にAuth0を採用（Buy判断）

# ADR-003: 認証基盤にAuth0を採用

## ステータス
承認済み (2026-01-15)

## コンテキスト
NexPayのユーザー認証（ログイン、MFA、ソーシャルログイン）と
API認可（JWT、スコープベースアクセス制御）を実現する必要がある。

## 決定
認証基盤としてAuth0 (Enterprise Plan) を採用する（Buy判断）。

## 根拠
1. セキュリティ: 認証は専門ベンダーに任せることで、脆弱性リスクを低減
2. 機能充実: MFA、ソーシャルログイン、Adaptive MFA、Breached Password Detection
3. コンプライアンス: SOC 2 Type II、ISO 27001取得済み
4. 開発効率: SDK充実。実装期間2週間（内製の場合3ヶ月以上）
5. SLA: 99.99%の可用性保証

## 検討した代替案
- 内製: セキュリティリスクが高く、専門人材が必要。コアコンピタンスではない
- Cognito: AWSロックイン。カスタマイズ性が不足
- Keycloak (OSS): 運用負荷が高い。SLAの自己保証が必要

## 影響
+ 認証に関するセキュリティリスクの軽減
+ 開発期間の短縮（2週間 vs 3ヶ月）
- Auth0への依存（月額¥80万のランニングコスト）
- Auth0障害時の影響（ログイン不可）→ トークンキャッシュで軽減

追加ADR例（タイトルのみ）

ADR-004: サービス間通信にgRPCを採用
ADR-005: インフラ管理にTerraform + Terragruntを採用
ADR-006: Aurora Global Databaseによるマルチリージョン構成
ADR-007: 可観測性基盤にOpenTelemetry + Grafana Stackを採用

ADRの運用

ADRのライフサイクル

ADRのステータス遷移:

  提案 → 承認済み → （状況変化時）→ 非推奨 → 新ADRで置き換え

例:
  ADR-003: Auth0を採用 [承認済み]
  ↓ 2年後、Auth0の料金改定でコスト増大
  ADR-003: Auth0を採用 [非推奨 - ADR-015で置き換え]
  ADR-015: 認証基盤をKeycloakに移行 [承認済み]

レビュープロセス

ADRのレビュープロセ:

  1. 起案者がADRのPRを作成
  2. テックリード + 関連チームがレビュー（5営業日以内）
  3. コメント対応 → Approve
  4. マージ = 承認

レビュー時のチェックポイント:
  □ コンテキストは十分に記述されているか
  □ 代替案が検討されているか
  □ トレードオフが明確か
  □ 影響（ポジティブ・ネガティブ両方）が記載されているか

まとめ

チェックリスト

• ADRのフォーマットと5つの原則を理解した
• NexPayのADRを3つ以上作成できた
• 代替案とトレードオフを含む根拠を記述できた
• ADRのライフサイクルとレビュープロセスを理解した

次のステップへ

次は「レビュー準備とプレゼンテーション」に進みます。設計したアーキテクチャをステークホルダーにプレゼンテーションする準備をしましょう。

推定読了時間: 30分