dev-rfc

Dev RFC スキル

2 つの目的に役立つ RFC と技術提案を作成します。何を、なぜ構築するかについて関係者の認識を合わせること（RFC）と、システムの仕組みをエンジニアが理解できるようにすること（アーキテクチャドキュメント）です。実際の提案の多くは両方の要素を含んでおり、このスキルでは状況に応じた適切なセクションを選ぶ手助けをします。

参照テンプレート

3 種類の構成テンプレートについては、references/template.md を参照してください。

• RFC — 構築前に認識を合わせるためのものです。概要、アプローチ（公平な比較を含む）、サービス SLA、オブザーバビリティ、ロールアウト計画を重視します。
• Architecture Doc — 構築済みのシステムを記録するためのものです。図、ソースツリー、データフロー、設計思想を重視します。
• One-Pager — 小規模な変更（1 週間未満）向けです。問題、提案する解決策、ロールアウトを記載します。約 20 行です。

ステップ 0：モードを選ぶ

どの状況に該当するかをユーザーに尋ねるか、文脈から判断します。

状況	モード	ドキュメントが答える主な質問
新しいシステムや大規模な変更を計画している	RFC	「これを構築するべきか。構築するなら、どのように進めるべきか？」
既存のシステムをドキュメント化している	Architecture Doc	「このシステムはどのように動作するか？」
既存のシステムへの変更を提案している	RFC（Detailed Design に変更前後の図を含める）	「なぜこれを変更するのか。変更後はどのようになるのか？」
範囲の小さい変更（1 週間未満）	One-Pager	「何を、なぜ変更するのか。簡潔に」

既存システムへの変更では、RFC の構成を骨格としつつ、Detailed Design セクションに変更前後のアーキテクチャ図を含め、コンポーネントに [NEW] と [CHANGED] のマーカーを付けます。

ファイルの配置場所

• 正式な提案または RFC — 主な配置場所は docs/rfcs/RFC-NNN-title.md
• プロジェクト全体のアーキテクチャドキュメント — リポジトリのルートに ARCHITECTURE.md
• サブシステムのドキュメント — docs/design/subsystem-name.md、または説明対象のコードと同じ場所

ドキュメントの配置場所がユーザーから指定されていない場合は、尋ねてください。

ステップ 1：プロジェクトを把握する

何かを書く前に、全体像を頭の中に描きます。

RFC の場合：

• 問題の説明と制約について、ユーザーに確認します
• 関係者と承認者を把握します
• 連携または置き換えの対象となる既存システムについて尋ねます
• 厳守すべき制約（スケジュール、予算、互換性、コンプライアンス）を特定します
• すでに検討または却下された代替案について尋ねます

アーキテクチャドキュメントの場合：

• プロジェクトの README、CLAUDE.md、既存のドキュメントを読みます
• ソースツリーを調べ、主要なサブシステムとその境界を特定します
• 入力から出力までの主なデータフローをたどります
• モジュール間で受け渡される主要な型やインターフェースを確認します
• git の履歴を調べ、アーキテクチャ上の決定に関する背景を把握します

ステップ 2：ドキュメントの草案を作成する

references/template.md にある適切な構成に従います。含めるセクションはモードとプロジェクトの複雑さによって異なります。テンプレートには、小規模・中規模・大規模プロジェクト向けの規模に応じたガイダンスがあります。

モードごとに特に重要なセクション：

RFC — 承認者が特に重視するセクション：

1. Abstract — 3～5 文のエグゼクティブサマリーです。読者はこれだけを読めば、RFC 全体に目を通すべきかどうか判断できます。
2. Approaches — 公平な比較を含め、評価したすべての選択肢を記載します。これが RFC を仕様書と区別する要素です。
3. Service SLAs & Observability — 本番環境への対応準備を示します。システムが本番環境でどのように動作し、監視されるかを提案が考慮していることを示します。

Architecture Doc — 新しい貢献者が特に重視するセクション：

1. High-Level Architecture（図を含む）— ひと目で全体を把握できます。
2. Source Tree — 「X はどこにあるか」を調べるための索引です。
3. Key Design Decisions — 「なぜこのような方式なのか」という疑問に答えます。

ステップ 3：効果的なコンテンツを作成する

