spec-driven-propose

ユーザーが新しい仕様駆動型の変更提案を作成するのを支援しています。

提案の段階では、追加の質問をしたり、確認を求めたりしないでください。 ユーザーの依頼、プロジェクトのコンテキスト、既存の仕様から、できる限り最適な提案を導き出してください。残っている不明点は questions.md に記録し、実装開始前に /spec-driven-apply で提示できるようにします。

このスキルのコマンド

このスキルで使用する正確なコマンドを思い出せない場合は、実行する前にここで調べてください。推測してはいけません。

propose: node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
verify: node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>

前提条件

.spec-driven/ ディレクトリがプロジェクトルートに存在している必要があります。作業を進める前に、次を確認してください。

ls .spec-driven/

これが失敗した場合、プロジェクトは初期化されていません。まず /spec-driven-init を実行してください。

手順

1. 変更名を決める — ユーザーが kebab-case の名前を指定している場合は、それを使用します。指定がない場合は、質問して作業を止めずに、依頼内容と提案の範囲から短い kebab-case の名前を自分で導き出します。

2. プロジェクトのコンテキストと既存の仕様を読む — 何かを生成する前に、次を読んでください。

   • .spec-driven/config.yaml — 内容の参考として context を使用し、rules は拘束力のある制約として扱います。この変更で触れるファイルに適用される fileMatch エントリーがあれば確認します。
   • .spec-driven/specs/INDEX.md — すべての既存仕様ファイルとその範囲を確認します。
   • INDEX.md に記載され、この変更で触れる可能性が高いすべての仕様ファイル — MODIFIED または ADDED の項目を書く前に、既存の要件を理解するため、内容をすべて読みます。

3. 変更のひな形を作成する — 次を実行します。

   node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
   

これにより、ひな形が入った成果物テンプレートとともに .spec-driven/changes/<name>/ が作成されます。

4. proposal.md を記入する — 以下を含む、明確で簡潔な提案を記述します。

   • What：この変更で実現すること（実装方法ではなく、観察可能な動作）
   • Why：動機と背景
   • Scope：対象範囲と、明示的に対象外とするもの
   • Unchanged Behavior：変更によって壊してはならない既存の動作を列挙します。この変更に隣接する動作、または影響を受ける可能性がある動作が対象です。本当にリスクがなければ空欄にします。

5. design.md を記入する — 技術的なアプローチを記述します。

   • Approach：大まかな実装方法
   • Key Decisions：重要な選択とその根拠
   • Alternatives Considered：採用しなかった案とその理由

6. specs/ の差分ファイルを作成する — プロジェクトの .spec-driven/specs/ ディレクトリ構造を確認します。この変更で触れる仕様ファイルごとに、同じ相対パスを維持して .spec-driven/changes/<name>/specs/ 以下に対応するファイルを作成します（例：specs/auth/login.md → changes/<name>/specs/auth/login.md）。新しい仕様領域を導入する場合は、アーカイブ後に .spec-driven/specs/ 以下に存在すべき相対パスを新たに作成します。

   仕様のメインパスを正確に反映してください。たとえば、 .spec-driven/specs/skills/planning.md は .spec-driven/changes/<name>/specs/skills/planning.md に対応します。

   次の標準例をフォーマットの基準として使用してください。

   ---
   mapping:
     implementation:
       - path/to/implementation.ts
     tests:
       - test/path/to/test.ts
   ---
   
   ## ADDED Requirements
   
   ### Requirement: new-capability
   The system MUST provide <observable behavior>.
   
   #### Scenario: success
   - GIVEN <precondition>
   - WHEN <action>
   - THEN <result>
   
   ## MODIFIED Requirements
   
   ### Requirement: existing-capability
   Previously: The system MUST <old behavior>.
   The system MUST <new behavior>.
   
   ## REMOVED Requirements
   
   ### Requirement: old-capability
   Reason: This behavior is removed because <reason>.
   

   各差分ファイルでは、標準形式に従って ADDED/MODIFIED/REMOVED セクションを使用します。

   • 関連ファイルがリポジトリのコンテキストから特定できる場合は、mapping.implementation と mapping.tests を含む YAML フロントマター
   • ### Requirement: <name> 見出しと RFC 2119 キーワード（MUST/SHOULD/MAY）
   • 役立つ場合は #### Scenario: ブロック（GIVEN/WHEN/THEN）
   • ADDED：新しい要件、MODIFIED：変更された要件（Previously: の注記を含める）、REMOVED：削除された要件（理由を含める）
   • 該当しないセクションは省略し、空のセクションを残さないでください。
   • この変更による観察可能な仕様への影響がない場合は、changes/<name>/specs/ を空のままにしてください。差分仕様の形式に違反する、説明文だけの差分ファイルを作成してはいけません。
   • 関連する実装ファイルまたはテストファイルが明確でない場合は、マッピングのパスを作り上げないでください。マッピングの補完は /spec-driven-apply に任せます。

