spec-kit-specify

自然言語の説明から機能仕様を作成します。

入力：機能の説明。提供されていない場合は、何を作りたいのかをユーザーに尋ねます。

手順

1. 機能の説明を収集する

   ユーザーがリクエストとともに入力したテキストが機能の説明です。繰り返しを求めてはいけません。 説明がない場合、またはアクターとアクションを特定するには曖昧すぎる場合は、次のように尋ねます。

   「どの機能の仕様を作成しますか？何を実現する機能で、なぜ必要なのかを説明してください。」

   2〜4語の短いケバブケース名を導き出します。可能であれば動詞＋名詞の形にし、 技術用語や略語は維持します （例：「ユーザー認証を追加する」→ user-auth、「決済処理のタイムアウトを修正する」→ fix-payment-timeout）。

2. 変更ディレクトリを作成する

   specs/changes/<name>/ を作成します。 1回の実行につき機能は1つです。

   specs/changes/ は Git の追跡対象外です。正規の仕様であり、バージョン管理されるのは specs/features/ のみです。

3. 対象領域を規定する既存の内容を読む

   作成を始める前に、機能が関係する領域を扱う specs/features/ の現行仕様と、specs/decisions/（プロジェクトで使用している場合）の決定記録、ならびに FRAMEWORK.md（存在する場合は FRAMEWORK.local.md も）を読みます。 仕様は、すでに適用されているルールを基礎とし、それを暗黙のうちに繰り返したり、矛盾したりしてはいけません。

4. specs/changes/<name>/spec.md を作成する

   構成：

   # Spec: <Feature Name>
   
   ## Problem
   <Why this feature is needed.>
   
   ## Goals
   <What success looks like, in measurable, technology-agnostic terms.>
   
   ## Non-Goals
   <What is explicitly out of scope.>
   
   ## User Stories
   - US-1: As a <role>, I want <goal> so that <benefit>. [P1]
     Independent test: <how this story alone can be demonstrated to work>
   
   ## Requirements
   ### FR-01: <one behaviour the system must have>
   - WHEN <situation> THEN <observable outcome>
   
   ## Edge Cases
   ### <a surface the change alters: a screen, a command, an endpoint, a message>
   - FR-02: on failure — WHEN <it fails> THEN <what the person or caller sees>
   - FR-03: while waiting — WHEN <it has not answered yet> THEN <...>
   - FR-04: with nothing to show — WHEN <there is no data> THEN <...>
   - FR-05: after closing and reopening — WHEN <it is dismissed and opened again> THEN <...>
   - FR-06: on a repeated or concurrent action — WHEN <it is triggered twice> THEN <...>
   - FR-07: with hostile or malformed input — WHEN <outside input arrives malformed or crafted> THEN <...>
   - <state>: cannot arise, because <reason>
   - None: the change alters no screen, command, endpoint or message, because <reason>
   
   ## Key Entities
   <Only when data is involved: each entity, what it represents, its key attributes and relationships, without implementation.>
   
   ## Success Criteria
   - SC-01: <measurable, technology-agnostic outcome>
   
   ## Assumptions
   - <informed default taken> — <why it is the safe reading>
   
   ## Open Questions
   - [NEEDS CLARIFICATION] <question> — impact: <scope|security|ux|technical>
   

   任意のセクション（たとえば「主要エンティティ」）が該当しない場合は、「N/A」と書かずに削除します。

   ルール：

   • WHAT（何を）と WHY（なぜ）に焦点を当てます。HOW（どのように）を説明したり、技術名を挙げたりしてはいけません。
   • 開発者ではなく、ビジネス関係者向けに書きます。
   • FRAMEWORK.md の基本原則に沿わせます。
   • すべての項目に識別子を付けます。 ユーザーストーリーには US-n を付け、優先度（P1 が最重要）と独立したテストを含めます。 要件には FR-nn、成功基準には SC-nn を付けます。 識別子は変更の期間を通じて再利用したり、番号を振り直したりしてはいけません。後続の成果物から参照できるようにします。
   • 各要件には動作を1つだけ含めます。 各要件には、specs/features/ で使用されている形式の WHEN/THEN シナリオを少なくとも1つ含めます。 複合的な要件は分割し、一部のみが満たされたことを示せるようにします。
   • 変更によって影響を受けるすべての画面や機能について、## Edge Cases で各状態を決定します。 失敗、待機、表示するものがない場合、閉じた後に再度開いた場合、操作の繰り返しや同時実行を扱います。 各状態について、シナリオを伴う独立した要件を設けるか、その状態が発生しない理由を1行で説明します。 人、別のエージェント、または別のシステムから入力を受け取る画面や機能では、同じ方法で不正または形式不備の入力の状態も決定します。 変更によって画面や機能に影響しない場合は、その旨と理由を記載します。
   • エッジケースには、既存のルールを適用するのが原則です。 すでにその状態を決定している現行仕様または決定記録を引用します。 既存のルールで扱われず、妥当なデフォルトもない状態は、新たな設計とせず未解決の質問とします。
   • 指定されていない詳細には、状況と一般的な慣行に基づいて妥当なデフォルトを定め、その解釈が安全である理由とともに「前提」に記録します。 デフォルトを決定した場合は要件とし、その理由を前提として記録します。 データ保持、一般的なエラー処理、通常のパフォーマンス要件など、妥当なデフォルトがある詳細については尋ねてはいけません。
   • 成功基準は、実装を知らなくても検証できる、測定可能で、技術に依存せず、ユーザーを重視したものにします。 「ユーザーが3分以内にチェックアウトを完了する」は基準です。「API が200ミリ秒以内に応答する」や「キャッシュヒット率が80％を超える」は実装の詳細です。
   • [NEEDS CLARIFICATION] マーカーは最大3つとし、選択によって対象範囲やユーザー体験が大きく変わり、複数の解釈が妥当で、デフォルトもない場合に限って使用します。 優先順位は、対象範囲 > セキュリティとプライバシー > UX > 技術です。その他の項目については、妥当な推測を行います。
   • 仕様内にチェックリストを埋め込まないでください。

