Architecture Decision Records

重要な技術的決定の背景と根拠を記録する Architecture Decision Records (ADR) を作成、管理、保守するための包括的なパターン。

このスキルを使うべき場合

• 重要なアーキテクチャ決定を下す場合
• 技術選択を文書化する場合
• 設計上のトレードオフを記録する場合
• 新しいチームメンバーのオンボーディング
• 過去の決定を見直す場合
• 意思決定プロセスを確立する場合

コア概念

1. ADR とは何か？

Architecture Decision Record は以下を記録します：

• Context（文脈）: なぜ決定が必要だったのか
• Decision（決定）: 何を決定したか
• Consequences（結果）: その結果どうなるか

2. ADR を書くべき時

ADR を書く	ADR をスキップする
新しいフレームワークの採用	マイナーバージョン更新
データベース技術の選択	バグ修正
API 設計パターン	実装詳細
セキュリティアーキテクチャ	ルーチンメンテナンス
統合パターン	設定変更

3. ADR ライフサイクル

Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected

テンプレート

テンプレート 1: 標準 ADR (MADR フォーマット)

# ADR-0001: PostgreSQL をプライマリデータベースとして使用

## Status

Accepted

## Context

新しい e-commerce プラットフォーム用のプライマリデータベースを選択する必要があります。
このシステムは以下を扱います：

- 約 10,000 の同時ユーザー
- 階層カテゴリを持つ複雑な製品カタログ
- 注文と支払いのためのトランザクション処理
- 製品の全文検索
- ストアロケータ用の地理空間クエリ

チームは MySQL、PostgreSQL、MongoDB の経験を持っています。金融トランザクションには ACID
コンプライアンスが必要です。

## Decision Drivers

- **ACID コンプライアンスが必須** - 支払い処理用
- **複雑なクエリをサポートが必須** - レポート用
- **全文検索をサポートすべき** - インフラ複雑度を削減するため
- **優れた JSON サポートをすべき** - 柔軟な製品属性用
- **チームの習熟度** - オンボーディング時間を削減

## Considered Options

### Option 1: PostgreSQL

- **Pro**: ACID コンプライアント、優れた JSON サポート (JSONB)、
  組み込み全文検索、PostGIS 地理空間機能、チームが経験あり
- **Con**: MySQL より若干複雑なレプリケーションセットアップ

### Option 2: MySQL

- **Pro**: チームが非常に習熟、シンプルなレプリケーション、大規模コミュニティ
- **Con**: 弱い JSON サポート、組み込み全文検索なし (Elasticsearch が必要)、
  拡張機能なしの地理空間対応なし

### Option 3: MongoDB

- **Pro**: 柔軟なスキーマ、ネイティブ JSON、水平スケーリング
- **Con**: マルチドキュメントトランザクション用 ACID なし (決定当時)、
  チームの経験が限定的、スキーマ設計の規律が必須

## Decision

プライマリデータベースとして **PostgreSQL 15** を使用します。

## Rationale

PostgreSQL は以下のベストバランスを提供します：

1. **ACID コンプライアンス** - e-commerce トランザクションに不可欠
2. **組み込み機能** (全文検索、JSONB、PostGIS) - インフラ複雑度を削減
3. **チームの習熟度** - SQL データベースの学習曲線を削減
4. **成熟したエコシステム** - 優れたツーリングとコミュニティサポート

レプリケーション複雑度の増加は、追加サービス (別途 Elasticsearch 不要) の削減に
よって十分に相殺されます。

## Consequences

### Positive

- 単一データベースでトランザクション、検索、地理空間クエリに対応
- 運用複雑度の軽減 (管理するサービスが少ない)
- 金融データのための強い一貫性保証
- チームが既存の SQL 専門知識を活かせる

### Negative

- PostgreSQL 固有の機能 (JSONB、全文検索構文) の習得が必要
- 垂直スケーリング限界が早期の読み取りレプリカ導入を要求する可能性
- 一部チームメンバーが PostgreSQL 固有トレーニングが必要

### Risks

- 全文検索が専用検索エンジンほど良好にスケールしない可能性
- 軽減策: 必要に応じて Elasticsearch 追加を想定して設計

## Implementation Notes

