ストーリー

RFCとADRの違い

// RFCとADRは補完関係にある
interface RFC {
  purpose: "意思決定に至るまでの議論プロセス";
  timing: "決定の前";
  content: "提案、代替案、議論、フィードバック";
  outcome: "承認されたらADRに変換";
}

interface ADR {
  purpose: "意思決定の記録と理由の保存";
  timing: "決定の後";
  content: "コンテキスト、決定、結果";
  outcome: "イミュータブルな記録として保管";
}

// フロー: RFC → 議論 → 承認 → ADR

RFCテンプレート

# RFC-2025-003: 商品検索サービスのElasticsearch導入

## メタデータ
- **著者**: 田中太郎
- **レビュアー**: 高橋、鈴木、山田
- **ステータス**: レビュー中
- **作成日**: 2025-04-01
- **最終更新**: 2025-04-05
- **レビュー期限**: 2025-04-15

## 1. サマリー
商品検索の全文検索機能をPostgreSQLのLIKE検索から
Elasticsearchに移行する提案。

## 2. 背景と動機
現在の商品検索はPostgreSQLのLIKE/ILIKE検索で実装されている。
商品数が10万件を超え、以下の問題が発生している:
- 検索レスポンスが平均1.2秒（目標: 200ms以内）
- 日本語のトークナイズが不十分で検索精度が低い
- ファセット検索（価格帯、カテゴリ）が実装困難

## 3. 提案
Elasticsearchを導入し、商品検索専用のインデックスを構築する。

### 3.1 アーキテクチャ
- PostgreSQLをSource of Truth（正データ）として維持
- DynamoDB StreamsまたはCDCでElasticsearchと同期
- 検索APIはElasticsearchに直接クエリ
- 書き込みはPostgreSQLに行い、非同期でインデックス更新

### 3.2 技術的詳細
- Elasticsearch 8.x
- 日本語アナライザ: kuromoji
- インデックス設計: 商品マスタ + カテゴリのデノーマライズ

## 4. 代替案

### 4.1 PostgreSQL全文検索（tsvector）
- Pros: 追加インフラ不要
- Cons: 日本語対応が弱い、ファセット検索が難しい
- 却下理由: 日本語検索の品質が要件を満たさない

### 4.2 Meilisearch
- Pros: セットアップが簡単、日本語対応良好
- Cons: 大規模データでの実績が少ない
- 却下理由: 10万件以上のスケーラビリティに懸念

### 4.3 Algolia (SaaS)
- Pros: 即座に利用可能、高品質な検索
- Cons: 従量課金で月額コストが高い
- 却下理由: 予算制約

## 5. リスクと軽減策
| リスク | 影響度 | 軽減策 |
|--------|--------|--------|
| データ同期の遅延 | 中 | 最大許容遅延を5秒と定義 |
| Elasticsearchの運用負荷 | 高 | マネージドサービス(OpenSearch)を使用 |
| インデックスの肥大化 | 低 | ILMポリシーで管理 |

## 6. 実装計画
| フェーズ | 期間 | 内容 |
|---------|------|------|
| Phase 1 | 2週間 | PoCと性能検証 |
| Phase 2 | 3週間 | 本実装とテスト |
| Phase 3 | 1週間 | 段階的リリース |

## 7. 未解決の質問
- [ ] マネージドサービスはOpenSearch Serviceでよいか？
- [ ] インデックス更新の頻度は？（リアルタイム vs バッチ）
- [ ] 既存の検索APIとの互換性をどう保つか？

RFCプロセスの設計

interface RFCProcess {
  stages: RFCStage[];
  roles: RFCRole[];
  timeline: Record<string, string>;
  criteria: AcceptanceCriteria;
}

interface RFCStage {
  name: string;
  description: string;
  duration: string;
  exitCriteria: string;
}

const rfcProcess: RFCProcess = {
  stages: [
    {
      name: "Draft",
      description: "著者がRFCを起草する",
      duration: "1-5日",
      exitCriteria: "テンプレートの全セクションが埋まっている",
    },
    {
      name: "Review",
      description: "レビュアーがコメントし、議論する",
      duration: "5-10日",
      exitCriteria: "全レビュアーがフィードバックを返した",
    },
    {
      name: "Revised",
      description: "フィードバックを反映して修正",
      duration: "2-3日",
      exitCriteria: "主要な懸念事項が解決されている",
    },
    {
      name: "Decision",
      description: "Approverが最終判断を下す",
      duration: "1-2日",
      exitCriteria: "Accepted または Rejected が確定",
    },
  ],
  roles: [
    { name: "Author", responsibility: "RFCの起草と修正" },
    { name: "Reviewer", responsibility: "フィードバックの提供" },
    { name: "Approver", responsibility: "最終判断（通常はテクニカルリード）" },
  ],
  timeline: {
    small: "1-2週間（影響範囲が小さい変更）",
    medium: "2-3週間（チームレベルの変更）",
    large: "3-4週間（組織レベルの変更）",
  },
  criteria: {
    quorum: "レビュアーの過半数がApprove",
    noBlockers: "Blockerフラグのコメントが全て解決済み",
    approverSign: "Approverの明示的な承認",
  },
};

interface RFCRole {
  name: string;
  responsibility: string;
}

interface AcceptanceCriteria {
  quorum: string;
  noBlockers: string;
  approverSign: string;
}

レビューの質を上げるコツ

## レビュアーへのガイドライン

### 確認すべきポイント
1. **問題の妥当性**: 解決すべき問題は本当に存在するか？
2. **提案の完全性**: 重要な観点が抜けていないか？
3. **代替案の検討**: 他により良い方法はないか？
4. **リスク評価**: 見落としているリスクはないか？
5. **実現可能性**: チームのスキルとリソースで実現可能か？

### フィードバックの形式
- **MUST**: 対応必須。ブロッカー
- **SHOULD**: 強く推奨。対応しない場合は理由を記載
- **COULD**: あれば良い。対応は任意
- **QUESTION**: 理解のための質問

まとめ

チェックリスト

• RFCとADRの違いを説明できる
• RFCテンプレートの各セクションを理解した
• RFCプロセスの4つの段階を把握した
• レビューガイドラインの重要性を理解した

次のステップへ

次は「設計ドキュメントの書き方」を学びます。RFCの中核となる技術的な設計をどう文書化するかを掘り下げましょう。

推定読了時間: 30分