write-prd

PRD の作成

docs/specs/<feature-slug>/_prd.md を作成します。これは、後続のパイプライン（write-techspec、write-tasks、implement-task、qa-gate）が実装の基準とするプロダクト定義です。PRD が定義するのは 何を、なぜ であり、技術仕様が定義するのは どのように です。この境界を保つことで、コードがその下で変化しても、各成果物を小さく、内容に忠実に保てます。

入力

$ARGUMENTS は機能の説明です。現在の会話ですでに機能を検討済みの場合（掘り下げやブレインストーミングのセッション）は空です。会話ですでに回答された内容はすべて回答済みとして扱い、再度質問しないでください。

docs/specs/<slug>/_idea.md が存在する場合（write-idea によって作成されたもの）、それが検討内容です。まず読み込み、そこに記載された調査、評価、トレードオフに関する知見、選択した方向性、Out of Scope リストを、回答済みの確定事項として扱ってください。アイデア文書で未解決の点だけを確認してください。

最初に規模を見極める

変更のすべてに PRD が必要なわけではありません。記録すべきプロダクト上の判断があり、そこから複数のタスクを導出する場合に、PRD は作成コストに見合います。作業によってプロダクトの動作が変わらない場合（リファクタリングやバグ修正）は、その旨を伝え、パイプラインに直接進んで最小限の _prd.md とともに仕様フォルダーを作成する write-techspec に案内してください。変更がごく簡単な場合（1 行の修正、誤字、設定の微調整）は、仕様フォルダーを作らずに直接実装することを勧めてください。

基本ルール

• 何よりも先に CONTEXT.md と docs/adr/ を読みます。 用語集の語彙を、タイトル、ユーザーストーリー、機能名など全体で使用し、用語集の Avoid にある同義語に置き換えないでください。概念にまだ用語がない場合は、ユーザーと一緒に明確な用語を決め、その場で用語集に追加してください。曖昧な言葉で書かれた PRD からは、曖昧なタスクが生まれます。いずれかのファイルが存在しない場合は、何も言わずに続行してください。
• 決定してから書きます。 調査と確認が終わったら、ファイルに直接書き込み、完成した成果物をユーザーに確認してもらってください。承認を求めるためのアウトライン案は提示しないでください。実際の PRD をレビューする方が、作成予定のものを確認するよりも迅速です。
• 永続性。 docs/agents/ のプロジェクト制約の根拠と、ツールによる認可の対象となる正確なファイルを除き、ファイルパス、コードスニペット、行番号は記載しないでください。PRD はコードベースが変わる間、何週間も保留になる場合があります。リファクタリング後も変わらない、動作とインターフェースを記述してください。

根拠の記録

段落内で判断記録を根拠として動作を説明する場合は、その段落に Claim Receipt を追加してください。記録の識別子またはリポジトリパス、コロン、そして半角ダブルクォーテーションで囲んだ一字一句そのままの引用を記載します。Spec Consistency Check は引用を原文と照合するため、正確にコピーしてください。このチェックでは引用の有無を確認し、根拠の評価は読者に委ねます。

用語集の宣言

PRD で用語集に定義のない概念に言及する場合は、自律実行の場合も含め、執筆前にドメインモデリングを開始し、その用語を明確にしてください。PRD には references/glossary.md の ## Glossary セクションを含めます。新しい用語は、初出箇所で太字にします。執筆を担当者が進める場合は、grilling または grill-with-docs を引き続き対話型の開始方法とします。

同じコンテキストを共有するソース

Spec では、コンテキストが類似または補完関係にある複数の Inbox Entry、Backlog Entry、Finding を採用できます。ソースごとに Spec を 1 つ作成する必要はなく、推奨もされません。Spec を新規作成する前に、コンテキストを共有するソースがないか、未完了の Backlog Entry と未解決の Finding を確認してください。実装 Task 4 件とその QA ゲートに収まる範囲でのみグループ化し、それを超える場合はスコープを分割して、各ソースに 1 つの所有 Spec を割り当てます。

