write-a-prd

PRD を作成する

このスキルでは、形の整った提案を作成します。ビルダーが判断できる余地を残しつつ、出荷できる程度には解決されており、明確な時間の許容範囲が定められた PRD です。以下の手順に従い、作業に応じて深さを調整します。ただし、時間の許容範囲、現在のコードの実態、組織内の知識、引き継ぎの準備状況を確認する手順は省略しないでください。

1 回のターンにつき質問は 1 つです。 このスキルのインタビューでは、一度に 1 つだけ質問し、次の質問をする前にユーザーの回答を待ってください。短い質問であっても、1 つのメッセージで複数の質問を提示しないでください。

単一選択を優先してください。 ユーザーが 1 つの方向性、優先事項、または次のステップを選ぶ場合は、単一選択式の複数選択肢を使用してください。

複数選択はなるべく避けてください。 互いに両立する目標、制約、対象外事項、成功基準などに限って使用してください。優先順位が重要な場合は、選択した項目のうちどれが最優先かを追加で尋ねてください。

利用可能な場合は、プラットフォームの質問ツールを使用してください。 Claude Code では AskUserQuestion、Codex では request_user_input、Gemini では ask_user を使用してください。それ以外の場合は、チャットで番号付きの選択肢を提示し、ユーザーの返答を待ってから次に進んでください。

呼び出し位置

これは主要なパイプラインスキルであり、通常は /research の後、/prd-to-issues の前に実行します。

問題を理解できており、解決策の範囲を定め、実装可能な提案にまとめる場合は、/write-a-prd を使用してください。

問題がまだ曖昧で、/shape で発見を続ける必要がある場合、/research で技術的な実態をまだ確認していない場合、またはユーザーがすでに方向性の定まった PRD を持っていて、分解や実行を望んでいる場合は、ここから始めないでください。

プロセス

1. 問題を具体的なストーリーとして把握する

現状が実際のユーザーにとってなぜうまくいかないのかを示す具体的なストーリーを説明してもらいます。抽象的な機能リクエスト（「X を改善する必要がある」）は、具体的な摩擦（「ユーザーが Y をしようとすると、Z のせいで行き詰まる」）に落とし込めるまで、掘り下げてください。

よい問題文は、1 人の登場人物、1 回の試み、1 つの失敗を描く 1 つの場面です。ユーザーが先に解決策を提示した場合（「Webhook システムを追加したい」など）は、「これを作る必要があるほど、今どのような問題が起きていますか？」と尋ねてください。

2. アペタイトを設定する

ソリューションを設計する前に、時間の予算を決めます。この問題にどれだけの時間をかける価値がありますか？

• 小規模バッチ：実装に1～2週間
• 大規模バッチ：実装に最大6週間

アペタイトは制約であり、見積もりではありません。「どれだけの時間をかける意思があるか」に答えるものであり、「どれくらいの時間がかかるか」に答えるものではありません。問題がアペタイトに収まらない場合は、予算を増やすのではなく、問題の範囲を狭めてください。

アペタイトは目標であり、ビジネスがどれだけの時間をかける意思があるかを示します。作業にどれくらいの時間がかかりそうかを分析して予測する見積もりでも、期日までに納品するという約束であるコミットメントでもありません。現在の見積もりがアペタイトを超える場合は、アペタイトを暗黙のうちにコミットメントに変えるのではなく、ソリューションを再構成してください。

アペタイトは、その後のすべてに影響します。どのユーザーストーリーを必須とし、どれをあれば望ましいものとするか、どれだけの寄り道を許容するか、スコープをどれだけ厳しく絞り込むかが決まります。

大規模バッチ作業のコンテナとしてのマイルストーン。 アペタイトが大規模バッチ（6週間）の場合、PRDとその後のスライスのイシューをまとめる組織上のコンテナとして、GitHubのマイルストーンを作成するか確認してください。通常は作成します。大規模バッチ作業では、GitHubでマイルストーン単位の進捗を追跡すると効果的です。

新しいマイルストーンを作成する前に、既存のものがないか確認してください。gh api repos/{owner}/{repo}/milestones --jq '.[].title'。既存のマイルストーンがある場合（たとえば、前のトランシェで /create-milestone を実行して作成したもの）、新しく作成するのではなく、そのマイルストーンに紐付けるかどうかを確認してください。

ユーザーが同意した場合は、ステップ8で使うマイルストーン名を記録してください。ユーザーが辞退した場合は、マイルストーンなしで進めてください。マイルストーンは組織上の便宜であり、構造上の必須要件ではありません。小規模バッチ作業（1～2週間）にはマイルストーンは不要です。

ステップ8のバックエンド確認で sidecar と判明した場合、マイルストーンは名前にすぎません。gh api による検索は省略し、GitHub上には何も作成しないでください。名前を記録し、ステップ8で作業項目のフィールドとして登録します。

3. コードベースを調査する

リポジトリを調査して、ユーザーの主張を検証し、コードの現在の状態を把握します。

4. 組織のナレッジを確認する

ユーザーにインタビューする前に、次の2つの情報源を確認します。

