LESSON 30分

ストーリー

佐
佐藤CTO
アーキテクチャの決定は記録に残さなければ意味がない
佐
佐藤CTO
半年後に『なぜこのデータベースを選んだの？』と聞かれたとき、答えられるかい？　人の記憶は曖昧だ。ADRを書くことで、決定の背景と理由を組織の資産にできる

ADRとは

Architecture Decision Record（ADR）は、アーキテクチャに関する重要な決定を記録する軽量なドキュメントです。

項目説明
目的決定の背景・理由・結果を記録する
対象アーキテクチャに影響を与える重要な決定
形式1決定1ファイル、マークダウン推奨
粒度「なぜその技術を選んだか」レベル

ADRテンプレート

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

## ステータス
提案中 / 承認済 / 非推奨 / 代替済

## コンテキスト
どのような状況で、なぜこの決定が必要になったのか。

## 決定
何を決定したのか。

## 理由
なぜこの決定をしたのか。検討した選択肢と比較。

## 結果
この決定によって生じるメリットとデメリット。

ADRのライフサイクル

提案中（Proposed）
  │
  ├─ 承認 → 承認済（Accepted）
  │            │
  │            ├─ 新しい決定で置換 → 代替済（Superseded by ADR-XXX）
  │            └─ 技術変更で無効化 → 非推奨（Deprecated）
  │
  └─ 却下 → 却下済（Rejected）

実践的なADR例

ADR-001: プライマリデータベースとしてPostgreSQLを採用する

# ADR-001: プライマリデータベースとしてPostgreSQLを採用する

## ステータス
承認済（2026-01-15）

## コンテキスト
新規ECプラットフォームのプライマリデータストアを選定する必要がある。
トランザクション処理、全文検索、JSONデータの柔軟な格納が求められている。

## 検討した選択肢
1. **PostgreSQL** - OSS、豊富な機能、JSONB対応
2. **MySQL** - OSS、広く普及、シンプル
3. **MongoDB** - ドキュメントDB、スキーマレス
4. **CockroachDB** - 分散SQL、強整合性

## 決定
PostgreSQLを採用する。

## 理由
- JSONB型による柔軟なスキーマ対応（商品属性の多様性）
- 全文検索機能（pg_trgm）で初期段階はElasticsearch不要
- チームに経験者が多い
- AWS RDSでのマネージド運用が可能
- CockroachDBは初期段階ではオーバースペック

## 結果
### メリット
- 豊富なエコシステムとコミュニティサポート
- Prisma ORMとの親和性が高い
- ACID準拠による強い整合性保証

### デメリット
- 大規模な水平スケーリングには別途検討が必要
- 全文検索は日本語対応にカスタマイズが必要

### 将来の検討事項
- 100万ユーザー超の場合、読み取りの水平スケーリング（Read Replica + pgpool）
- 検索要件が高度化した場合、Elasticsearchの導入（ADR別途）

ADR-002: サービス間通信にgRPCを採用する

# ADR-002: サービス間通信にgRPCを採用する

## ステータス
承認済（2026-01-20）

## コンテキスト
マイクロサービス間の同期通信方式を決定する必要がある。

## 検討した選択肢
1. **REST（JSON over HTTP）** - 汎用的、ツール豊富
2. **gRPC（Protocol Buffers）** - 高性能、型安全
3. **GraphQL** - 柔軟なクエリ

## 決定
内部サービス間通信にgRPCを採用する。
外部API（クライアント向け）はREST（OpenAPI）を維持する。

## 理由
- バイナリプロトコルによる高いパフォーマンス
- Protocol Buffersによるスキーマファースト開発
- 双方向ストリーミング対応（リアルタイム追跡に有用）
- コード自動生成による開発効率向上

## 結果
### メリット
- サービス間通信のレイテンシ30-50%削減
- スキーマ変更時のコンパイル時エラー検出

### デメリット
- デバッグ時の可読性がRESTより低い（バイナリ）
- ブラウザからの直接アクセス不可（gRPC-Webが必要）

ADR管理のベストプラクティス

プラクティス説明
連番管理ADR-001, ADR-002… と連番を付ける
Git管理docs/adr/ ディレクトリに格納しバージョン管理
レビューPRベースでチームレビューを実施
索引README.md にADR一覧と概要を記載
不変性承認済ADRは修正せず、新しいADRで代替する
docs/adr/
├── README.md          # ADR一覧（索引）
├── adr-001-postgresql.md
├── adr-002-grpc.md
├── adr-003-kafka.md
└── template.md        # ADRテンプレート

ADRを書くべきタイミング

  • 新しい技術やフレームワークの採用
  • アーキテクチャパターンの選択
  • サードパーティサービスの選定
  • 既存の決定を変更するとき
  • チーム内で議論が分かれた決定

まとめ

ポイント内容
ADRの目的決定の背景と理由を組織の資産にする
テンプレートステータス、コンテキスト、決定、理由、結果
ライフサイクル提案→承認→（代替/非推奨）
管理方法Git管理、PR レビュー、連番索引

チェックリスト

  • ADRの目的と価値を理解した
  • ADRテンプレートの各セクションの意味を把握した
  • ADRのライフサイクルを理解した
  • 実際のADR例を読み、書き方のイメージを掴んだ

次のステップへ

次は演習です。実際にトレードオフを分析してADRを書いてみましょう。

推定読了時間: 30分