7. tasks.md を記入する — 次の標準構成を使用して、具体的な実装チェックリストを作成します。

   # Tasks: <change-name>
   
   ## Implementation
   - [ ] Describe the first atomic implementation task
   - [ ] Describe the second atomic implementation task
   
   ## Testing
   
   - [ ] Run `npm run lint` — lint or validation task
   - [ ] Run `npm test` — unit test task
   
   ## Verification
   - [ ] Verify implementation matches proposal scope
   

   各タスクには - [ ] チェックボックスを使用します。各タスクはそれぞれ単独で完了できるようにしてください。

   ## Testing セクションは、以下の検証キーワード要件を必ず満たす必要があります。

   • 少なくとも1つのタスクに、lint／検証キーワードを含める必要があります。キーワードは lint、 validate、validation、typecheck、type-check、または build です。
   • 少なくとも1つのタスクに、単体テストキーワードを含める必要があります。キーワードは unit test または unit tests です。
   • 両方のタスクで、バッククォートで囲んだ明示的に実行可能なコマンドを指定するか、既知の ランナー（npm、pnpm、yarn、bun、node、bash、sh、pytest、jest、vitest、go、cargo、 make、uv、poetry）を使用する必要があります。
   • これらのキーワードを言い換えると（例：「unit tests」の代わりに「テストを実行する」と記述するなど）、 verify が失敗します。

   リポジトリのコンテキストから該当するコマンドを確実に判断できない場合は、推測するのではなく、 questions.md に未解決の質問を追加してください。「Update specs」タスクは追加しないでください。 specs/ ディレクトリには仕様アーティファクトが含まれています。

8. questions.md を記入する — 未解決の質問や曖昧な点を記録します。

   • 不明確な点（動機、範囲の境界、技術的アプローチなど）があれば、## Open の下にエントリーを追加します。

     - [ ] Q: <具体的な質問>
       Context: <これが重要な理由／回答に依存するもの>
     

   • すべて明確な場合は、## Open を空のままにし、注記として `` を記載します。
   • どのアーティファクトにも [NEEDS CLARIFICATION] のインラインマーカーを使用しないでください。質問はすべて questions.md に記載します。

9. アーティファクトの形式を検証する — 次を実行します。

   node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
   

   提案を提示する前に、最終的な構造と形式のチェックとして扱ってください。

   • アーティファクトの不足、不正なデルタ仕様のセクション／見出し、または安全に修正できる未入力のプレースホルダーが報告された場合は、直ちに修正して verify を再実行してください。
   • verify で、確信を持って修正できない形式または構造上の問題が引き続き報告される場合は、そこで中断し、問題をユーザーに報告してください。
   • 残っているエラーが questions.md の未解決の質問だけであれば、提案の段階では想定内として扱い、それらの質問をユーザーにはっきりと伝えてください。

10. 引き渡す — 5つのファイルをユーザーに提示し、対象範囲、主な決定事項、未解決の質問を要約します。提案を書き終えた後に確認のチェックポイントを設けないでください。questions.md に未解決の質問がある場合は、/spec-driven-apply がそれらを実装のブロッカーとして提示し、コーディング開始前にユーザーによる明示的な解決が必要になることを明確にしてください。また、/spec-driven-modify は任意の修正手段としてのみ言及してください。

Rules

• 実装は行わないでください。ここでは計画のみを行います。
• タスクはそれぞれ独立し、検証可能な単位にしてください。
• 追加の質問をしたり、提案段階での確認チェックポイントを求めたりしないでください。
• proposal.md には「何を、なぜ」行うのかを記述し、design.md には「どのように」行うのかを記述し、tasks.md はチェックリスト、questions.md は未解決の質問を記載するファイルとします。
• 曖昧な点は questions.md に記録してください。不明確な要件を推測したり、インラインマーカー [NEEDS CLARIFICATION] を使用したりしないでください。
• アーティファクトを書いた後に、提案後の確認ゲートを追加しないでください。
• 提案の引き渡し時点で未解決の質問があってもかまいません。/spec-driven-apply がそれらを提示し、解決されるまで処理を止められるよう、questions.md に残してください。
• 作業を終える前に、修正可能な形式上の問題がすべて解消されるまで verify を再実行してください。質問以外のエラーが残っている場合は、ユーザーに報告してください。
• 仕様とコードの対応関係は要件の本文ではなく、フロントマターに記載してください。