アーキテクチャ決定レコード

重要な技術的決定の背景と根拠を記録するアーキテクチャ決定レコード(ADR)を作成、維持、管理するための包括的なパターン。

このスキルを使用する場合

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

このスキルを使用しない場合

• 小さな実装の詳細のみを文書化する必要がある場合
• 変更がマイナーパッチまたはルーチン保守の場合
• 記録するべきアーキテクチャ決定がない場合

指示

1. 決定の文脈、制約、ドライバーをキャプチャします。
2. トレードオフを含む検討されたオプションを文書化します。
3. 決定、根拠、結果を記録します。
4. 関連するADRをリンクし、時間の経過とともにステータスを更新します。

コアコンセプト

1. ADRとは何ですか?

アーキテクチャ決定レコードは以下をキャプチャします:

• 文脈: 決定が必要だった理由
• 決定: 何を決めたか
• 結果: その結果どうなるか

2. ADRを書くべき場合

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

3. ADRライフサイクル

提案 → 承認 → 非推奨 → 置き換え
        ↓
      却下

テンプレート

テンプレート1: 標準ADR(MADR形式)

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

## ステータス

承認

## 文脈

新しいeコマースプラットフォーム用のプライマリデータベースを選択する必要があります。
システムは以下を処理します:
- 同時ユーザー約10,000人
- 階層カテゴリを持つ複雑な商品カタログ
- 注文と支払いのトランザクション処理
- 商品の全文検索
- ストア検索用の地理的空間クエリ

チームはMySQL、PostgreSQL、MongoDBの経験があります。
金融トランザクション用のACIDコンプライアンスが必要です。

## 決定ドライバー

* **ACID コンプライアンスは必須** - 決済処理用
* **複雑なクエリをサポートする必要あり** - レポーティング用
* **全文検索をサポートすることが望ましい** - インフラストラクチャの複雑性を削減
* **優れたJSON サポートがあることが望ましい** - 柔軟な商品属性用
* **チームの親熟度** - オンボーディング時間を削減

## 検討されたオプション

### オプション1: PostgreSQL
- **メリット**: ACID準拠、優れたJSONサポート(JSONB)、組み込み全文検索、
  PostGIS地理的空間対応、チームの経験あり
- **デメリット**: MySQLよりレプリケーション設定がやや複雑

### オプション2: MySQL
- **メリット**: チームに非常に馴染みがある、シンプルなレプリケーション、
  大規模コミュニティ
- **デメリット**: JSONサポートが弱い、組み込み全文検索なし(Elasticsearch必要)、
  拡張機能なしでは地理的空間対応なし

### オプション3: MongoDB
- **メリット**: 柔軟なスキーマ、ネイティブJSON、水平スケーリング
- **デメリット**: マルチドキュメント トランザクションのACIDなし(決定時点では)、
  チームの経験が限定的、スキーマ設計に規律が必要

## 決定

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

## 根拠

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

レプリケーション設定のやや複雑性は、追加サービスの削減(別途Elasticsearch不要)
で相殺されます。

## 結果

### ポジティブ
- 単一のデータベースがトランザクション、検索、地理的空間クエリを処理
- 運用複雑性の削減(管理するサービスが少ない)
- 金融データの強い一貫性保証
- チームが既存のSQL専門知識を活用可能

### ネガティブ
- PostgreSQL固有の機能を学習する必要あり(JSONB、全文検索構文)
- 垂直スケーリングの制限により、読み込みレプリカが早期に必要になる可能性
- 一部のチームメンバーがPostgreSQL固有のトレーニングが必要

### リスク
- 全文検索は専用検索エンジンほどよくスケールしない可能性
- 緩和策: 必要に応じてElasticsearch追加の可能性に向けた設計

## 実装ノート

- 柔軟な商品属性にJSONBを使用
- PgBouncer でコネクションプーリングを実装
- 読み込みレプリカ用のストリーミングレプリケーションをセットアップ
- ファジー検索にpg_trgm拡張を使用

## 関連する決定

- ADR-0002: キャッシング戦略(Redis) - データベース選択を補完
- ADR-0005: 検索アーキテクチャ - 必要に応じてElasticsearchで置き換える可能性

## 参考資料