過去の解決策 — 教訓が記録されている可能性のある場所をすべて検索します。プロジェクトのサイドカーと、リポジトリ内のパスの両方です。このスキルに同梱されているリゾルバー references/sidecar.sh を、インストール先の絶対パスを使って実行し、両方の場所を解決します。サイドカーパスを自分で計算してはいけません。sidecar.sh solutions-dirs は検索対象のディレクトリを出力し、その方針を管理します（ヘッダーに記載されています）。検索するキーワードを KW に設定します。

SC="<this skill's directory>/references/sidecar.sh"
KW="relevant-keyword"
bash "$SC" solutions-dirs | while IFS= read -r DIR; do
  [ -d "$DIR" ] && grep -rl -- "$KW" "$DIR"
done
true

両方の場所で見つかった項目を一覧表示します。一方が他方を隠すことはありません。docs/solutions 以外の in_tree_path（docs/adr、docs/decisions など）にある項目は、そのリポジトリ独自の慣習に従ったものです。フロントマターや古さの確認は行わず、通常のドキュメントとして読みます。読んだ項目に別のパス（Related: ポインター、調査項目、ドシエなど）が記載されている場合は、SC="<this skill's directory>/references/sidecar.sh"; bash "$SC" require "<cited path>" --from "<the citing entry's file path>" で確認します（新しいシェルには SC がありません）。引用元からパスを導き出すのではなく、出力されたパスを開きます。MISSING: 行が表示された場合は、スキップせずユーザーに示します。関連する解決策があれば読み、その教訓を問題領域の理解に取り入れます。インタビューでは、関連する落とし穴、パターン、決定事項をユーザーに伝えます。「類似機能では以前 X が問題になり、Y で解決しました。今回も同じパターンを適用しますか？」のように尋ねます。

調査ドキュメント — この機能に関する最新の調査成果物を探します。プロジェクトの research.storage 設定に応じて、成果物は次のいずれかの場所にあります。

1. スパイク課題モード — GitHub で、該当機能に一致する、クローズ済みかつ research ラベル付きの課題を検索します。

   gh issue list --label research --state closed --search "<feature keywords>" --limit 5
   

   該当するスパイク課題があれば、その本文を読みます。先頭の YAML フロントマターには、アーカイブと同じ date フィールドと installed_versions_snapshot フィールドが記載されています。

2. アーカイブモード（デフォルト） — Phase 5c が書き込む調査ディレクトリ /research を、同じリゾルバーを使って一覧表示します。サイドカーがある場合はその research/ が対象です。SIDECAR MISS の場合はサイドカー導入前のアーカイブであり、sidecar.sh archive-dir がこのブロックと Phase 5c の両方に対してその場所を示します。

   SC="<this skill's directory>/references/sidecar.sh"
   ERR="$(mktemp)" || exit 1
   if DIR="$(bash "$SC" path research 2>"$ERR")"; then
     rm -f "$ERR"
     ls "$DIR"
   else
     cat "$ERR" >&2
     # Only a SIDECAR MISS falls back; any other failure is a refusal, not a miss.
     grep -q 'SIDECAR MISS:' "$ERR" || { rm -f "$ERR"; exit 1; }
     rm -f "$ERR"
     DIR="$(bash "$SC" archive-dir)" || exit 1
     echo "pre-sidecar archive: $DIR"
     if [ -d "$DIR" ]; then ls "$DIR"; else echo "(empty: no research entries)"; fi
   fi
   

feature フロントマターフィールド（またはファイル名のスラッグ）がこの機能に一致する項目を選び、$DIR/<file> として参照します。SIDECAR MISS の場合は、表示されたミスの行をそのままユーザーに示し、サイドカーの作成は人間が行うものなので、その init コマンドは実行しません。ミスの行がなく終了コードが 1 の場合（Git リポジトリではない場合）は、ミスではありません。リゾルバーの出力をそのまま伝えます。scripts/test-sidecar-resolution.sh は、Phase 5c の書き込み先とこのブロックの書き込み先が異ならないことを確認します。

両方の場所を確認します。プロジェクトが最近モードを切り替えた場合、以前の場所に成果物が残っていることがあります。同じ機能について両方に成果物がある場合は、フロントマターの date がより新しいものを優先し、重複があることをユーザーに伝えます。調査成果物を信用する前に、フロントマターの date と installed_versions_snapshot を確認します。どちらかが現在の実情と照らして古いようであれば、そのことをユーザーに知らせます。新しく有効な調査成果物があれば、十分に読み込みます。そこには /research フェーズで調査・推奨された技術的なアプローチが記載されています。提案は、これらの推奨事項を踏まえて作成し、再検討の議題にしないでください。実装時に /execute と Ralph が参照できるよう、提案には正規の場所（スパイク課題の URL、または上記のとおりに一覧表示された項目の絶対パス）を記載します。

成果物の優先順位： 調査成果物と docs/solutions/ の内容が食い違う場合は、調査成果物を優先します。インストール済みバージョンに照らして検証されているためです。保存場所は信頼性に影響しません。スパイク課題もアーカイブ項目も、同じ /research スキルが同じ Phase 0/1 の検証に基づいて本文を作成するため、同等の権威があります。食い違いを黙って選択するのではなく、インタビュー中にユーザーに伝えます。

5. Shape Up の手法を取り入れたインタビュー

解決策についてユーザーに聞き取りを行います。ただし、全体を通じて Shape Up のシェーピング手法を適用します。

