productspec

ProductSpec エージェントスキル

Product Spec は、重大なソフトウェア開発における製品の契約です。

リポジトリで Agent Run ファイルを使用している場合は、固定された Product Spec リビジョンに基づく、1 回のエージェント実行の記録として扱ってください。

計画、コーディング、テスト、スコープ変更を行う前に、リポジトリ内で関連する .product-spec.md ファイルを探してください。よくある配置場所は次のとおりです。

• specs/
• product-specs/
• docs/product-specs/
• タスク、issue、プルリクエスト、またはエンジニアリング仕様で指定されたパス

関連する Product Spec がある場合は、作業を始める前に読んでください。

Product Spec の使い方

次の順序で各セクションを読んでください。

1. Problem：誰が困っているのか、そしてその作業がなぜ重要なのか。
2. Hypothesis：製品の因果関係に関する仮説。
3. Product Summary：作業完了時に実現しているべきこと。
4. Scope：対象、対象外、意図的に見送ったもの。
5. Acceptance Criteria：AI 評価が含まれる場合はそれも含む、ビルドの契約。
6. Success Metrics：リリース後の成果を確認する指標。
7. Related Artifacts：作業が依存する issue、プルリクエスト、評価実行、ダッシュボード、デザイン、エンジニアリング仕様、その他の Product Spec。

Acceptance Criteria はビルドの契約です。計画、タスク、コード変更、テスト、プルリクエストの概要には、該当する AC-<number> ID を記載してください。

AI 評価は Acceptance Criteria に含まれるリリース前のゲートであり、独立した ## AI Evals セクションではありません。モデルの動作を実装または変更する際は、EVAL-<number> を記載してください。

Success Metrics はリリース後の成果です。SM-<number> の項目を実装タスクとして扱わないでください。

計画のルール

実装計画を作成する際は、次の点に従ってください。

• 実装対象の Product Spec と spec_revision を記載してください。
• ProductSpec MCP が利用可能な場合は、計画の前に begin_spec_session を呼び出し、返された spec_revision とセッション ID を計画に含めてください。
• 各タスクを該当する Acceptance Criteria に対応付けてください。
• 計画で対応しない Acceptance Criteria を明記してください。
• scope.out と scope.cut は明示的な非目標として扱ってください。
• applies_to と Related Artifacts を使って、関連するコード、issue、プルリクエスト、デザイン、評価、ダッシュボードを特定してください。
• 計画を立てる前に、product_spec 関連アーティファクトを解決してください。depends_on の対象がまだビルドされていない仕様はブロックされており、実装できません。計画には、何を待つ必要があるかを記載してください。
• 仕様がまとめられたフォルダーについては、すべての仕様を読み直して依存関係を導き出す代わりに、productspec graph <dir> --json（または get_spec_graph MCP ツール）を実行して、ビルド可能な仕様、各仕様の待機対象を示すブロック中の仕様、依存関係を考慮したビルド順を 1 回の呼び出しで取得してください。
• Product Specs、Agent Runs、Decision Traces、エビデンスリンクがあるリポジトリでは、作業を選ぶ前に productspec garden <repo> --json を実行してください。これを使って、エビデンスの欠落、古いリビジョンの固定、実行の不足、Decision Trace の不足、スコープ未確定の仕様、競合、作業ウェーブを確認してください。
• 別のエージェントが同じフォルダーで作業している可能性がある場合は、同じ呼び出し結果から contention と waves を確認してください。同じ領域に触れる 2 つの仕様は、どちらもビルド可能であっても同時にビルドしてはいけません。現在のウェーブから作業を選び、unscoped に記載された仕様は安全なスコープではなく、スコープ不明として扱ってください。
• RESOLVE-IN-PLAN: マーカーは、未解決の技術的な紐付けとして扱ってください。コーディング前に、ソースを引用してコードベース内で各マーカーを解決してください。
• 推測したテーブル名、フィールド、エンドポイント、サービス、ファイルパスを、拘束力のある指示であるかのように実装しないでください。

変更のルール

製品の意図を黙って変更しないでください。

実装上の制約が Product Spec と衝突する場合は、その衝突を明示し、次のいずれかを提案してください。

• Product Spec を更新する
• 実装を更新する
• トレードオフを受け入れ、Decision Trace に記録する
• 作業を再開する

実装後に動作を変更する場合は、コードの乖離を意図として扱うのではなく、Product Spec のリビジョンまたは Decision Trace への記録を提案してください。

出力ルール

進捗を報告するとき、またはプルリクエストを作成するときは、次のルールに従ってください。

• ProductSpec MCP が利用可能な場合は、まず check_spec_session を呼び出します。Product Spec が変更されていた場合は、完了を宣言する前に再読し、計画を立て直してください。
• ProductSpec MCP が利用可能な場合は、get_evidence_checklist を呼び出し、該当する AC- と EVAL- の ID について、根拠を添付するか、根拠の名前を示してください。
• リポジトリで Agent Run ファイルを使用している場合は、draft_agent_run を呼び出すか、productspec init-run <spec> <agent-run> を実行して記録を作成します。その後、確認済みの AC-、EVAL-、SM- の ID、根拠へのリンク、ドリフトの状態、完了宣言を記入してください。productspec validate-run で検証します。
• 完了を宣言する前に、ローカル CLI が利用可能な場合は productspec reconcile <spec> --against <agent-run> を実行します。未確認の項目、失敗した項目、古い仕様のリビジョン、根拠のない合格項目、Decision Trace のないドリフトを修正してから、作業の完了を宣言してください。
• Product Spec のパスと spec_revision を明記します。
• 対応した Acceptance Criteria を明記します。
• 追加または変更した AI 評価を明記します。
• 意図的に先送りしたスコープ項目を明記します。
• 関連する課題、プルリクエスト、評価の実行結果、ダッシュボードが利用可能な場合は、それらへのリンクを記載します。