- [PostgreSQL JSON ドキュメント](https://www.postgresql.org/docs/current/datatype-json.html)
- [PostgreSQL 全文検索](https://www.postgresql.org/docs/current/textsearch.html)
- 内部: `/docs/benchmarks/database-comparison.md`のパフォーマンスベンチマーク

テンプレート2: 軽量ADR

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

**ステータス**: 承認
**日付**: 2024-01-15
**決定者**: @alice, @bob, @charlie

## 文脈

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

## 決定

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

## 結果

**良い点**: コンパイル時の型エラー検出、IDEサポートの向上、自己文書化コード。

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

**緩和策**: TypeScript トレーニングセッション、`allowJs: true`での段階的導入の許可。

テンプレート3: Y-Statement形式

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

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

テンプレート4: 非推奨用ADR

# ADR-0020: MongoDBを非推奨にしPostgreSQLに置き換え

## ステータス

承認(ADR-0003を置き換え)

## 文脈

ADR-0003(2021)はスキーマの柔軟性の必要性のためユーザープロファイルストレージに
MongoDBを選択しました。それ以来:
- MongoDBのマルチドキュメントトランザクションは私たちのユースケースで問題のまま
- スキーマが安定し、ほぼ変更されなくなった
- 他のサービスからPostgreSQL専門知識を習得
- 2つのデータベースの保守は運用負担を増加

## 決定

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

## 移行計画

1. **フェーズ1**(1-2週間): PostgreSQLスキーマ作成、デュアルライト有効化
2. **フェーズ2**(3-4週間): 履歴データをバックフィル、一貫性を検証
3. **フェーズ3**(5週間目): PostgreSQLに読み込み切り替え、監視
4. **フェーズ4**(6週間目): MongoDBライトを削除、廃止

## 結果

### ポジティブ
- 単一のデータベース技術で運用複雑性削減
- ユーザーデータのACIDトランザクション
- チームがPostgreSQL専門知識に集中可能

### ネガティブ
- 移行作業(約4週間)
- 移行中のデータ問題のリスク
- スキーマ柔軟性が低下

## 学んだ教訓

ADR-0003経験からの文書化:
- スキーマ柔軟性のメリットは過大評価された
- 複数のデータベースの運用コストは過小評価された
- テクノロジー決定で長期保守を検討する

テンプレート5: リクエスト・フォー・コメント(RFC)スタイル

# RFC-0025: 注文管理にイベントソーシング採用を提案

## 概要

注文管理ドメインにイベントソーシングパターン採用を提案し、
監査性向上、時間クエリ有効化、ビジネス分析をサポート。

## モチベーション

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

## 詳細設計

### イベントストア

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

### プロジェクション

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

### テクノロジー

- イベントストア: EventStoreDB(目的別、プロジェクション処理)
- 検討された代替案: Kafka + カスタムプロジェクションサービス

## デメリット

- チームの学習曲線
- CRUD比較での複雑性増加
- イベントの慎重な設計が必要(保存後は変更不可)
- ストレージ増加(イベントは削除されない)

## 代替案

1. **監査テーブル**: シンプルだが時間クエリを有効にしない
2. **既存DBからのCDC**: 複雑、データモデル変更しない
3. **ハイブリッド**: 注文状態の変更のみイベントソース

## 未解決の質問

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

## 実装計画

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

## 参考資料

- [Martin Fowlerによるイベントソーシング](https://martinfowler.com/eaaDev/EventSourcing.html)
- [EventStoreDB ドキュメント](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  # [非推奨]
│   └── 0020-deprecate-mongodb.md      # 0003を置き換え

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

# アーキテクチャ決定レコード

このディレクトリには[プロジェクト名]のアーキテクチャ決定レコード(ADR)が含まれます。

## インデックス

| ADR | タイトル | ステータス | 日付 |
|-----|-------|--------|------|
| 0001 | プライマリデータベースとしてPostgreSQLを使用 | 承認 | 2024-01-10 |
| 0002 | Redisを使用したキャッシング戦略 | 承認 | 2024-01-12 |
| 0003 | ユーザープロファイル用MongoDB | 非推奨 | 2023-06-15 |
| 0020 | MongoDBを非推奨 | 承認 | 2024-01-15 |

## 新しいADRを作成

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

## ADRステータス

- **提案**: 検討中
- **承認**: 決定済み、実装中
- **非推奨**: 関連性がなくなった
- **置き換え**: 別のADRで置き換え
- **却下**: 検討されたが採用されない
- **リジェクト**: 考慮されたが採用されない

自動化(adr-tools)

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

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

# 新しいADRを作成
adr new "プライマリデータベースとしてPostgreSQLを使用"

# ADRを置き換え
adr new -s 3 "MongoDBを非推奨にしPostgreSQLに置き換え"

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

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

レビュープロセス

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

### 送信前
- [ ] 文脈が問題を明確に説明している
- [ ] すべての実行可能なオプションが検討されている
- [ ] 長所/短所がバランスしており正直である
- [ ] 結果(正と負)が文書化されている
- [ ] 関連するADRがリンクされている

### レビュー中
- [ ] 少なくとも2人の上級エンジニアがレビューした
- [ ] 影響を受けるチームに相談した
- [ ] セキュリティの影響を検討した
- [ ] コストの影響を文書化した
- [ ] 反転可能性を評価した

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

ベストプラクティス

すること

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

しないこと

• 承認されたADRを変更しない - 置き換える新しいものを書く
• 文脈をスキップしない - 将来のリーダーが背景を必要とする
• 失敗を隠さない - リジェクトされた決定は価値がある
• 曖昧にしない - 具体的な決定、具体的な結果
• 実装を忘れない - 実装なしのADRは無駄

リソース

• アーキテクチャ決定のドキュメント化(Michael Nygard)
• MADRテンプレート
• ADR GitHub組織
• adr-tools

制限事項

• このスキルは、上記で説明されたスコープと明確に一致する場合にのみ使用してください。
• 出力は、環境固有の検証、テスト、または専門家のレビューの代わりとしないでください。
• 必要な入力、権限、セキュリティ境界、または成功基準が不足している場合は、 立ち止まって明確にしてください。