speckit-specify

ユーザー入力

$ARGUMENTS

空でない場合は、先に進む前にユーザー入力を必ず考慮してください。

実行前の確認

仕様作成前に拡張フックを確認してください：

• プロジェクトのルートに .specify/extensions.yml があるか確認します。
• ファイルがある場合は、その内容を読み取り、hooks.before_specify キーの下にエントリーがあるか確認します。
• YAML を解析できない、または無効な場合は、黙ってスキップしないでください。.specify/extensions.yml を読み取れなかったこと（パーサーエラーを含む）と、そこに登録されている必須（optional: false）フックも含め、フックが確認されなかったことをユーザーに伝え、その後通常どおり続行します。
• enabled が明示的に false のフックは除外します。enabled フィールドがないフックは、デフォルトで有効として扱います。
• 残りの各フックについて、condition 式を解釈または評価しようとしないでください。
  • フックに condition フィールドがない場合、または null／空の場合は、実行可能なフックとして扱います。
  • フックに空でない condition が定義されている場合はフックをスキップし、条件の評価は HookExecutor の実装に委ねます。
• フックのコマンド名からコマンド呼び出しを構築する際は、ピリオド（.）をハイフンに置き換えます。たとえば、speckit.git.commit → /speckit-git-commit です。
• 実行可能な各フックについて、optional フラグに基づき、次の内容を出力します。

  • 任意のフック（optional: true）：

    ## Extension Hooks
    
    **Optional Pre-Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • 必須フック（optional: false）：

    ## Extension Hooks
    
    **Automatic Pre-Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    
    Wait for the result of the hook command before proceeding to the Outline.
    

    上記のブロックを出力した後、フックを実際に呼び出し、完了するまで待ってからアウトラインに進まなければなりません。このエージェント／セッションで自分自身がコマンドを実行する場合と同じ方法で実行してください（呼び出し方は、表示されている {command} の ID と異なる場合があります。たとえば、スキルモードのエージェントでは /skill:speckit-... や $speckit-... のようになります）。ブロックを出力しただけでは、フックを実行したことにはなりません。

• フックが登録されていない場合、または .specify/extensions.yml がない場合は、何も通知せずスキップします。

アウトライン

トリガーメッセージで /speckit-specify の後にユーザーが入力したテキストが、機能の説明です。以下に $ARGUMENTS が文字どおりに記載されていても、この会話では機能の説明を常に利用できるものとして扱ってください。ユーザーが空のコマンドを入力した場合を除き、説明を再度尋ねないでください。

その機能説明に基づき、次を行います。

1. 簡潔な短い名前を生成します（2～4語）。

   • 機能説明を分析し、最も重要なキーワードを抽出します。
   • 機能の本質を表す2～4語の短い名前を作成します。
   • 可能であれば、動作＋名詞の形式を使用します（例：「add-user-auth」、「fix-payment-bug」）。
   • 技術用語や略語（OAuth2、API、JWT など）はそのまま維持します。
   • 簡潔さを保ちつつ、ひと目で内容が分かる名前にします。
   • 例：
     • 「ユーザー認証を追加したい」→「user-auth」
     • 「API に OAuth2 統合を実装する」→「oauth2-api-integration」
     • 「分析用ダッシュボードを作成する」→「analytics-dashboard」
     • 「決済処理のタイムアウトバグを修正する」→「fix-payment-timeout」

2. ブランチの作成（フック経由で任意）：

   上記の実行前の確認で before_specify フックが正常に実行された場合、そのフックにより Git ブランチが作成または切り替えられ、BRANCH_NAME と FEATURE_NUM を含む JSON が出力されています。これらの値は参照用に記録しますが、ブランチ名によって仕様ディレクトリ名が決まるわけではありません。

   ユーザーが GIT_BRANCH_NAME を明示的に指定した場合は、ブランチスクリプトがその値をブランチ名としてそのまま使えるよう、フックに渡します（プレフィックス／サフィックスの生成をすべて回避します）。

