rfc-writer

RFC 作成スキル

技術的な意思決定やアーキテクチャの変更について、完全なエンジニアリング RFC（コメント募集）を作成します。RFC は構造化された提案書であり、説得を目的とする文書ではありません。その目的は、意思決定を精査にさらし、トレードオフを明らかにし、検討した代替案を記録し、なぜその選択をしたのかを恒久的な記録として残すことです。

優れた RFC があれば、その場にいなかった人でも、数年後にチームがなぜそのような方法で構築したのかを理解できます。

必要な入力

まだ提示されていない場合は、次の情報を尋ねてください。

• RFC のタイトルと作成者 — RFC のテーマと提案者
• 解決する問題 — 現在、何が壊れているのか、欠けているのか、不十分なのか、そして今すぐ対応が必要な理由
• 提案するソリューション — 作成者が推奨するアプローチ（少なくとも概要レベル）
• 背景と制約 — チームの規模、既存のアーキテクチャ、スケジュール上の制約、予算の上限、コンプライアンス要件
• 検討した代替案 — 作成者が検討した代替アプローチを少なくとも 2 つ
• 現在のステータス — 意思決定前（フィードバックを募集中）か、意思決定後（決定済みの内容を文書化）か

出力形式

---

RFC [Number]: [Title]

作成者： [Name] | チーム： [Team name] 作成日： [Date] | 最終更新日： [Date] ステータス： Draft | In Review | Approved | Rejected | Superseded by RFC-[X] チケット： [JIRA-XXX] | Slack スレッド： [#channel link] レビュー期限： [Date — when comments should be submitted by]

---

概要

[RFC 全体を要約する 2～4 文です。これだけを読む人にも、何が提案されているのか、なぜ提案されているのか、主なトレードオフは何かが伝わるようにします。最後に書いてください。]

---

1. 問題提起

[解決する問題を説明します。ソリューションではなく、問題に焦点を当ててください。可能な場合は、具体的な数値を示してください。]

現在の状況： [現在の仕組み（既存のシステム、プロセス、アーキテクチャ）を説明します。関連する制約や限界があれば含めてください。]

今、これが問題である理由： [なぜ、もっと早くではなく、または後ではなく、今取り組むのでしょうか。緊急性や適時性を示す指標、インシデント、製品要件、または拡張性のしきい値を挙げてください。]

実際の問題の例： [問題を具体的に示すシナリオまたはインシデントです。抽象的な説明だけでなく、実際の影響をレビュー担当者が理解するのに役立ちます。]

// Example: current behaviour that illustrates the problem
[code snippet, log output, or sequence description showing the problem]

解決しない場合の影響：

• [影響 1 — 例：「新しいテナントのオンボーディングには、アカウントごとに 3 時間の手動設定が必要」]
• [影響 2 — 例：「認証サービスは 400 req/s を処理しており、現在の成長率では 8 週間以内に容量の上限に達する見込み」]
• [影響 3 — 例：「現在のアプローチは、今後のマルチリージョン要件と互換性がない」]

---

2. 目標と対象外

目標：

• [具体的で測定可能な成果 — 例：「テナントのオンボーディング時間を 3 時間から 5 分未満に短縮する」]
• [例：「認証サービスで P99 レイテンシ ≤50ms のまま 2,000 req/s をサポートする」]
• [例：「アプリケーション層を変更せずにマルチリージョン展開を可能にする」]

対象外： (この RFC で明示的に扱わない内容)

• [例：「この RFC では、内部サービス間の呼び出しに対する認証は扱いません。RFC-042 を参照してください」]
• [例：「既存システムのパフォーマンス改善。この RFC では既存システムを置き換えます」]
• [例：「過去のデータの移行。後続の RFC で扱います」]

成功指標：

指標	現在	目標	測定方法
[例：オンボーディング時間]	[3 時間]	[5 分未満]	[オンボーディングジョブの所要時間を Prometheus ヒストグラムで計測]
[例：認証レイテンシ P99]	[120ms]	[≤50ms]	[Datadog APM]
[例：エンジニアのセットアップ時間]	[4 時間]	[30 分未満]	[オンボーディングアンケート]

---

3. 背景と動機

［提案を評価するためにレビュアーが必要とする背景を記載します。これは問題の説明を繰り返すのではなく、その周辺にある技術的・ビジネス的な背景です。］

既存システムの概要： ［現在のアーキテクチャの関連部分を説明します。コンポーネント間の関係を理解するうえで役立つ場合は、ASCII 図を含めてください。］

[ASCII diagram of current architecture — optional but strongly recommended for architectural RFCs]

  ┌──────────┐     ┌──────────────┐     ┌──────────────┐
  │  Client  │────▶│  [Service A] │────▶│  [Service B] │
  └──────────┘     └──────────────┘     └──────────────┘
                           │
                           ▼
                   ┌──────────────┐
                   │  [Database]  │
                   └──────────────┘

これまでの取り組みと関連する決定：

• ［RFC-XXX：タイトル — 関連する過去の決定。リンク］
• ［ADR-XXX：タイトル — アーキテクチャ決定記録］
• ［この提案に影響する外部標準、ブログ記事、ベンダーのドキュメント］

制約：

• ［例：v1 API クライアントとの後方互換性を12か月間維持する必要がある］
• ［例：チームに Rust の知識がないため、ソリューションは Python または Go で実装する必要がある］
• ［例：メンテナンス時間を設けずにデプロイできる必要がある］

---

4. 提案するソリューション

［提案するアプローチを明確かつ具体的に説明します。エンジニアがこのドキュメントをもとに実装を開始できるだけの詳細を記載しますが、コードは書かないでください。コードは PR で作成します。］

4.1 概要レベルのアプローチ

［ソリューション全体について1～3段落で説明します。重要なアイデアと、それが問題を解決する理由を説明してください。］

4.2 アーキテクチャ

[ASCII diagram of the proposed architecture — what the system looks like after this RFC is implemented]

  ┌──────────┐     ┌──────────────────┐     ┌──────────────┐
  │  Client  │────▶│  [New Component] │────▶│  [Service B] │
  └──────────┘     └──────────────────┘     └──────────────┘
                           │                       │
                           ▼                       ▼
                   ┌──────────────┐       ┌──────────────┐
                   │  [Store A]   │       │  [Store B]   │
                   └──────────────┘       └──────────────┘

4.3 詳細設計

［ソリューションを主要なコンポーネントや決定ごとに分けて説明します。それぞれについて、何をするのか、なぜその設計にしたのかを説明してください。］

コンポーネント／決定 1：［名前］

［このコンポーネントの説明 — 何をするのか、どのように動作するのか、なぜこのアプローチを選んだのかを記載します。］

// Example interface, API contract, or pseudocode (not implementation code)
[Relevant schema, API definition, data flow, or pseudocode]

コンポーネント／決定 2：［名前］

［説明］

コンポーネント／決定 3：［名前］

［説明］

4.4 API の変更

RFC によって API エンドポイント、イベント、またはインターフェイスが新設または変更される場合に、このセクションを記入してください。

新しいエンドポイント／イベント：

[HTTP method + path or event name]
Request: { ... }
Response: { ... }

変更するエンドポイント：

• [endpoint]：［変更内容とその理由、後方互換性に関する注記］

廃止予定のエンドポイント：

• [endpoint]：[new endpoint] に移行するため廃止予定 — 削除予定：［日付／バージョン］

4.5 データモデルの変更

データベーススキーマまたはデータ構造の変更が必要な場合に、このセクションを記入してください。

［スキーマの変更を概要レベルで説明します。詳細な移行手順については、database-migration-plan スキルを参照してください。］

-- Key schema changes (abbreviated — full migration in [link])
[DDL statements for key additions/changes]

---

5. 検討した代替案

代替案ごとに、採用しなかった明確な理由を記載する必要があります。「提案したソリューションを選んだ」は理由になりません。

代替案 1：［名前］

説明： ［この代替案で必要となる内容を説明します。］

メリット：

• ［メリット 1］
• ［メリット 2］

デメリット：

• ［デメリット 1］
• ［デメリット 2］

却下した理由： ［具体的な理由 — 例：「インフラコストが3倍になる」、「マルチリージョンの要件に対応できない」、「チームにこの技術の知識がなく、習得期間を考慮すると第3四半期の期限に間に合わない」］

---

代替案 2：［名前］

説明： ［この代替案で必要となる内容を説明します。］

メリット：

• ［メリット 1］
• ［メリット 2］

デメリット：

• ［デメリット 1］
• ［デメリット 2］

却下した理由： ［具体的な理由］

---

代替案 3：何もしない／先送りする

説明： 現状を受け入れ、［期間］後に問題を再検討します。

却下した理由： ［先送りが許容できない理由を説明します。セクション1に記載した、問題を解決しない場合の影響を参照してください。］

---

6. 実装計画

見積もり工数： [X エンジニア週] | 完了目標： [日付／四半期] チーム： [担当者 — 氏名または役割]

フェーズ	説明	期間	依存関係	担当者
1	[例：コア実装 — 新しいコンポーネントを構築してテスト]	[X 週間]	[なし]	[氏名]
2	[例：統合 — 新しいコンポーネントを既存のサービスに接続]	[X 週間]	[フェーズ 1 の完了]	[氏名]
3	[例：展開 — カナリアデプロイ後、全面展開]	[X 週間]	[フェーズ 2 の完了＋ステージングでの検証]	[氏名]
4	[例：整理 — 旧システムを非推奨化し、機能フラグを削除]	[X 週間]	[フェーズ 3 の安定稼働が X 週間]	[氏名]

主なマイルストーン：

• [日付]：[マイルストーン — 例：「コア実装が完了し、コードレビュー済み」]
• [日付]：[マイルストーン — 例：「ステージング環境での検証が完了」]
• [日付]：[マイルストーン — 例：「回帰なしでカナリアトラフィック 10％を達成」]
• [日付]：[マイルストーン — 例：「全面展開が完了」]
• [日付]：[マイルストーン — 例：「旧システムの廃止が完了」]

---

7. 移行計画

RFC で既存のユーザー、データ、または API 利用者の移行が必要な場合は、このセクションを記入してください。

移行戦略： [一括移行／段階的移行／並行稼働／オプトイン]

影響を受ける対象：

• [例：既存の API v1 利用者全員 — クライアントライブラリの更新が必要]
• [例：orders テーブルの X 百万行をバックフィルする必要がある]

移行手順：

1. [手順 1 — 実施内容、担当者、見積もり期間を記載]
2. [手順 2]
3. [手順 3]

後方互換性の維持期間： [旧システム／API はどのくらいの期間利用可能ですか？]

コミュニケーション計画：

• [通知対象、時期、方法 — 例：「旧エンドポイントの削除の 3 か月前に、API 利用者へ非推奨化の通知を送付」]

---

8. セキュリティへの影響

[この変更によるセキュリティへの影響を説明してください。セキュリティへの影響がない場合は、理由とともに明記してください。このセクションを空欄のままにしないでください。]

懸念事項	影響	緩和策
[例：新しい API エンドポイントをインターネットに公開]	[例：新たな攻撃対象領域]	[例：レート制限、認証必須化、WAF ルール]
[例：新しいデータの保存 — ユーザーの個人情報]	[例：GDPR の適用範囲が拡大]	[例：保存時の暗号化、アクセスログ、データ保持ポリシー]
[例：サービス間通信]	[例：トークン偽造のリスク]	[例：サービス間の mTLS]

脅威モデルは作成または更新されていますか？ [はい — リンク／いいえ — 実装前に必須／不要 — 理由]

---

9. パフォーマンスへの影響

[予想されるパフォーマンスへの影響を説明してください。新システムの予測値と、その推定方法を記載してください。]

指標	現在	予測	測定方法
[例：P99 レイテンシ — /api/auth]	[120ms]	[≤50ms]	[負荷テストの結果 — リンク]
[例：リクエストあたりのデータベースクエリ数]	[12]	[3]	[ステージングでのクエリログ]
[例：インスタンスあたりのメモリ]	[512MB]	[768MB]	[プロファイリング — リンク]
[例：インフラコスト]	[$X/month]	[$Y/month]	[AWS コスト計算ツールによる見積もり]

負荷テスト： [負荷テストは実施済みですか？結果へのリンクを記載してください。未実施の場合、実施予定時期を記載してください。]

パフォーマンスリスク：

• [リスク 1 — 例：「新しいコンポーネントによってネットワークホップが増え、輻輳時にテールレイテンシが増加する可能性があるため、ピーク負荷の 2 倍での検証が必要」]

---

10. 可観測性の変更

この RFC で導入する新規または変更対象のメトリクス、ログ、トレース、アラートを記載してください。

新しいメトリクス：

メトリクス名	種類	説明	アラートしきい値
[service].[component].[metric]	[カウンター／ゲージ／ヒストグラム]	[測定内容]	[例：P99 > 100ms が 5 分間継続]

新しいログイベント：

イベント	レベル	出力タイミング	主なフィールド
[event.name]	INFO	[タイミング]	user_id、duration_ms、result

分散トレーシング： [新しいコンポーネントにスパンを追加しますか？どの操作を計測しますか？]

ダッシュボードの変更： [新しいダッシュボード／既存ダッシュボードの更新 — リンク]

---

11. ロールアウト計画

ロールアウト戦略：［フィーチャーフラグ／カナリア／ブルーグリーン／段階的なトラフィック移行／全面デプロイ］

段階	トラフィック割合	期間	成功基準	ロールバックのトリガー
内部テスト	0%（ドッグフーディング）	［X 日間］	［内部利用でエラーがないこと］	エラーが1件でも発生
カナリア	1%	［X 時間］	［エラー率 <0.1%；P99 レイテンシが予算内］	エラー率 >0.5%
限定的なロールアウト	10%	［X 日間］	［上記に加え、ビジネス指標が安定していること］	エラー率 >0.2%
全面ロールアウト	100%	—	［セクション 2 のすべての成功指標を達成］	SLO 違反が1件でも発生

フィーチャーフラグ：［該当する場合はフィーチャーフラグ名］ — ［LaunchDarkly／Unleash／config］で管理

ロールバック手順：

// How to roll back if the rollout needs to be reversed
1. [Step 1 — e.g. Toggle feature flag to off]
2. [Step 2 — e.g. Deploy previous version]
3. [Step 3 — e.g. Notify stakeholders]

---

12. 未解決の質問

［未解決の質問、まだ決定していない設計上の判断、または著者が特にフィードバックを求めている分野を記載してください。それぞれに担当者と解決期限を割り当てます。］

#	質問	担当者	期限	解決状況
1	［例：［リソース］への同時更新には、楽観的ロックと悲観的ロックのどちらを使うべきですか？］	［名前］	［日付］	［保留中／［回答］］
2	［例：［新しいデータ型］の保持ポリシーはどうしますか？］	［名前］	［日付］	［保留中／［回答］］
3	［例：リリース時にこのクエリパターン用のリードレプリカが必要ですか？それとも後回しにできますか？］	［名前］	［日付］	［保留中／［回答］］

---

13. 決定事項

レビュー期間終了後に記入します。

決定：［承認／却下／修正を条件に承認］
決定日：［日付］
決定者：［名前］

対応済みの主なフィードバックの概要：

• ［フィードバック項目とその対応方法］

承認条件（該当する場合）：

• ［例：フェーズ 2 の開始前に負荷テストを完了すること］

---

品質チェック

• 問題の記述が具体的で、数値化されています。「現行システムが遅い」ではなく、「P99 レイテンシは 800ms、予算は 200ms」のように記載します
• 目標のセクションに、願望的な記述ではなく測定可能な成功指標が含まれています
• すべての代替案に、明確な却下理由が記載されています。短所を列挙するだけでは不十分です
• セキュリティへの影響のセクションが記入されており、空欄ではありません
• パフォーマンスへの影響に、単に「改善するはず」と書くのではなく、予測値が含まれています
• 未解決の質問に、期限付きで担当者が割り当てられています。担当者不在のまま放置されていません
• RFC は、計画に関する議論に参加していなかった人にも理解できるように書かれています
• 移行計画では、技術的な手順だけでなく、ユーザー、API 利用者、データなど、影響を受けるすべての対象が考慮されています

アンチパターン

• RFC を説得のための文書として書かないでください。目的はトレードオフを明らかにすることであり、決定を売り込むことではありません
• 明確な却下理由なしに代替案を列挙しないでください。「提案された解決策を優先した」は理由になりません
• セキュリティへの影響のセクションを空欄にしたり、理由を説明せずに「該当なし」と書いたりしないでください
• 担当者と解決期限を割り当てずに、未解決の質問を記載しないでください
• 「解決しなかった場合の影響」のセクションを省略しないでください。このセクションがないと、レビュアーは緊急性を評価できません

きっかけとなるフレーズの例

• 「RFC を作成してください。」
• 「技術提案を文書化してください。」
• 「設計ドキュメントを作成してください。」
• 「レビュー用のアーキテクチャ決定書を作成してください。」
• 「チームのフィードバック用に技術仕様書を作成してください。」