すべてのシステムがパイプラインであるとは限りません。 システムに合った図の形式を選びます。

• パイプライン — コンパイラー、データパイプライン、ETL。データが流れる線形のステージです。
• リクエストフロー — サービス、API。ミドルウェア、ハンドラー、依存関係を通るリクエストの経路です。
• イベントフロー — イベント駆動型システム。プロデューサー、キュー／トピック、コンシューマーです。
• レイヤー図 — Web アプリ、CRUD。UI → API → サービス → データの各レイヤーです。

図は中心となる要素です。読者が図だけでシステム全体の流れを理解できるようにします。ASCII のボックス描画を使用します。ステージにはモジュールのパスと説明を付けます。ステージ間のデータ形式を示します。

抽象的ではなく、具体的に記述します。 「モジュール A が入力を処理し、モジュール B に渡す」ではなく、「Preprocessor::preprocess() は String（行マーカー付きの展開済みテキスト）を出力し、Lexer::tokenize() はそれを受け取って Vec<Token> を生成する」と記述します。提案では、提案する型やインターフェースの名前を使用します。

アプローチでは、公平な長所と短所を備えた、真の代替案を示します。 推奨案をよく見せるために、他の案をわざと弱く描いてはいけません。それぞれのアプローチについて、実際の強みを認めます。推奨案に反対するレビュー担当者が、自分の支持する案が公平に扱われたと感じられるようにします。

目標と対象外事項は具体的で、検証可能なものにします。 例（「認証を OAuth2 に移行する」場合）：

目標：

• 第 3 四半期の終わりまでに、ユーザー向けのすべてのログインフローで OAuth2 認可コードフローを使用する
• リリース時に Google と GitHub を ID プロバイダーとしてサポートする
• セッショントークンの保存を SOC 2 要件に適合させる（保存時に暗号化し、有効期間を最大 24 時間とする）

対象外事項：

• サービス間認証の移行（当面は mTLS を継続）
• 独自の ID プロバイダーの構築 — Auth0 を使用する
• SAML のサポート（エンタープライズ SSO は第 4 四半期の別プロジェクトとする）

サービス SLA は具体的にします。 「高可用性」ではなく、「稼働率 99.95%」と記載します。「低レイテンシ」ではなく、「P99 が 300ms 未満」と記載します。それぞれの目標値には根拠を示します。

意思決定と理念を分けます。 主要な設計上の決定は、事実に基づく選択です（「SSA 形式を使用する」）。設計理念には、継続的な意思決定の指針となる原則を記載します（「表現を通じた関心の分離」）。

ステップ 4：レビューチェックリスト

RFC の場合：

• 要約は、RFC 全文を読むかどうかを読者が判断できるほど明確ですか？
• アプローチでは、すべての選択肢を、実際の長所と短所を含めて公平に示していますか？
• 推奨案には十分な根拠があり、何を断念するのか説明されていますか？
• サービス SLA は具体的な数値で示されていますか。「高可用性」のような曖昧な表現になっていませんか？
• 提案と照らし合わせて評価できるほど、目標と対象外事項が具体的ですか？
• 判断基準を含む具体的なロールバック計画がありますか？
• 承認者からの意見が必要な未解決の質問は、明確に示されていますか？

アーキテクチャ文書の場合：

• プロジェクトに詳しくない人でも、図だけで処理の流れを理解できますか？
• データフローに記載された具体的な型とメソッド名は正確ですか？
• 主要な設計上の決定は、新しいコントリビューターが最初に知る必要のある内容を網羅していますか？
• 他の文書（README、モジュールごとのドキュメント）への相互参照が含まれていますか？

ステップ 5：フィードバックを集めて反復する（任意）

RFC の作成後、ユーザーのブラウザーでレビュー UI を開くことを提案します。レビュー UI は、フィードバックを自動保存するローカルサーバーを起動します。複数回の改訂に対応し、ユーザーが文書を明示的に承認できます。

パスの解決： 以下のコマンドでは、$SKILL_PATH はこの SKILL.md ファイルの絶対パスを指します。このファイルを含むディレクトリとして解決してください（例：SKILL.md が /path/to/dev-rfc/SKILL.md にある場合、$(dirname "$SKILL_PATH") は /path/to/dev-rfc です）。Bun（または --experimental-strip-types を指定した Node 22 以降）が必要です。