5. 品質チェックリストに照らして仕様を検証する specs/changes/<name>/checklists/requirements.md を作成します。

   # Specification Quality Checklist: <Feature Name>
   
   **Purpose**: Validate the specification before planning.
   **Feature**: [spec.md](../spec.md)
   
   ## Content Quality
   - [ ] No implementation details (languages, frameworks, APIs)
   - [ ] Focused on user value and business needs
   - [ ] Written for non-technical stakeholders
   - [ ] All mandatory sections completed
   
   ## Requirement Completeness
   - [ ] No [NEEDS CLARIFICATION] markers remain
   - [ ] Every story, requirement and success criterion carries its identifier
   - [ ] Every requirement states one behaviour and has a WHEN/THEN scenario
   - [ ] Requirements are testable and unambiguous
   - [ ] Success criteria are measurable and technology-agnostic
   - [ ] Every surface the change alters has its edge-case states decided
   - [ ] Scope is clearly bounded
   - [ ] Dependencies and assumptions are identified
   
   ## Feature Readiness
   - [ ] Every user story has an independent test
   - [ ] User stories cover the primary flows
   - [ ] No implementation details leak into the specification
   

   各項目に照らして仕様を確認し、合格した項目にのみチェックを付けます。不合格の項目については、それぞれ該当する仕様のセクションを引用します。 未解決の質問を除く不合格項目について、仕様を修正して再度検証します。これを最大3回まで行います。 3回目の反復後も不合格項目が残る場合は、チェックリストの下に残りの問題を記載し、ユーザーに伝えます。 このチェックリストは、このスキルと spec-kit-clarify が管理します。spec-kit-checklist が作成したチェックリストは、レビュー担当者が管理します。

出力

仕様を作成した後、次の内容を要約します。

• 変更名とファイルの場所。
• 識別子ごとに集計したストーリー、要件、成功基準の数。
• チェックリストの結果：合格項目数／合計項目数、および不合格のまま残っている項目。
• 未解決の質問の数（ある場合）。
• 次のステップ：「未解決の質問を解決するには spec-kit-clarify スキルを使用し、仕様が明確な場合は spec-kit-plan スキルを使用してください。」

ガードレール

• 同じ名前の変更がすでに存在する場合は、続行するか、新しい変更を作成するかをユーザーに確認します。
• 仕様にHOWを含めてはいけません。技術スタック、フレームワーク、実装の詳細は記載しません。
• 不必要な質問をするより、妥当な前提を置くことを優先します。
• 生きた仕様や意思決定記録と矛盾する場合は、未解決の質問として明示せずに矛盾してはいけません。