ユースケースごとに解決策を検証します。 形になりつつある設計に照らしながら、やり取りを一つずつたどります。ここでギャップや脇道が明らかになります。「ユーザーが X をしたとき、Y がまだ読み込まれていなかったらどうなりますか？」といった具合です。脇道が見つかったらその都度名前を付け、先に進む前に一行で解決策を合意します。 重要なユースケースには、メインの成功シナリオに加えて、フローが変化する、失敗する、または復旧が必要になる拡張シナリオが少なくとも 2 つ必要です。拡張シナリオを挙げられない場合、そのシナリオは十分にシェーピングされていません。

留保付きアンカーは、未解決の脇道の一種として扱います。「またはその X テーブル」、「現在 Y が使っているものと同じローダーパス」、「既存の Z テストを模倣する」、*「W の既存パターン」*といった表現は、モデルが実在を確認していないエンティティを名指ししたことを示しています。§Rabbit Holes 内の留保付き表現は、同じ PRD の §Implementation Decisions では断定的な表現に変わり、/prd-to-issues のスライス Boundary Map に伝わり、さらに /execute の Step 0 を過ぎても残ります。Step 0 の Consumes 検証ゲートが反応するのは、曖昧な名詞ではなく、名前の付いたシンボルだけです。§Implementation Decisions の内容が固まる前に、留保付きアンカーをすべて解決してください。リポジトリ内の検索で正確な識別子を確認するか、エンティティが存在するかのように見せかけない表現に書き換えます。この PRD の /research が実行されていれば、Phase 0 の仕様アンカーチェックですでに検出されているはずです。この段落は、/research が省略または圧縮された場合の最後の安全策です。

ユースケースをたどった後に、一度視点を反転させます。 前向きに検討して最初の脇道を洗い出したら、フレーミングを反転させます。この機能をリリースした結果、深刻な問題が起きたと想像してください。その問題は何だったでしょうか？失敗から逆算して考えます。各失敗モードを、解決策を添えて Rabbit Holes または No-gos に分類します。「許容できるリスク」といった曖昧なまま放置してはいけません。解決も除外もできない失敗モードがあるなら、設計はまだ解決されていません。

症状だけでなく、構造を確認します。 アプローチを固める前に、次の 3 つの質問を一つずつ尋ねます。一つ尋ねて回答を受け止めてから、次の質問に進みます。

1. 目に見える不満だけでなく、現在の問題を引き起こしている根本的な条件は何ですか？
2. 問題を早期に把握しにくくしている遅延、引き継ぎ、フィードバックループの欠如はありますか？
3. 提案する介入は、その条件に大きな効果をもたらす変更ですか。それとも局所的な症状の修正にすぎませんか？

簡潔さを保ちます。目的はシェーピングの改善であり、ピッチをシステム思考の論文にすることではありません。

スコープを継続的に分類します。 機能や振る舞いが話題に上がるたびに、必須項目か、あると望ましい項目（~）かを分類します。あると望ましい項目は、あらかじめ削減を認められた項目です。工数の上限が厳しい場合、議論せずにまずこれらをスコープハンマーで削減します。

粘土を柔らかいまま保ちます。 形になりつつある理解は、「今のところ、こう考えています。どこでも異論があれば教えてください」のように、変更可能なものとして示します。最終決定として提示してはいけません。そうすることで、ただ追認するのではなく、軌道修正を促せます。

理想ではなく、現状と比較します。 スコープ削減が許容できるかを評価する際は、完璧なバージョンではなく、ユーザーが現在利用できるもの（ベースライン）と比較します。理想を目指した結果何も出荷しないより、ベースラインを上回るものを出荷するほうが常に優れています。 条件付きのフロー行。 この機能で、ユーザー向けの複数ステップのフロー、新しいナビゲーション、または重要な UI 状態の変更が導入される場合は、インタビュー中に、その配置場所（画面／ダイアログ）、操作要素（各画面のボタン／フィールド／アクション）、接続関係（何がどこにつながるか）を整理してください。また、各行は独立したセクションにまとめるのではなく、実現する必須ストーリーに紐づけてください。これにより、遷移の漏れや曖昧な状態を早期に発見でき、/prd-to-issues のステップ 5 で、文全体の粒度ではなく操作要素の粒度でテスト範囲を検証できます。1 行が複数の必須項目を実現する場合もあります。また、どの必須項目も実現しない行（ナビゲーションの枠組み、読み込み中や空の状態）は、テンプレートに用意された未帰属の残余部分に記載してください。すべての行を必ず 1 つのストーリーだけに紐づけるよう強制しないでください。そうすると、行が適切な場所に配置されず、削除されるという過剰な制約が生じます。API のみ、バックエンド、または単一画面の変更では省略してください。

インタビュー中に、過去のソリューションや調査から関連する知見を取り上げてください。

• 「調査ではプレゼンスに Ably を推奨しています。この推奨を採用しますか、それとも再検討しますか？」
• 「docs/solutions/ に X に関する落とし穴が記録されています。設計で考慮する必要があります。」
• 「過去のソリューションでは、この種の統合にパターン Y を使うことが提案されています。今回も適していますか？」