新しい Finding または Backlog Entry を作成する前に、適合する既存のものを拡張してください。未完了の Backlog Entry はその場で改訂するか、未解決の Finding に日付入りの追記を加えます。

roundfix spec judge が候補のペアを表示した場合は、候補ごとに、範囲内で未完了のソースを採用するか、レポートで別々に扱う理由を述べてください。候補の提示はゲートにはなりません。また、候補が表示されなくても、適合するものがないとは限りません。コンテキストを共有する未完了のソースを引き続き確認してください。

プロセス

1. 保留中のインボックスを読む

上記の基本ルール関連ドキュメント、すなわち CONTEXT.md と有効な ADR を読んだ後、調査を始める前に、設定済みのナレッジワークスペースのワークフローを通じて、brain 側の inbox/<repository>/ 名前空間にあるリポジトリの保留中の Inbox Entry を読みます。キューに入った証拠と意図をプロダクトの意思決定への入力として扱い、Triage は対象リポジトリのセッションに委ねます。

2. 調査

何か質問する前に調査してください。コードベースを調べれば答えられる質問でユーザーの時間を無駄にしてはいけません。

• 変更が影響する既存の動作と関連機能。
• docs/specs/ と docs/history/specs/ にある過去の Spec。すでに実装済みまたは計画済みの項目との重複は、暗黙に取り込むのではなく、報告すべき Finding です。
• 機能がユーザー向けで、位置付けが重要な場合は、ウェブ調査による市場や競合の状況。

明確化の前に、リポジトリのセマンティックガイドから有効な Project Constraints を確認します。

• docs/agents/domain.md は識別子の指針を定め、有効な ADR の検出先を案内します。
• このガイドがないリポジトリでは、対象のサーフェスのポリシーを定めるガイドを参照します。
• docs/agents/backend.md は認証と HTTP のポリシーを定めます。
• docs/agents/agent-instructions.md はツールの権限を含む、普遍的な Normative Clause を定めます。
• docs/agents/spec-routing.md は Spec ワークフローの契約を定めます。

存在するパスをすべて読み、有効な決定値にたどり着くまでリンクを確認します。推奨される既定値を推測したり、ガイドがないことを許可と見なしたりしてはいけません。完成したスナップショットでは、該当するものについて、識別子の方針、認証と HTTP、有効な ADR の要件、ツールの権限を「該当」または理由付きの「非該当」に分類し、各項目の根拠となる docs/agents/ のパスを記載する必要があります。

3. 明確化

人が作成を主導する場合は、対話の入り口としてグリリングを使い、すでに得られた回答を保持します。人が参加していない場合は、利用可能なソースから質問への答えを導き、その方法を Clarification Record に記載してください。インタビューを捏造してはいけません。references/clarification-record.md に従ってください。

人が参加している場合は、1 メッセージにつき質問は 1 つとし、選択肢を列挙できる場合は複数選択式にしてください。

Which failure behavior should an expired import have?

A) Retry automatically up to 3 times (Recommended) — preserves the sync retry behavior.
B) Fail fast and notify the user — surfaces the failure immediately without another attempt.
C) Park it for manual review — keeps the import available for an operator to resolve.

セッションで利用できる構造化質問ツールを使って質問します。利用できない場合は、チャットに同じ質問を 1 つだけ表示し、自由回答を受け付けます。既定の推奨案と、その理由を一文で必ず示してください。重要度の高い順に、目標と成功基準、機能スコープ、非目標、制約、リスクを確認します。残る不明点によって実装内容が変わらなくなった時点で、質問を終了してください。

4. 判断を記録する