3. 仕様用の機能ディレクトリを作成します： ユーザーが SPECIFY_FEATURE_DIRECTORY を明示的に指定しない限り、仕様はデフォルトの specs/ ディレクトリに配置されます。

   SPECIFY_FEATURE_DIRECTORY の解決順序：

   1. ユーザーが SPECIFY_FEATURE_DIRECTORY を明示的に指定した場合（環境変数、引数、設定など）、その値をそのまま使用します
   2. それ以外の場合は、specs/ の下に自動生成します：
      • .specify/init-options.json で feature_numbering（優先）または branch_numbering（非推奨。移行時のみ使用。今後のリリースで削除予定）を確認します
      • "timestamp" の場合：プレフィックスは YYYYMMDD-HHMMSS（現在のタイムスタンプ）です
      • "sequential" または未設定の場合：プレフィックスは NNN（specs/ 内の既存ディレクトリを調べて決定する、次に利用可能な3桁の番号）です
      • ディレクトリ名を作成します：<prefix>-<short-name>（例：003-user-auth または 20260319-143022-user-auth）
      • SPECIFY_FEATURE_DIRECTORY を specs/<directory-name> に設定します
      • branch_numbering が使用され（feature_numbering は未設定）、次の警告を1行で出力する場合：「⚠️ branch_numbering in init-options.json is deprecated. Rename to feature_numbering.」

   ディレクトリと仕様ファイルを作成する：

   • mkdir -p SPECIFY_FEATURE_DIRECTORY

   • Spec Kit のプリセット／テンプレート解決スタックを通じて、アクティブな spec-template を解決します（specify preset resolve spec-template と同等）

   • 解決された spec-template ファイルを SPECIFY_FEATURE_DIRECTORY/spec.md にコピーして、開始点とします

   • SPEC_FILE を SPECIFY_FEATURE_DIRECTORY/spec.md に設定します

   • 解決されたパスを .specify/feature.json に保存します：

     {
       "feature_directory": "<resolved feature dir>"
     }
     

     文字列 SPECIFY_FEATURE_DIRECTORY ではなく、実際に解決されたディレクトリパスの値（例：specs/003-user-auth）を書き込みます。 これにより、後続のコマンド（/speckit-plan、/speckit-tasks など）は、git ブランチ名の規則に依存せずに機能ディレクトリを見つけられます。

   重要：

   • /speckit-specify の1回の実行で作成できる機能は1つだけです
   • 仕様ディレクトリ名と git ブランチ名は独立しています。同じ名前にしてもかまいませんが、選択するのはユーザーです
   • 仕様ディレクトリとファイルは必ずこのコマンドで作成し、フックでは作成しません

4. 解決されたアクティブな spec-template ファイルを読み込み、必要なセクションを把握します。

5. 存在する場合：プロジェクトの原則とガバナンス上の制約を把握するため、.specify/memory/constitution.md を読み込みます。

6. 次の実行フローに従います：

   1. 引数からユーザーの説明を解析します 空の場合：エラー「機能の説明が指定されていません」
   2. 説明から重要な概念を抽出します アクター、アクション、データ、制約を特定します
   3. 不明確な点について：
      • 文脈と業界標準に基づいて、妥当な推測を行います
      • 次の条件を満たす場合に限り、[NEEDS CLARIFICATION: specific question] を付けます：
        • 選択によって機能の範囲またはユーザー体験が大きく変わる
        • 異なる影響をもたらす複数の妥当な解釈がある
        • 妥当なデフォルトが存在しない
      • 上限：[NEEDS CLARIFICATION] マーカーは合計3つまで
      • 影響の大きさに応じて、確認事項の優先順位を付けます：範囲 > セキュリティ／プライバシー > ユーザー体験 > 技術的な詳細
   4. ユーザーシナリオとテストのセクションを埋めます 明確なユーザーフローがない場合：エラー「ユーザーシナリオを特定できません」
   5. 機能要件を作成します 各要件はテスト可能である必要があります 指定されていない詳細には妥当なデフォルトを使用し、前提条件のセクションに記載します
   6. 成功基準を定義します 技術に依存しない、測定可能な成果を設定します 定量的な指標（時間、パフォーマンス、量）と定性的な指標（ユーザー満足度、タスク完了度）の両方を含めます 各基準は、実装の詳細がなくても検証できる必要があります
   7. 主要なエンティティを特定します（データを扱う場合）
   8. 次を返します：成功（計画に進める状態の仕様）