ユーザーが日付、期限、確信度について話し始めたら、先に進む前に、何を意味しているのかを明確にしてください。次の質問を 1 つずつ尋ねてください。

1. これは目標（望ましいビジネス成果または期限）、見積もり（現時点での予測）、それともコミットメント（交渉のうえでの約束）ですか？
2. 強いコミットメントを時期尚早にしている不確実性は、まだ何ですか？
3. この提案には、単一の日付ではなく、幅を持たせた期間や確信度に関する注記を含めるべきですか？

API 形式の作業では、インタビューを終える前にコントラクトを具体化してください。簡潔で構いませんが、次の項目を明示してください。

• API の課題と影響の説明
• コントラクトを利用する開発者
• API がサポートする必要のある操作
• エンドポイントまたはイベントの概要
• 利用者にとって重要な必須フィールド、任意フィールド、デフォルト値が設定されるフィールド
• 想定されるエラー形式
• 既存の利用者との互換性に関する注記
• 採用しなかったパラダイムやコントラクトの方向性についての、「その他に検討したこと」の簡単な注記

これは完全な実装仕様ではありません。/execute が作業中に API の動作を独自に作り上げないようにするために必要な、最小限のコントラクト概要です。

6. 検証：大まかで、解決済みで、範囲が限定されている

提案を書く前に、具体化した作業が次の 3 つの特性を備えていることを確認してください。

• 大まか：このソリューションには、意図的にビルダーの判断に委ねる余地を残します。ピクセル単位の UI、厳密なメソッドシグネチャ、手順ごとの実装は指定していません。ワイヤーフレームやチュートリアルのように読めるなら、詳細に踏み込みすぎています。
• 解決済み：大枠の方針が決まっています。特定されたすべての未解決事項に、1 行で解決策が示されています。ビルダーが根本的なアーキテクチャ上の決定をする必要はなく、戦術的な決定だけで済みます。
• 範囲が明確：アペタイトが定められています。対象外事項が明記されています。あるとうれしい項目には ~ が付いています。ビルダーは、質問しなくても対象範囲を把握できます。
• 不確実性を正直に示す：スケジュールやスコープにプレッシャーがある場合、ピッチではアペタイトの目標と現在の見積もりや確約を区別しています。大きな不確定要素が未解決のまま、誤った精密さで単一の日付を提示することはありません。
• 漏れがない：作成前に、ユーザーストーリーや未解決事項でカバーされていない、よく抜け落ちる作業がないか確認します。スコープ超過の主な原因は、見積もり不足ではなく作業の漏れです。AI エージェントはこれを増幅します。Ralph は、誰も触れなかったエラーハンドリングを追加するために残業しません。そのまま出荷します。次のチェックリストを確認してください（30 秒で十分です。各項目を網羅的に議論するのではなく、関連性を確認してください）。
  • 名前は挙がっているが列挙されていない、製品の意味論に関する内容（ルーブリック、分類方式、スコアリング基準、分類体系、役割／権限マトリックス、判断ルールなど） — PRD で分類方式に名前だけ言及し、その構成要素を列挙していない場合は、§Implementation Decisions で列挙するか、対象外と宣言してください。「7 つのカテゴリ」や「4 つの階層」のような表現は、実際には内容が PRD 本文ではなくユーザーの頭の中にあるのに、定冠詞による確信を示す、誤った精密さの兆候です。
  • 代替のナレッジチャネル — この機能が「再質問しない／重複させない／再表示しない／一度だけ処理する」という不変条件を守る場合、対象となる入力が届くすべてのチャネルを列挙してください（構造化フィールド と 自由文、入力された回答 と アップロードされたドキュメント、API パラメーター と インラインテキスト）。チャネルの構造的なマーカー（センチネルプレフィックス、メッセージロール、ツール出力のパートタイプなど）に基づくガードは、他のチャネルを構造上見落とします。自由文のように語彙が自由なチャネルでは、ガードは意味的なものでなければなりません。決定論的なキーではなく、LLM の判断を促すプロンプトを使い、回帰ガードを動作／評価の接点に置いてください。「提示済み」（完全に提供されている）と「言及済み」（触れられてはいるが、実質的に不完全）を区別してください。後者については、引き続き質問できる状態にします。
  • 品質属性（パフォーマンス、信頼性、セキュリティ、ユーザビリティ、保守性） — この機能が含意する各属性について、§Implementation Decisions に SMART 基準（Specific、Measurable、Attainable、Relevant、Time-bounded）を記載するか、対象外と宣言してください。テストを書けない場合、要件はエージェントがたまたま実装した内容に委ねられます。曖昧な懸念は、テスト可能な基準に置き換えてください。「バックエンドのパスを監視する」→「すべてのバックエンドのパスで、request_id、latency_ms、outcome を含む構造化ログイベントを出力する。スライス X のログキャプチャ統合テストで検証する」。「破損した状態を黙って伝播させず、速やかに失敗させる」→「統合ポイント X でスキーマ検証に失敗した場合、writer は 50ms 以内に例外をスローする。スライス Y の不正な行を強制するテストで検証する」。「機能の処理速度が十分である」→「同時ユーザー 100 人で検索レイテンシの p95 が 200ms 未満。スライス X の負荷テストで検証する」。docs/solutions/ に、この機能が触れるモジュールで過去に発生した不具合の集中が示されている場合、SMART 基準は、過去の不具合を検出できたはずのアサーションまたは監視でなければなりません。（各オブザーバビリティ AC について、呼び出しを出力するファイルまたは手順を明記し、そのファイル／手順から SDK にアクセスできることを確認してください。出力箇所が、サーバー側だけで使える SDK（サーバー側に保持された認証情報を読み取るもの、または Node 専用ランタイムを必要とするもの）にアクセスするクライアントコンポーネントの場合、AC を上流のサーバー境界に移すか、クライアントからサーバーへのルートをスコープに追加する必要があります。移動先がすぐに明らかでない場合は、これを未解決事項として扱い、1 行で解決策を示してください。SDK の型シグネチャはコンパイルできる内容の上限であり、SDK が実際に出力できるランタイム境界は実行可能な内容の下限です。）
  • 信頼境界 — 信頼境界とは、データフローの両側を異なる主体が制御する箇所です（ブラウザー↔サーバー、サーバー↔サードパーティ API、Webhook 送信元↔受信先、アップロード↔パーサー、LLM 出力↔その出力に基づいて動作するあらゆるもの）。機能によって追加または変更される境界をそれぞれ示し、境界ごとに脅威とその緩和策を 1 つ記載してください（例：「呼び出し元から ID を受け取り、読み取り前に所有者を確認する」）。それぞれを、対象スライスに対する 2 つのテスト（緩和策がない場合を悪用するテストと、緩和策の回避を試みるテスト）を含む AC にするか、1 行の解決策を示した未解決事項にするか、対象外と宣言してください。対象外とする場合、ユーザーに代わってリスクを受け入れてはなりません。境界がない場合は、一度だけ「なし」と記載してください。
  • データベースのマイグレーションまたはスキーマの変更
  • 読み込み中、空、部分表示の状態（UI 機能）
  • 既存レコードのデータ補完またはマイグレーション
  • デプロイまたは環境の変更（新しい環境変数、フィーチャーフラグ）
  • 置き換えるコードパスのクリーンアップ
  • この変更が影響する可能性のある既存機能のエッジケース
  • API コントラクトへの影響：リクエスト／レスポンスの形式変更、追加と破壊的変更のリスク、認証またはスコープの変更、Webhook の検証、開発者向けエラーコントラクト 該当する省略カテゴリごとに、ユーザーストーリーに追加するか、解決策を明記した Rabbit Hole として挙げるか、No-go として宣言してください。見えないままにしないでください。