「## Decisions」の下に確認記録を記述します。質問に人が回答した場合は、質問ごとに次の形式で1行記述します。 - YYYY-MM-DD: <question> — <answer> 日付には実際の回答日を使用します。または、次の形式で、作成者が判断の根拠とした情報源を示します。 Autonomous route: no person present; decisions taken from <source>. 両方の形式が混在してもかまいません。 SC-DECISIONS-UNRECORDED は、ガイドに定められた追加コミットの対象範囲内で、PRD の段階にどちらの形式も記録されていない場合に報告します。このチェックでは形式のみを読み取ります。

元に戻すのが難しく、文脈がなければ意外であり、実際のトレードオフの結果であるプロダクト上の判断は、docs/adr/NNNN-slug.md に ADR として記録し、リポジトリの番号付けを引き継ぎます。文脈、判断、理由を1～3文にまとめます。この3要件を満たさない判断は、PRD 本文に記載するだけにします。

5. Spec フォルダーを準備し、根拠とする情報源を取り込む

取り込みとは、実装を約束する Spec に情報源のドキュメントを移すことです。手順6のルールに従って番号付きスラッグを決め、最初に移動する前に mkdir -p docs/specs/<slug>/references を実行します。判断を記録した後、PRD の作成前に、以下の手順を順番に実行します。

1. 棚卸し。 PRD が内容を根拠とする受信トレイのメモ、調査結果、バックログ項目をすべて一覧にします。背景情報としてのみ引用されているドキュメントは取り込みません。

2. 分類。 元の受信トレイのメモが資料の場合は、そのまま移動できます。観察された挙動を記録したメモは現場の証拠として扱い、まず調査結果に昇格させてから、その調査結果を取り込みます。この Spec が実装するバックログ項目は、backlog として取り込みます。項目を移動するのと同じ変更で、その項目の status: promoted と spec をこの Spec のスラッグに設定し、項目自体のフロントマターとインデックスを一致させます。

3. 所有権を確定。 docs/specs/ と docs/history/specs/ の両方を検索し、既存の所有者を確認します。共有する情報源を所有する Spec は1つだけです。最初に実装を約束した Spec が所有者となります。2つ目以降の Spec は所有者が取り込み後に保持するコピーへのリンクを張り、何も取り込みません。 所有者のアーカイブ時にはアーカイブ再リンクを行い、そのコピーを docs/references/ に昇格させて、2つ目以降の Spec のリンクを書き換えます。これにより、情報源の所有者は1つのままとなり、2つ目以降の Spec にコピーは不要です（ADR-0260、ADR-0083）。

4. 事前確認。 所見のステータスを変更する前、インデックスを書く前、または情報源を移動する前に、取り込むすべての情報源のベース名と移動先を docs/specs/<slug>/references/ 以下で確定します。_index.md は予約済みのベース名です。このベース名の情報源を取り込むことはできません。同じベース名の情報源が複数ある場合は拒否し、シンボリックリンクを含め、移動先のパスがすでに存在する場合は処理を中止します。取り込み状態を変更する前に、棚卸し対象全体の確認を完了します。

5. インデックス。 最初にステータスを更新する前、または情報源を移動する前に、完全な _index.md を記述します。取り込む情報源ごとに、以下の固定形式の Markdown テーブルに1行追加します。

   # Adopted sources
   
   | source | type | owner | adopted date | path |
   | --- | --- | --- | --- | --- |
   | docs/findings/2026-07-25-example.md | finding | 0060 | 2026-07-30 | 2026-07-25-example.md |
   

   source は導入前のリポジトリパスで、更新されません。これは来歴の記録です。type は、ソースが inbox、finding、backlog のいずれであるかを示します。 owner は、所有者となる4桁の Spec 番号です。adopted date は導入日で、path は _index.md からの相対パスなので、Spec がアーカイブされた後も有効です。続行する前に、インデックス全体を検証してください。固定ヘッダー、インベントリに記載されたソースごとの完全な行、重複しない source と path の値、有効なタイプ、所有者、日付の値を必須とし、各 path が source のベース名と一致することを確認します。この検証済みインデックスを最初に作成することで、中断された導入が archive-spec から認識できるようになります。archive-spec は、インデックスに記載された不完全な Spec をレガシーとして扱わず、拒否する必要があります。