- 柔軟な製品属性には JSONB を使用
- PgBouncer でコネクションプーリングを実装
- 読み取りレプリカ用のストリーミングレプリケーションを設定
- ファジー検索用に pg_trgm 拡張機能を使用

## Related Decisions

- ADR-0002: キャッシング戦略 (Redis) - データベース選択を補完
- ADR-0005: 検索アーキテクチャ - Elasticsearch が必要な場合は置き換え可能

## References

- [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html)
- [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)
- Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md`

テンプレート 2: 軽量 ADR

# ADR-0012: フロントエンド開発に TypeScript を採用

**Status**: Accepted
**Date**: 2024-01-15
**Deciders**: @alice, @bob, @charlie

## Context

React コードベースが 50 以上のコンポーネントに成長し、プロップ型のミスマッチと
未定義エラーに関連するバグ報告が増加しています。PropTypes はランタイムのみの
チェックを提供します。

## Decision

すべての新しいフロントエンドコードに TypeScript を採用します。既存コードは段階的に
移行します。

## Consequences

**Good**: コンパイル時に型エラーをキャッチ、IDE サポートの向上、自己説明的なコード。

**Bad**: チームの学習曲線、初期速度低下、ビルド複雑度増加。

**Mitigations**: TypeScript トレーニングセッション、`allowJs: true` により段階的採用を許可。

テンプレート 3: Y-Statement フォーマット

# ADR-0015: API ゲートウェイの選択

**マイクロサービスアーキテクチャを構築する** という文脈において、
**集中管理された API 管理、認証、レート制限の必要性** に直面し、
**AWS API Gateway とカスタム Nginx ソリューションに対して** Kong Gateway **を決定した**
ため、**ベンダーロックインの回避、プラグイン拡張性、Lua に対するチーム習熟度** を実現
する一方で、**Kong インフラストラクチャを自分たちで管理する必要がある** ことを受け入れます。

テンプレート 4: 廃止のための ADR

# ADR-0020: MongoDB を非推奨にして PostgreSQL を採用

## Status

Accepted (ADR-0003 を置き換え)

## Context

ADR-0003 (2021) はスキーマ柔軟性ニーズのため MongoDB をユーザープロファイルストレージに
選択しました。その後：

- MongoDB のマルチドキュメントトランザクションは当社のユースケースで問題のままです
- スキーマが安定し、滅多に変更されなくなりました
- 他のサービスから PostgreSQL の専門知識を獲得しました
- 2 つのデータベースの保守は運用負担が増します

## Decision

MongoDB を非推奨にし、ユーザープロファイルを PostgreSQL に移行します。

## Migration Plan

1. **Phase 1** (週 1-2): PostgreSQL スキーマ作成、デュアルライト有効化
2. **Phase 2** (週 3-4): 過去データをバックフィル、一貫性を検証
3. **Phase 3** (週 5): PostgreSQL への読み取りを切り替え、監視
4. **Phase 4** (週 6): MongoDB への書き込みを削除、廃止

## Consequences

### Positive

- 単一のデータベース技術により運用複雑度を削減
- ユーザーデータの ACID トランザクション
- チームが PostgreSQL 専門知識に集中可能

### Negative

- 移行作業 (~4 週間)
- 移行中のデータ問題リスク
- スキーマ柔軟性の喪失

## Lessons Learned

ADR-0003 から学んだ教訓：

- スキーマ柔軟性の利点は過大評価されました
- 複数データベースの運用コストは過小評価されました
- 技術決定には長期的な保守性を考慮してください

テンプレート 5: Request for Comments (RFC) スタイル

# RFC-0025: 注文管理に Event Sourcing を採用

## Summary

監査可能性を向上させ、時系列クエリを有効にし、ビジネス分析をサポートするために、
注文管理ドメインに Event Sourcing パターンの採用を提案します。

## Motivation

現在の課題：

1. 監査要件は完全な注文履歴が必要
2. 「時刻 X での注文状態は？」というクエリは不可能
3. 分析チームはリアルタイムダッシュボード用のイベントストリームが必要
4. 顧客サポート用の注文状態再構築は手動

## Detailed Design

### Event Store

OrderCreated { orderId, customerId, items[], timestamp } OrderItemAdded { orderId, item, timestamp } OrderItemRemoved { orderId, itemId, timestamp } PaymentReceived { orderId, amount, paymentId, timestamp } OrderShipped { orderId, trackingNumber, timestamp }

### Projections

- **CurrentOrderState**: クエリ用の物理化ビュー
- **OrderHistory**: 監査用の完全なタイムライン
- **DailyOrderMetrics**: 分析用集約

### Technology

- Event Store: EventStoreDB (目的特化、プロジェクション処理)
- 検討代替案: Kafka + カスタムプロジェクションサービス

## Drawbacks

- チームの学習曲線
- CRUD より増加した複雑度
- イベント設計を慎重に (保存後は不変)
- ストレージ増加 (イベントは決して削除されない)

## Alternatives

1. **Audit tables**: よりシンプルだが時系列クエリは不可能
2. **CDC from existing DB**: 複雑、データモデル変更なし
3. **Hybrid**: 注文状態変更のみにイベントソーシング

## Unresolved Questions

- [ ] イベントスキーマバージョニング戦略
- [ ] イベント保持ポリシー
- [ ] パフォーマンス用スナップショット頻度

## Implementation Plan

1. 単一注文タイプでプロトタイプ (2 週間)
2. Event Sourcing についてチームトレーニング (1 週間)
3. 完全実装と移行 (4 週間)
4. 監視と最適化 (継続)

## References

- [Event Sourcing by Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)
- [EventStoreDB Documentation](https://www.eventstore.com/docs)

ADR 管理

ディレクトリ構成

docs/
├── adr/
│   ├── README.md           # インデックスとガイドライン
│   ├── template.md         # チーム用 ADR テンプレート
│   ├── 0001-use-postgresql.md
│   ├── 0002-caching-strategy.md
│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
│   └── 0020-deprecate-mongodb.md      # ADR-0003 を置き換え

ADR インデックス (README.md)

# Architecture Decision Records

このディレクトリには [Project Name] の Architecture Decision Records (ADR) が
含まれています。

## Index

| ADR                                   | Title                              | Status     | Date       |
| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |
| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |
| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 |
| [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 |

## 新しい ADR を作成

1. `template.md` を `NNNN-title-with-dashes.md` にコピー
2. テンプレートを入力
3. レビュー用に PR を提出
4. 承認後にこのインデックスを更新

## ADR Status

- **Proposed**: 検討中
- **Accepted**: 決定済み、実装中
- **Deprecated**: 関連性がなくなった
- **Superseded**: 別の ADR に置き換えられた
- **Rejected**: 検討したが採用しなかった

自動化 (adr-tools)

# adr-tools をインストール
brew install adr-tools

# ADR ディレクトリを初期化
adr init docs/adr

# 新しい ADR を作成
adr new "Use PostgreSQL as Primary Database"

# ADR を置き換え
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"

# 目次を生成
adr generate toc > docs/adr/README.md

# 関連 ADR をリンク
adr link 2 "Complements" 1 "Is complemented by"

レビュープロセス

## ADR レビュー チェックリスト

### 提出前

- [ ] Context が問題を明確に説明している
- [ ] 実行可能なすべてのオプションが検討されている
- [ ] Pro/Con がバランス取れており正直である
- [ ] Consequences (ポジティブとネガティブ) が文書化されている
- [ ] 関連 ADR がリンクされている

### レビュー中

- [ ] シニアエンジニア 2 名以上がレビューしている
- [ ] 影響を受けるチームに相談している
- [ ] セキュリティ意味合いが検討されている
- [ ] コスト意味合いが文書化されている
- [ ] 復帰可能性が評価されている

### 承認後

- [ ] ADR インデックスが更新されている
- [ ] チームに通知されている
- [ ] 実装チケットが作成されている
- [ ] 関連ドキュメントが更新されている

ベストプラクティス

すべき事

• 早期に ADR を書く - 実装開始前
• 簡潔に保つ - 最大 1-2 ページ
• トレードオフについて正直である - 実際のデメリットを含める
• 関連する決定をリンクする - 決定グラフを構築
• ステータスを更新する - 置き換えられたら非推奨にする

するべきではない事

• 承認済み ADR を変更しない - 置き換える新しい ADR を書く
• Context をスキップしない - 将来の読み手が背景を必要とします
• 失敗を隠さない - 拒否された決定は価値があります
• 曖昧にしない - 具体的な決定、具体的な結果
• 実装を忘れない - アクション なし の ADR は無駄です