この機能によって重要な API コントラクトが変更または導入され、インタビュー後もコントラクトの形がまだ十分に明確でない場合は、ピッチを確定する前に /api-design-review を実行してください。

不足している項目があれば、インタビューに戻ってギャップを解消してください。

7. モジュールを設計する

実装を完了するために構築または変更が必要な主要なモジュールを概略化してください。個別にテストできる深いモジュールを抽出できる機会を積極的に探してください。

深いモジュールとは、浅いモジュールとは異なり、シンプルでテスト可能なインターフェースに多くの機能をカプセル化し、そのインターフェースがほとんど変更されないモジュールです。

複雑な内部状態を持つ各モジュールについて、違反すると即時の失敗ではなく、気づかれないままデータが破損するような重要な不変条件を特定してください。これを Implementation Decisions セクションに記載してください。実装担当者は、その不変条件に対する事前条件または isValid() チェックを追加してください。

説明文に挙げたすべての仕組みに、必ず置き場所を用意してください。 このステップを終える前に、§Solution と Must-haves のフロー行を確認し、そこで挙げた仕組み（各データ構造、事前計算された入力、バックグラウンドジョブ、キャッシュ、シードされた状態）を一つずつ取り上げてください。それぞれに、次の4つの処遇のうち、ちょうど1つを割り当ててください。ここに Modules の項目として記載する、解決策を明記した Rabbit Hole として記載する、No-go の行を設ける、または独自の Must-have ストーリーにする。

4つ目は、作成者が見落としがちな選択肢です。前提条件は、別の目標の一部ではなく、それ自体が完全なユーザー目標である場合があります。Cockburn が挙げているのは、「ビデオをレンタルする」ことを望む顧客が、その前に「会員登録する」必要があるケースです。Cockburn がこれを取り上げるのは、執筆者がこれを誤った階層に「修正」しないようにするためです（第5章）。仕組み自体がユーザーの達成しようとしていることであれば、ストーリーに昇格させてください。そうすることで、/prd-to-issues のステップ5にある、対応づけられていない Must による停止条件に含められます。説明文で言及されている仕組みに4つの処遇のいずれも割り当てないと、その仕組みは後続工程から見えなくなります。ステップ4では、固定されたコントラクトの形を確認するために §Implementation Decisions を読むため、モジュールのない仕組みは境界マップの導出で検出されません。

これらのモジュールが期待に合っているか、ユーザーに確認してください。どのモジュールについて、どの境界でテストを書いてほしいかもユーザーに確認してください。

