productspec-authoring

ProductSpec ファイルの作成

ProductSpec は、チケット、エンジニアリング計画、コードに先立つプロダクト上の意思決定を記述する Markdown 形式です。機能ごとに 1 つのファイルを作成し、確定した意図を記録します。

このスキルでは、そのファイルの作成方法を扱います。完成した仕様を読み、それに基づいて構築するのは別の作業であり、その作業には productspec スキルを使用します。このスキルは、ファイルの検証が完了した時点で終了します。

常に守ること

• ファイルの拡張子は .product-spec.md にします。--- マーカーで囲んだ YAML フロントマターの後に、## Section 見出しを続けます。
• 必須セクションは 6 つあり、順序は problem、hypothesis、product_summary、scope、acceptance_criteria、success_metrics です。
• 見出しは、大文字と小文字、および区切り文字を区別せずに一致します。## Acceptance Criteria と ## acceptance_criteria は同じセクションです。タイトルケースを慣例とします。
• フロントマターには spec_format_version: "0.1"、title、artifact_type（hypothesis | prd | openspec_proposal）、author、created_at、updated_at が必要です。任意の項目は spec_revision、linked_github_repo、applies_to、custom_sections、tool_metadata です。
• acceptance_criteria と success_metrics には、それぞれ必須のフェンス付きブロックが必要です。文章だけでは検証に合格しません。構造化されたスコープ、AI 評価、関連成果物は任意です。
• 構造化された項目には、永続的な ID（AC-<number>、SM-<number>、EVAL-<number>）を付けます。他のドキュメントからこれらを参照します。
• AI 評価は ## Acceptance Criteria 内に記述し、独立したセクションにはしません。関連成果物は ## Related Artifacts 内に記述します。
• 次のコマンドで任意のファイルを検証できます：npm exec --yes --package @productspec/parser -- productspec validate <file>（--yes は npm の対話形式のインストール確認を抑制します。この確認があると、CI や非対話型エージェントが停止します）。
• 規範的な定義の全文は、ProductSpec リポジトリの SPEC.md にあります：https://github.com/gokulrajaram/ProductSpec/blob/main/SPEC.md。このスキルと SPEC.md の内容が異なる場合は、SPEC.md を優先します。

タスクを選び、参照資料を 1 つ読む

タスク	読む資料
新しい仕様を一から作成する	references/authoring.md
ファイルを検証してエラーを修正する	references/validating.md
既存の PRD または機能ドキュメントを変換する	references/converting.md
乖離、改訂、結果を記録する	references/decision-trace.md

タスクに必要な参照資料だけを読んでください。

基本ルール

• 永続的な ID を決して振り直さないでください。チケット、エンジニアリング仕様、別のエージェントが参照する可能性があるため、AC-2 は今日も明日も同じ基準を意味します。新しい ID は末尾に追加してください。
• 成功指標には目標値と期間が必要で、ブロックも必須です。ローンチ後に初めて得られるベースラインによって数値が決まる場合は、target: tbd と target_status: provisional を記述し、target_owner に担当者を明記してください。バリデーターを通すために数値を作り上げないでください。
• セクション内では、作成者の Markdown を保持してください。表、リスト、リンクはそのまま残します。平坦化しないでください。
• Scope の項目は、完結した文または命令文として記述してください。search や storage のような簡潔すぎるタグは避けてください。
• spec_revision を増やすのは、プロダクトの意図が実質的に変わる場合だけです。誤字や書式の修正では増やしません。