第 1 ラウンド

1. RFC を指定されたファイルパスに保存します。
2. レビューサーバーを起動します。

   bun run "$(dirname "$SKILL_PATH")/scripts/generate_review.ts" <doc-path> --title "<project name>"
   

   これにより、localhost:3118 で HTTP サーバーが起動し、ブラウザーが開きます。フィードバックは、ユーザーの入力中に <doc-dir>/.rfc-review/feedback.json に自動保存されます（デバウンスは 800ms）。サーバーは、更新のたびに最新バージョンの Markdown も配信します。
3. ユーザーに次のように伝えます。「ブラウザーで RFC レビューを開きました：http://localhost:3118。各セクションにフィードバックを追加したり、テキストをハイライトしてインラインコメントを追加したりできます。その後、**Submit Feedback**（修正が必要な場合）または Approve（問題がない場合）をクリックしてください。フィードバックは入力中に自動保存されます。」
4. ユーザーがレビューの完了を伝えたら、ワークスペースからフィードバックを読み取ります。

   cat <doc-dir>/.rfc-review/feedback.json
   

ステータスの確認

• "status": "approved" — ユーザーが RFC を承認しました。反復を終了し、RFC が確定したことを伝えます。
• "status": "needs_revision" — ユーザーは変更を希望しています。修正に進みます。
• "status": "draft" — ユーザーはレビュー中にブラウザーを閉じました。続行するか、現在のドラフトフィードバックで十分かを確認します。

修正のガイドライン

修正時は、次の順序でフィードバックに優先的に対応します（最も具体的なものから最も一般的なものへ）。

1. インラインコメント（inline_comments）— 特定のテキストを対象としています。それぞれに対応します。
2. セクションのフィードバック（sections[].feedback）— セクションごとの懸念事項です。該当するセクションを修正します。
3. 全体的なフィードバック（overall_feedback）— 全般的なテーマです。ドキュメント全体に適用します。

セクションのフィードバックが空の場合、懸念事項はありません。そのセクションはスキップします。フィードバックがない箇所は変更しないでください。

以降のラウンド

RFC を修正した後、前回のフィードバックを読み取り専用のコンテキストとして表示し、次のレビューラウンドを開始します。

bun run "$(dirname "$SKILL_PATH")/scripts/generate_review.ts" <doc-path> --title "<project name>" \
  --previous-feedback <doc-dir>/.rfc-review/feedback-history/feedback-round-N.json \
  --iteration N+1

サーバーは起動時に、前回の feedback.json を feedback-history/feedback-round-N.json に自動的にアーカイブします。レビュー担当者には、各セクションの上部に前回のフィードバックが読み取り専用で表示されるため、懸念事項が解消されたか確認できます。

ユーザーが承認するか、これ以上のラウンドを望まないと明示するまで、ステータスの確認 → 修正 → 再起動のループを繰り返します。

終了条件

次のいずれかに該当した場合、反復を終了します。

• ユーザーが UI で Approve をクリックした（"status": "approved"）
• ユーザーが「問題ありません」「公開してください」「完了です」などと伝えた
• ユーザーがこれ以上ラウンドを続けたくないと明示した

静的フォールバック

サーバーを起動できない場合（ポートの競合、環境の問題など）は、静的モードに切り替えます。

bun run "$(dirname "$SKILL_PATH")/scripts/generate_review.ts" <doc-path> --title "<project name>" --static

これにより、スタンドアロンの HTML ファイルが開きます。送信すると、フィードバックは ~/Downloads に feedback.json としてダウンロードされます。ファイルの保存場所をユーザーに尋ねます。

ユーザーがレビューの反復なしでドキュメントを直接作成することを希望する場合、または 1 ページのドキュメントの場合は、この手順を完全にスキップします。

ステップ 5b：ライブ作成モード（任意）

RFC 全体を書いてからレビューする代わりに、ライブ作成モードを使用できます。このモードでは、まずすべての予定セクションの骨組みを含む UI を開き、セクションを 1 つずつ作成します。各セクションはリアルタイムでブラウザーに表示され、ユーザーは次のセクションの作成前に、セクションごとにフィードバックを返します。