モジュールのインターフェースにユーザーが確信を持てない場合、または実質的なトレードオフを伴う複数の有力な設計案がある場合（例：すべてを行う1つのメソッドか、組み合わせ可能な3つのメソッドか、コールバック API かイベントエミッターか）は、並列サブエージェントを使って大きく異なる選択肢を2～3案生成するために /design-an-interface を実行してください。トレードオフとともに各案を提示し、ユーザーに選んでもらってください。インターフェースが明白な場合や、ユーザーに明確な希望がある場合は、これを省略して先に進んでください。

不確実なのが API コントラクトそのもの（パラダイムの選択、リクエスト／レスポンスの形、Webhook のモデル、認証モデル、互換性の方針）である場合は、通常のモジュールインターフェースの検討として扱わず、代わりに /api-design-review を実行してください。

8. ピッチを書く

問題と解決策を十分に理解し、形にできたら、以下のテンプレートを使ってピッチを書きます。保存先はプロジェクトによって異なります。

まず、PRD の保存場所を確認します。 references/state-backend.md に記載のとおり、backend prds で確認できます。

SC="<this skill's directory>/references/sidecar.sh"
BACKEND="$(bash "$SC" backend prds)" || BACKEND=
case "$BACKEND" in
  github)  echo "prds backend: github" ;;
  sidecar) echo "prds backend: sidecar" ;;
  *)       echo "prds backend: refused; stop and relay the stderr above" >&2; exit 1 ;;
esac

• github：以下の手順に従い、ピッチを GitHub イシューとして登録します。
• sidecar：ピッチを GitHub イシューではなく、サイドカーの作業項目として保存します。以下の サイドカーへの保存 のブロックを実行し、プレースホルダー行をテンプレートの本文に置き換えます。GitHub イシューもマイルストーンも作成しません。テンプレート末尾の 次のセッション の行は、work create が ID を出力するまで ID が存在しないため、本文には保存しません。#<n> ではなく、/prd-to-issues W-<n> としてユーザーに出力します。
• その他（終了コードが 0 以外で、何も出力されない場合）：処理を停止し、backend が標準エラー出力に表示した内容を伝えます。gh issue create にフォールバックしてはいけません。ゲストリポジトリでは、ピッチがクライアントのトラッカーに登録されてしまいます。

サイドカーへの保存。 以下の各ブロックは自己完結しています。ツールを呼び出すたびに新しいシェルが起動するため、各ブロックで SC と本文ファイルを設定し、上記の backend ブロックから引き継がれるものはありません。プレースホルダー行をテンプレートの本文に置き換え、MILESTONE にはステップ 2 で確認した名前を設定するか、空のままにします。このブロックは新しい ID W-<n> を出力します。

SC="<this skill's directory>/references/sidecar.sh"
MILESTONE=""
f="$(mktemp)"
cat > "$f" <<'PITCH'
<the pitch body, from the template below>
PITCH
set -- --kind prd
if [ -n "$MILESTONE" ]; then set -- "$@" --milestone "$MILESTONE"; fi
bash "$SC" work create "$@" --body-file "$f"

入力が research-ready の作業項目だった場合は、別の項目を作成せず、既存の項目をその場で展開します。ID を ID に設定します。

SC="<this skill's directory>/references/sidecar.sh"
ID="W-<n>"
f="$(mktemp)"
cat > "$f" <<'PITCH'
<the pitch body, from the template below>
PITCH
bash "$SC" work edit "$ID" --body-file "$f" && bash "$SC" work set "$ID" maturity prd

ステップ 2 でコンテナマイルストーンがリクエストされており、バックエンドが github の場合は、PRD イシューを作成する前にマイルストーンを作成し、そのイシューを関連付けます。

1. マイルストーンを作成します：gh api repos/{owner}/{repo}/milestones -f title="<Milestone Name>" -f description="<1-2 sentences from the problem story>"
2. --milestone "<Milestone Name>" を指定して PRD イシューを作成し、マイルストーンに関連付けます
3. ピッチの出力にマイルストーン名を記載し、/prd-to-issues がスライスイシューに引き継げるようにします

問題

現状がなぜ機能しないのかを示す具体的なストーリーです。登場人物は 1 人、試みは 1 回、失敗は 1 回です。抽象的な不満ではなく、苦痛が具体的に伝わる場面にします。

投資規模

小規模（1～2 週間）または大規模（6 週間）です。この問題にこの予算を割くのが適切な理由、つまり、この投資に見合う価値があり、それ以上は必要ない理由を説明します。

この投資規模は、この問題にかける価値がある時間の目標であり、現時点での期間の見積もりでも、納期のコミットメントでもないことを明記します。

目標／見積もり／コミットメント

［タイムライン、スコープ、または納期のプレッシャーがある場合に記載します。意味のある時間的な議論がない場合は省略します。］

• 目標：［望ましいビジネス成果、イベント日、または予算上の境界］
• 現時点での見積もり：［幅、または確度の段階。精度を装った単一の数値は避けます］
• コミットメントの姿勢：［現時点ではコミットメントなし／X が解決した後に条件付きでコミット／明確にコミット］

不確実性／確度

［タイミングやスコープに関する確度がピッチに大きく影響する場合に記載します。時間的なプレッシャーが低い検討作業では省略します。］

• 現時点での確度：［高／中／低］
• 主な不確実性の要因：［見積もりの精度を高める前に、学習または決定が必要なこと］
• 確度を高めるために必要なこと：［プロトタイプ、調査の回答、最初のトレーサーバレット、契約上の決定など］