6. 切り替えてからリンクする。 finding を移動する前に、そのフロントマターの status: done を設定し、updated_at を更新して、同じ変更内で所有者となる Spec へのリンクを記録します。この順序により、Git 履歴内の以前のパスでステータスと参照先が確認できます。

7. 移動する。 インデックスに記載されたソースごとに、git mv <source> docs/specs/<slug>/references/<basename> を一度実行します。コピーやスタブではなく、移動を一度だけ行ってください。移動によってベース名とすべてのバイトが保持されます。その後、手順8では、移動したソース内の Markdown リンク先のみを変更できます。観察内容やその他のソースコンテンツを書き換えてはいけません。

8. 書き換えて確認する。 リポジトリ内で、各旧パスへのリンクを検索します。自動リンク書き換えの対象から docs/history/specs/ を除外してください。アーカイブされた Spec は変更不可の履歴アーティファクトです。アーカイブされた Spec からのリンクは、明示的なポリシー確認のために別途報告してください。それ以外のリンク元ファイルでは、リンク先をそのファイルからの相対パスで導入後のパスに書き換え、書き換えたすべての Markdown リンク先が解決できることを確認します。導入したソース内のリンク先も対象です。バイトを保持した移動の後に変更できるのは、Markdown リンク先のみです。導入したソースが source パスに残っている場合、または書き換えたリンクのいずれかが解決できない場合は失敗とし、完了を報告しないでください。問題のあるソースまたはリンクを示し、スキップした導入手順を繰り返してください。

6. 作成

厳守事項 — 仕様フォルダーは docs/specs/NNNN-<kebab-slug>/ の形式で番号を付けます（4 桁のゼロ埋め。例：0001-implement-command）。docs/specs/ と docs/history/specs/ の両方を調べて、既存の最も大きい番号に 1 を加え、NNNN を決めます。仕様がどこにも存在しない場合は 0001 を使います。番号は再利用せず、アーカイブ時も仕様とともに維持します。番号なしの仕様フォルダーは作成しないでください。この PRD の元になった _idea.md がある場合、そのフォルダーにはすでに番号が付いているため、その番号を再利用し、新しい番号を付けないでください。

手順 5 で準備した仕様フォルダーに、references/prd-template.md のテンプレートを使って _prd.md を作成します。この PRD の元になった _idea.md がある場合は、そのフロントマターの status を promoted に変更します。下流のスキルが解析するため、PRD のフロントマターは慎重に設定してください。

• spec — フォルダーのスラッグです。
• status: active — 仕様が完了した時点（すべてのタスクが完了し、QA に合格した時点）で、archive-spec によって archived に変更されます。
• surfaces — 機能が関係するすべてのサーフェス（frontend、backend、cli、data、infra、docs）です。qa-gate はこのリストに基づいてブラウザーを使った QA を振り分けます。そのため、frontend を記載しないと、ブラウザーによる検証を行わずに機能がリリースされます。

Success Metrics は、番号付きの Success Metric 項目として記載するか、該当する項目がない理由を添えて、単一の項目 None. として記載します。番号付きの各メトリクスは、下流の仕様カバレッジで名前と番号を使って参照できるようにしてください。

Project Constraints は本文の内容であり、フロントマターには記載しません。PRD で、保護対象のツール設定、スクリプト、ignore ファイル、プラグイン宣言、またはバージョン固定の作成、編集、名前変更、移動、削除を提案する場合は、メンテナーから明示的な承認を得るまで作業を停止してください。その承認と、対象を限定した正確なファイルの一覧を Tooling authority の行に記録します。一般的な実装依頼、セットアップの完了、沈黙、または対象ファイルが限定されていない承認は、変更の許可にはなりません。正式な記録は <spec-root>/<slug>/_authorization.md に置きます。proposed の記録、または許可日が記載されていない記録は、いずれも許可として認められません。したがって、正式な許可が存在するまでは、保護対象のツール作業を分解フェーズに進めないでください。新規または範囲を拡大した許可は、それを適用する squash デリバリーより前に、対象の履歴上流に反映されている必要があります。許可または変更承認は、それが許可する変更とは別に保持してください。