ライブモードを使用する場合

• RFC の作成中に共同で作業したいとユーザーが希望している
• RFC が複雑で、各セクションで反復的に認識を合わせることが有効である
• ユーザーが「ライブ」「対話型」「ステップごと」モードを明示的に希望している

ライブサーバーの起動

1. テンプレートとプロジェクトの範囲に基づいて、RFC のセクション見出しを計画します。
2. サーバーをライブモードで起動します。

   bun run "$(dirname "$SKILL_PATH")/scripts/generate_review.ts" --live --title "<project name>" \
     --sections '["Abstract","Motivation","Goals and Non-Goals","Detailed Design","Approaches","Service SLAs","Rollout Plan"]'
   

   これにより、予定されているすべてのセクションが保留中のカードとして表示された骨組みを含むブラウザーが開きます。
3. ユーザーに次のように伝えます。「ライブ作成モードで RFC を開きました：http://localhost:3118。セクションを 1 つずつ作成します。次のセクションに進む前に、各セクションを承認するか、変更を依頼できます。」

セクションごとのプロトコル

各セクションについて、順番に次の手順を実行します。

1. セクションの内容を Markdown で記述します。
2. サーバーに送信します。

   curl -s -X POST http://localhost:3118/api/section/add \
     -H 'Content-Type: application/json' \
     -d '{"id": "abstract", "heading": "Abstract", "markdown": "## Abstract\n\nYour content here..."}'
   

   セクションは SSE を通じて、すぐにブラウザーに表示されます。
3. ユーザーからのフィードバックを待ちます。

   curl -s http://localhost:3118/api/wait-feedback?section=abstract
   

   これは、ユーザーがブラウザーで「Approve」または「Request Changes」をクリックするまで処理をブロックします（タイムアウトは 5 分です）。
4. 応答を処理します。
   • {"action": "approve"} — 次のセクションに進みます。
   • {"action": "request_changes", "text": "..."} — フィードバックを読み、セクションを修正してから、更新内容を送信します。

     curl -s -X POST http://localhost:3118/api/section/update \
       -H 'Content-Type: application/json' \
       -d '{"id": "abstract", "markdown": "## Abstract\n\nRevised content..."}'
     

     その後、再度 /api/wait-feedback?section=abstract を呼び出します。
   • {"timeout": true} — 5 分以内にユーザーから応答がありません。CLI でユーザーに確認するか、再試行します。

完了

すべてのセクションが承認されたら、承認済みのセクションから Markdown 全体を組み立て、指定されたファイルパスに書き込みます。すべてのセクションが承認された後、ユーザーはブラウザーで「Finalize RFC」をクリックすることもできます。

フォールバック

ライブモードで問題が発生した場合は、最初に RFC 全体を書き、その後標準のレビューユーザーインターフェイスを開いて、バッチモード（ステップ 5）に切り替えます。

トーンとスタイル

• アーキテクチャ文書では現在形の断定的な文体を使用します。将来形は提案に限って使用します。
• 簡潔にします。すべての単語に意味を持たせます。
• 説明よりも図、コード、型シグネチャなどで示すことを優先します。
• 段落は短くします。これは散文ではなく、リファレンス資料です。
• Markdown の書式：強調には太字、型やパスにはコードブロック、比較には表を使用します。

ドキュメントの規模

変更規模	形式	セクション
小規模（1 週間未満、単一コンポーネント）	1 ページ	問題、提案する解決策、展開
中規模（1〜4 週間、複数のコンポーネント）	標準 RFC	RFC 全文またはアーキテクチャ文書
大規模（1 か月超、複数チームにまたがる）	完全版 RFC + サブ文書	トップレベル文書 + サブシステムごとのリンク付きサブ文書

レビューワークフローのガイダンス

メタデータヘッダーにステータスを記載します。

1. ドラフト — 作成者が執筆中です。正式レビューの準備はできていません。
2. レビュー中 — 承認者に共有済みです。必要なフィードバックを明記します。
3. 承認済み — 承認者が承認済みです。正式な計画として扱います。
4. 置き換え済み — 新しい RFC に置き換えられています。置き換え先へのリンクを記載します。
5. 非推奨 — システムが存在しなくなったか、提案が取り下げられています。