7. テンプレートの構造に従って、仕様を SPEC_FILE に記述します。機能の説明（引数）から得られる具体的な詳細でプレースホルダーを置き換え、セクションの順序と見出しはそのまま維持してください。

8. 仕様の品質検証：初期仕様を記述した後、品質基準に照らして検証します。

   a. 仕様品質チェックリストの作成：次の検証項目を含むチェックリストファイルを、チェックリストのテンプレート構造に従って SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md に生成します。

   # Specification Quality Checklist: [FEATURE NAME]
   
   **Purpose**: Validate specification completeness and quality before proceeding to planning
   **Created**: [DATE]
   **Feature**: [Link to 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
   - [ ] Requirements are testable and unambiguous
   - [ ] Success criteria are measurable
   - [ ] Success criteria are technology-agnostic (no implementation details)
   - [ ] All acceptance scenarios are defined
   - [ ] Edge cases are identified
   - [ ] Scope is clearly bounded
   - [ ] Dependencies and assumptions identified
   
   ## Feature Readiness
   
   - [ ] All functional requirements have clear acceptance criteria
   - [ ] User scenarios cover primary flows
   - [ ] Feature meets measurable outcomes defined in Success Criteria
   - [ ] No implementation details leak into specification
   
   ## Notes
   
   - Items marked incomplete require spec updates before `/speckit-clarify` or `/speckit-plan`
   

   b. 検証の実施：各チェックリスト項目に照らして仕様を確認します。

   • 各項目について、合格か不合格かを判定します。
   • 見つかった具体的な問題を記録します（該当する仕様のセクションを引用してください）。

   c. 検証結果への対応：

   • すべての項目に合格した場合：チェックリストを完了済みとしてマークし、「実行後の必須フック」セクションに進みます。

   • 不合格の項目がある場合（[NEEDS CLARIFICATION] を除く）：

     1. 不合格の項目と具体的な問題を列挙します。
     2. 各問題に対処するよう仕様を更新します。
     3. すべての項目に合格するまで検証を再実行します（最大3回）。
     4. 3回の反復後も不合格が残る場合は、チェックリストの注記に未解決の問題を記録し、ユーザーに警告します。

   • [NEEDS CLARIFICATION] マーカーが残っている場合：

     1. 仕様からすべての [NEEDS CLARIFICATION: ...] マーカーを抽出します。

     2. 上限の確認：マーカーが3つを超える場合、最も重大な影響をもたらす3つ（スコープ／セキュリティ／UX への影響に基づく）だけを残し、残りについては妥当な推測をします。

     3. 必要な確認事項ごと（最大3件）に、次の形式で選択肢を提示します。

        ## 質問 [N]：[トピック]
        
        **背景**：[該当する仕様セクションの引用]
        
        **確認事項**：[NEEDS CLARIFICATION マーカーに記載された具体的な質問]
        
        **推奨する回答**：
        
        | 選択肢 | 回答                    | 影響                          |
        | ------ | ----------------------- | ----------------------------- |
        | A      | [最初の回答候補]        | [機能にどのような意味を持つか] |
        | B      | [2番目の回答候補]       | [機能にどのような意味を持つか] |
        | C      | [3番目の回答候補]       | [機能にどのような意味を持つか] |
        | Custom | 独自の回答を提示する    | [独自の回答を入力する方法を説明] |
        
        **選択する回答**： _[ユーザーの回答を待つ]_
        

     4. 重要 — 表の書式：Markdown の表が適切に書式設定されていることを確認します。

        • パイプの位置をそろえ、一貫した間隔にします。
        • 各セルの内容の前後にスペースを入れます（|Content| ではなく | Content |）。
        • ヘッダー区切りには3つ以上のハイフンを使用します（|--------|）。
        • Markdown プレビューで表が正しく表示されることを確認します。

     5. 質問には順番に番号を付けます（Q1、Q2、Q3。最大3件）。

     6. 回答を待つ前に、すべての質問をまとめて提示します。

     7. すべての質問に対する選択肢をユーザーが回答するまで待ちます（例：「Q1: A、Q2: Custom - [詳細]、Q3: B」）。

     8. 選択された回答または入力された回答で、各 [NEEDS CLARIFICATION] マーカーを置き換えて仕様を更新します。

     9. すべての確認事項が解決した後、検証を再実行します。

   d. チェックリストの更新：検証を繰り返すたびに、現在の合否状況を反映してチェックリストファイルを更新します。

実行後の必須フック

ユーザーに完了を報告する前に、このセクションを必ず完了してください。

プロジェクトルートに .specify/extensions.yml が存在するか確認してください。

• 存在しない場合、または hooks.after_specify にフックが登録されていない場合は、「完了レポート」に進んでください。
• 存在する場合は内容を読み、hooks.after_specify キーの下にあるエントリーを確認してください。
• YAML を解析できない、または無効な場合は、何も言わずにスキップしないでください。.specify/extensions.yml を読み取れなかったこと（パーサーエラーを含む）と、そこに登録されている必須のフック（optional: false）を含め、フックを一切確認していないことをユーザーに伝えてから、「完了レポート」に進んでください。
• enabled が明示的に false のフックは除外してください。enabled フィールドのないフックは、デフォルトで有効として扱ってください。
• 残りの各フックについて、フックの condition 式を解釈または評価しようとしないでください。
  • フックに condition フィールドがない場合、または null／空の場合は、実行可能なフックとして扱ってください。
  • フックに空でない condition が定義されている場合は、そのフックをスキップし、条件の評価は HookExecutor の実装に委ねてください。
• フックのコマンド名からコマンド呼び出しを構築する際は、ドット（.）をハイフン（-）に置き換えてください。例：speckit.git.commit → /speckit-git-commit。
• 実行可能な各フックについて、optional フラグに応じて以下を出力してください。

  • 必須フック（optional: false） — 必須フックごとに 必ず EXECUTE_COMMAND: を出力してください。

    ## Extension Hooks
    
    **Automatic Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    

    上記のブロックを出力した後、必ず実際にフックを呼び出し、完了するまで待ってから先に進んでください。このエージェント／セッションで自身がコマンドを実行するときと同じ方法で実行してください（呼び出し方法は、表示された {command} の ID と異なる場合があります。たとえば、skills モードのエージェントでは /skill:speckit-... または $speckit-... を実行します）。ブロックを出力するだけでは、フックを実行したことにはなりません。

  • 任意フック（optional: true）：

    ## Extension Hooks
    
    **Optional Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

完了レポート

次の内容をユーザーに報告してください。

• SPECIFY_FEATURE_DIRECTORY — フィーチャーディレクトリのパス
• SPEC_FILE — 仕様ファイルのパス
• チェックリスト結果の概要
• 次のフェーズ（/speckit-clarify または /speckit-plan）に進む準備ができているか

注記： ブランチの作成は before_specify フック（git 拡張機能）が担当します。仕様ディレクトリとファイルの作成は、常にこのコアコマンドが担当します。

クイックガイドライン

• ユーザーが何を必要としているか、そしてなぜ必要としているかに焦点を当ててください。
• 実装方法（技術スタック、API、コード構成など）は避けてください。
• 開発者ではなく、ビジネス関係者に向けて記述してください。
• 仕様書内にチェックリストを作成しないでください。チェックリストの作成は別のコマンドで行います。

セクションの要件

• 必須セクション：すべてのフィーチャーで記述してください。
• 任意セクション：フィーチャーに関連する場合にのみ含めてください。
• 該当しないセクションは完全に削除してください（「該当なし」として残さないでください）。

AI 生成时

ユーザープロンプトからこの仕様を作成する場合：

1. 十分な情報に基づいて推測する：文脈、業界標準、一般的なパターンを使って不足を補います
2. 前提を記録する：「前提」セクションに妥当なデフォルトを記載します
3. 確認事項を最小限に抑える：[NEEDS CLARIFICATION] マーカーは最大 3 つとし、次の条件に該当する重要な判断にのみ使用します：
   • 機能の範囲やユーザー体験に大きな影響を与える
   • 妥当な解釈が複数あり、それぞれに異なる影響がある
   • 妥当なデフォルトが存在しない
4. 確認事項に優先順位を付ける：範囲 > セキュリティ／プライバシー > ユーザー体験 > 技術的な詳細
5. テスターの視点で考える：曖昧な要件はすべて「テスト可能で曖昧でない」というチェック項目を満たせないものとして扱います
6. 確認が必要になりやすい一般的な項目（妥当なデフォルトが存在しない場合のみ）：
   • 機能の範囲と境界（特定のユースケースを含めるか除外するか）
   • ユーザーの種類と権限（解釈が複数あり、互いに矛盾する可能性がある場合）
   • セキュリティ／コンプライアンス要件（法務または財務に重大な影響がある場合）

妥当なデフォルトの例（これらについて確認しないでください）：

• データ保持：その分野の業界標準に従った運用
• パフォーマンス目標：指定がない限り、一般的なウェブ／モバイルアプリの期待値
• エラー処理：適切な代替手段を備えた、ユーザーにわかりやすいメッセージ
• 認証方法：ウェブアプリで一般的なセッションベースまたは OAuth2
• 統合パターン：プロジェクトに適したパターンを使用（ウェブサービスでは REST／GraphQL、ライブラリでは関数呼び出し、ツールでは CLI 引数など）

成功基準のガイドライン

成功基準は次の条件を満たす必要があります：

1. 測定可能である：時間、割合、件数、率などの具体的な指標を含めます
2. テクノロジーに依存しない：フレームワーク、言語、データベース、ツールに言及しません
3. ユーザーを中心にしている：システム内部の仕組みではなく、ユーザーやビジネスにとっての成果を記述します
4. 検証可能である：実装の詳細を知らなくてもテストまたは検証できます

良い例：

• 「ユーザーは 3 分以内にチェックアウトを完了できます」
• 「システムは同時に 10,000 人のユーザーをサポートします」
• 「検索の 95％で 1 秒以内に結果が返されます」
• 「タスク完了率が 40％向上します」

悪い例（実装に焦点を当てています）：

• 「API の応答時間が 200ms 未満です」（技術的すぎます。「ユーザーは結果をすぐに確認できます」とします）
• 「データベースは 1000 TPS を処理できます」（実装の詳細です。ユーザー向けの指標を使用します）
• 「React コンポーネントが効率よくレンダリングされます」（フレームワークに依存しています）
• 「Redis のキャッシュヒット率が 80％を超えています」（特定の技術に依存しています）

完了条件

• 仕様を SPEC_FILE に記述し、品質チェックリストに照らして検証している
• 上記の「必須の実行後フック」に記載されたルールに従って、拡張フックを実行またはスキップしている
• 機能ディレクトリ、仕様ファイルのパス、チェックリストの結果をユーザーに報告している