7. 報告

報告する前に、完成した成果物を読み直してください。Project Constraints が存在し、4 行すべてに該当するか該当しないかとその理由が記載され、各行が有効な docs/agents/ の情報源を引用し、保護対象のツールに変更を加えた場合は、明示的なメンテナーの承認と対象範囲を限定したファイルが記録されていない限り、完了を報告したり、次のパイプラインステップを推奨したりしてはいけません。承認はフロントマターに記載しないでください。

Delivery Queue が提供するすべての Spec には、保護対象のツールが関係するかどうかにかかわらず、承認済みの _authorization.md が必要です。その記録の operations リストには implement、commit、push、pull_request、merge を記載してください。Governed Path を一切変更しない Spec では、paths: [] を記録してください。

次に、成果物を作成したステージに対してチェッカーを実行してください。

roundfix spec check <slug> --stage prd --run-verification

エラーレベルの指摘、またはチェッカーの実行失敗がある場合は、報告を行ってはいけません。PRD を修正してコマンドを再実行してください。どちらかが解消されていない間は、完了を報告したり、次のパイプラインステップを推奨したりしないでください。

PRD ステージのチェック結果に問題がなくても、Spec が完全に網羅されているとは限りません。このステージでは、TechSpec のカバレッジマッピングやその Vocabulary Contract、Task Graph の ADR の記録、タスクのカバレッジ、コンテキスト参照、検証の独立性、要件の矛盾、リハーサルの宣言、コミットに依存する変更パスの範囲、まだ機械的に検証できないルール、製品目標が正しいかどうかは判断しません。これらの種類の確認は、後続の作成ステージ、全体を対象としたスコープなしのスイープ、QA で引き続き行います。チェッカーがスキップ対象として挙げた検出器は、問題なしと見なさず、省略されたものとして扱ってください。

ファイルパス、明確化後も残っている未解決の質問、および次のステップを回答してください。アーキテクチャ上の判断が必要な機能では write-techspec、技術的なアプローチがすでに明らかな場合は直接 write-tasks を指定してください。

アドバイザリー判断

roundfix spec check <slug> --stage prd --run-verification の結果に問題がなく、報告する前に、roundfix spec judge <slug> --stage prd を実行してください。判断指摘が提示された場合は、それぞれについて、成果物を修正してチェッカーを再実行するか、記述を変更せず、なぜそのままにするのかを報告に記載してください。judge は助言を行うものであり、ゲートではありません。スキップ結果は失敗でも問題なしの結果でもないため、スキップの理由を報告して続行してください。Jev キーを表示、保存、または要求してはいけません。対象となるキーは次のとおりです：ROUNDFIX_OPENROUTER_JUDGE_API_KEY、ROUNDFIX_OPENROUTER_API_KEY、ROUNDFIX_TYPESAFE_API_KEY。

アンチパターン

• PRD に技術設計を書くこと。スキーマ、エンドポイント、パッケージ構成は _techspec.md に記載します。
• 会話やコードベースですでに回答されている内容を再度尋ねること。
• 1 回のメッセージで複数の質問をすること、または選択肢を列挙できるのに自由回答形式の質問をすること。
• 文書を完全に見せるために、ユーザーが確認していない要件を作り出すこと。
• ユーザーが求めていないバリエーションでユーザーストーリーを水増しすること。すべてのストーリーは、確認済みのニーズにたどれる必要があります。

参考資料

• references/prd-template.md — _prd.md の完全なテンプレートです。ファイルを書く前に読んでください。
• references/clarification-record.md — Clarification Record の形式、作成ルート、チェック範囲です。