解決策

形を定めたコンセプトです。実装者が判断を下せる余地を残すため、ある程度の粗さを保ちます。大枠の方向性は明確にし、深追いすべきでない論点には手当てをしておきます。上記の意欲の範囲内に収めます。

ユーザーの視点から、何が変わるのかを説明します。有用な場合は、アーキテクチャレベルでアプローチを説明しますが、実装者に委ねるべき実装の詳細までは指定しないでください。

問題に明確な構造的要因がある場合は、ここで簡潔に述べてください。このアプローチが、最も近い症状だけでなく、問題を引き起こしている状況に対処する理由を説明できる程度で十分です。

ライブラリが提供するコールバック（エージェントフック、ミドルウェア、ライフサイクルメソッド、ツールハンドラー）を使って解決策を設計する場合は、research.md（Phase 1.25）のライブラリコールバック契約スナップショットをファイル名と行番号で引用してください。X と Y が承認済みの戻り値の形式にそのまま記載されていない限り、「X 経由で注入する」や「Y を渡す」といった仕組みを説明しないでください。ライブラリの .d.ts に存在しない仕組みを想定することは、/research の Phase 1.25 が防ごうとしている乖離の典型です。

[図の提案：解決策セクションを終える前に、上記の内容を図（フローチャート、シーケンス図、アーキテクチャ図、状態遷移図、決定木、または変更前と変更後の比較）にすると、より分かりやすくなるか検討してください。リストと本文が正式な情報であり、図は /prd-to-issues による分解や /execute のコールドスタートセッションで読みやすくするための補助です。図が有効なら /mermaid を呼び出してください。読者がざっと目を通す企画書の内容全体を図にする場合（単なる挿入図ではない場合）は、/visual-recap が PRD を先へと展開し、この企画書で確定した内容を示す決定カード、未決の分岐を比較する選択肢の比較図、そしてこの図を、単一の一時的な HTML ファイルとして生成します。これは任意であり、自動では呼び出されず、PRD の要件でもありません。いずれの場合も、課題本文が信頼できる情報源であることに変わりはありません。解決策が短く直線的で、本文がすでに最も明快な表現になっている場合は省略してください。判断基準は、コードベースに詳しくない読者が、図がない場合よりも図がある場合のほうが早く全体像を把握できるかどうかです。この指示は、条件付きのフロー行の中ではなく、解決策の末尾に配置されています。これにより、解決策が UI フロー、アーキテクチャ、リファクタリング／置き換え、状態遷移のいずれの形式であっても実行されます。これまでの Flow Sketch を条件としたトリガーと、chrislacey89/skills#90 で提案されたリファクタリング／置き換えのトリガーを統合し、形式に依存しない単一の指示としています。]

深追いすべき論点

名前を付けたリスクと、あらかじめ決めておいた一行の解決策です。検討しないままにしておくと、6 週間のプロジェクトが 18 週間かかる原因になり得る未知の要素を指します。ここで名前を挙げて解決策を示しておけば、実装者が期限に追われながらこうした判断を下す必要はありません。

• [リスク名]：[一行の解決策]

対象外

明示的な除外事項です。記載がなければ「対象範囲内」とみなされるため、実装者が含まれると合理的に想定し得るものの、実際には含まれないものはすべてここに記載する必要があります。これらは「いずれ対応するかもしれない」項目ではなく、意図的に定めた境界です。

• [明示的に対象外とするもの]

ユーザーストーリー

必須項目

1. [アクター]として、[機能]を実現したいです。[メリット]を得るためです。
   • [場所の名前]：[操作要素 1]、[操作要素 2] -> [その他の場所]に接続
   • [その他の場所]：[操作要素 3] -> ... に接続

[インデントされた行はフロー行であり、条件に応じて含めます。この機能に複数ステップのユーザー向けフロー、新しいナビゲーション、または大幅な UI 状態の変更がある場合にのみ含めてください。API のみ、バックエンドのみ、または単一画面の変更の場合は省略します。実現する各必須項目の下に行を繰り返し記載してください。どの項目も実現しない行は、以下の共通の操作要素に記載します。]

あれば望ましい項目（~）

1. ~[アクター]として、[機能]を実現したいです。[メリット]を得るためです。

共通の機能（未帰属）

[フロー行が存在し、かつ、どの行も単一の Must に対応していない場合にのみ含めてください。ナビゲーションの枠組み、読み込み中や空の状態、グローバルなエラー表示などが該当します。これらは確約ではありません。/prd-to-issues は、これらを未マッピングの Must として扱いません。すべての行に親が見つかった場合は、見出しごと省略してください。]

ストーリーの範囲はアペタイトによって定まります。Must-have は出荷可能な最小バージョンを定義します。つまり、今日のユーザーのベースラインよりも優れたものにする要件です。Nice-to-have は、事前に承認された削減対象です。アペタイトが厳しくなれば、議論することなくスコープから削られます。prd-to-issues は各垂直スライスをこれらのストーリーに対応付け、Must にフロー行がある場合は、機能単位の粒度で対応付けます。

API 契約の概要

[機能によって API 契約が導入または変更される場合にのみ含めてください。実装の詳細ではなく、利用者の視点に立った簡潔な内容にしてください。]

• 問題の説明： [この API が解決する開発者の問題]
• 効果の説明： [この API によって実現できること]
• 利用者： [この API を統合する人]
• 操作： [利用者が API で実行できる必要のあること]
• インターフェースの概要： [エンドポイント／イベントの概要]
• 重要なフィールド： [利用者にとって重要な必須／任意項目とデフォルト値]
• エラー形式： [機械可読コードと人間が読めるメッセージ]
• 互換性： [追加的／破壊的変更の可能性あり／破壊的変更]
• その他に検討した案： [採用しなかったパラダイムや契約の方向性]

実装上の決定事項

決定した実装上の事項を列挙します。以下を含めることができます。

• 構築または変更するモジュール
• 変更するモジュールのインターフェース
• 開発者による技術的な明確化事項
• アーキテクチャ上の決定
• スキーマの変更
• API 契約
• 具体的なインタラクション

実装の断片（ループ本体、エラー処理、ヘルパー関数の内部、設定文字列リテラル）は含めないでください。ビルダーが判断を下した時点で、すぐに内容が古くなるためです。

[このセクションは読者がざっと目を通す場所です。箇条書きでは、どの決定が何かを選択肢から排除するのかが示されないためです。ワイヤーフォーマット、公開 ID、所有権の境界、データモデルの形状など、選択肢を限定する決定がある場合、/visual-recap はそれらを決定カードとして表示できます。カードには「決定事項」「除外される選択肢」「見直し条件」「出典」を含め、各項目をこの本文から引用するか、明示的に断定事項として示します。これは任意で一時的なものであり、ここに決定を書き留めることに代わるものではありません。]

PRD の決定がインターフェースレベルにある場合は、固定された契約の形をコード形式で必ず記載してください。たとえば、スキーマのカラム一覧（Drizzle、Prisma、SQL DDL）、エクスポートされる型エイリアスやインターフェース、エクスポートされる関数シグネチャ、構造化された入力／出力スキーマ（Zod、JSON Schema）などです。判断基準は実証的です。下流のパイプラインのステップ（/prd-to-issues の Boundary Map、/execute の Consumes 検証、/pre-merge の境界契約レビュー）がこの識別子や形を検索するなら、それは契約の形であり、コードとして記載します。下流のステップでそのまま引き継がれないなら、実装の詳細であり、文章で記載するか、省略します。契約の形を示すコードも、PRD の再交渉プロセスと同じ頻度で変わります。他の PRD の内容を変更する場合と同じ手順で、PRD 本文を編集し、Coverage Matrix を再生成してください。

調査リファレンス

[該当する調査成果物がある場合のみ記載してください。プロジェクトの research.storage モードに合った形式を使用してください。アーカイブモードでは、§ 4 の一覧に出力された絶対パスを記載してください。]

スパイク課題モード（存在する場合は優先）：

この機能の技術調査は、スパイク課題 Refs #<spike-issue-number>（作成時点のスナップショットとしてクローズ済み、research ラベル付き）に記録されています。主な推奨事項：

• [調査に基づく推奨アプローチ]
• [調査に基づく主な制約またはトレードオフ]

実装担当者は作業開始前にスパイク課題を確認してください（どのマシンでも gh issue view <spike-issue-number> を実行できます）。

アーカイブモード（スパイク課題がない場合の代替）：

この機能の技術調査は、<absolute path to the research entry>（リポジトリ外）に記録されています。主な推奨事項：

• [調査に基づく推奨アプローチ]
• [調査に基づく主な制約またはトレードオフ]

実装担当者は作業開始前に調査ドキュメントを確認してください。記載されたパスはリポジトリ外にあります（/research のフェーズ 5c に場所が記載されています）。そのため、調査を実施したユーザー以外は開けません。複数マシン、複数のコントリビューター、または一般公開向けの PRD では、プロジェクトをスパイク課題モードに切り替えてください（/research のフェーズ 5a を参照）。

過去の解決策から得た教訓

[関連する docs/solutions/ ファイルが見つかった場合のみ記載してください]

以下の記録済みの解決策を、この提案の作成に活用しました：

• docs/solutions/<path> — [適用した教訓]

---

次のセッション： /prd-to-issues #<this-issue-number> 入力： PRD 課題の本文

この課題に対して /execute を直接実行しないでください。これは形を整えた提案であり、作業単位ではありません。次のセッションを課題番号の検索ではなくコピー＆ペーストで開始できるよう、課題番号を明示的に出力してください。

引き継ぎ

• 想定される入力： 明確化されたユーザーの問題、/research で検証された技術的背景、および機能に関連する過去の解決策からの指針
• 生成物： アペタイト、解決策、検討の深掘りを避ける項目、対象外事項、および必要に応じた契約の草案を含む、形を整えた PRD 課題（大規模な一括作業の場合は、コンテナマイルストーンに任意で関連付け可能）。サイドカーバックエンドでは、代わりに W-<n> サイドカー作業項目を生成し、マイルストーンはフィールドとして記録します。
• 呼び出す場合があるもの： モジュールインターフェースが未解決の場合は /design-an-interface、API 契約に不確実性が残る場合は /api-design-review
• デフォルトで次に実行するもの： /prd-to-issues