speckit-clarify

speckit-clarify

このスキルの内容は、GitHub Spec Kit の公式プロンプトテンプレートに基づいています。

• 上流：https://github.com/github/spec-kit
• ライセンス：MIT License, Copyright GitHub, Inc.（全文は同じディレクトリ内の LICENSE.txt を参照）
• 適応に関する説明：公式テンプレートはスラッシュコマンドの使用を想定しています。原文の $ARGUMENTS は、ユーザーが会話内で提示するリクエストを指します。 コマンド間の参照（speckit.plan など）は、このスキル体系では同名の speckit-* スキルに対応します。 その他の内容は上流と同一で、変更していません。

---

ユーザー入力

$ARGUMENTS

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

実行前の確認

拡張フックを確認する（明確化の前）：

• プロジェクトのルートに .specify/extensions.yml があるか確認します。
• 存在する場合は内容を読み、hooks.before_clarify キーの下にあるエントリを探します。
• YAML を解析できない場合や無効な場合は、黙ってスキップせず、.specify/extensions.yml を読み込めなかったこと（パーサーのエラーを含む）と、そこに登録された必須（optional: false）フックを含め、フックを確認していないことをユーザーに伝えたうえで、通常どおり続行します。
• enabled が明示的に false のフックは除外します。enabled フィールドがないフックは、デフォルトで有効として扱います。
• 残った各フックについて、フックの condition 式を解釈したり評価したりしてはいけません。
  • condition フィールドがない場合、または null／空の場合は、フックを実行可能として扱います。
  • 空でない condition が定義されている場合は、フックをスキップし、条件の評価は HookExecutor の実装に任せます。
• 実行可能な各フックについて、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} の識別子そのものとは異なる場合があります。たとえば、スキルモードのエージェントでは /skill:speckit-... または $speckit-... として実行します）。ブロックを出力するだけではフックは実行されません。
• フックが登録されていない場合、または .specify/extensions.yml が存在しない場合は、何も表示せずスキップします。

概要

目的：有効な機能仕様における曖昧さや不足している意思決定事項を検出して減らし、明確化した内容を仕様ファイルに直接記録します。

注：この明確化ワークフローは、__SPECKIT_COMMAND_PLAN__ を呼び出す前に実行し、完了している必要があります。ユーザーが明確化を明示的に省略すると述べた場合（例：探索的なスパイク）は続行できますが、後続工程での手戻りのリスクが高まることを警告してください。

実行手順：

1. リポジトリのルートから {SCRIPT} を一度実行します（--json --paths-only の複合モード／-Json -PathsOnly）。最小限の JSON ペイロードから、次のフィールドを解析します。

   • FEATURE_DIR
   • FEATURE_SPEC
   • （必要に応じて、後続の連続フローに備えて IMPL_PLAN、TASKS を取得します。）
   • JSON の解析に失敗した場合は中断し、__SPECKIT_COMMAND_SPECIFY__ を再実行するか、機能ブランチの環境を確認するようユーザーに指示します。
   • "I'm Groot" のような引数内のシングルクォートは、エスケープ構文を使います。例：'I'''m Groot'（可能であればダブルクォートを使用："I'm Groot"）。

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

3. 現在の仕様ファイルを読み込みます。次の分類に基づいて、曖昧さと網羅性を体系的に確認します。各カテゴリの状態を「明確」「一部」「不足」として記録します。優先順位付けに使用する内部網羅性マップを作成します（質問をしない場合を除き、生のマップは出力しないでください）。

   機能の範囲と動作：

   • ユーザーの主な目標と成功基準
   • 明示的に対象外とする事項
   • ユーザーロール／ペルソナの違い ドメインとデータモデル：
   • エンティティ、属性、関係
   • 識別と一意性のルール
   • ライフサイクル／状態遷移
   • データ量／スケールの想定

   インタラクションと UX フロー：

   • 重要なユーザージャーニー／シーケンス
   • エラー／空／読み込み状態
   • アクセシビリティやローカライズに関する注記

   非機能品質特性：

   • パフォーマンス（レイテンシ、スループットの目標）
   • スケーラビリティ（水平／垂直、上限）
   • 信頼性と可用性（稼働時間、復旧に関する想定）
   • 可観測性（ログ、メトリクス、トレースのシグナル）
   • セキュリティとプライバシー（認証／認可、データ保護、脅威に関する想定）
   • コンプライアンス／規制上の制約（該当する場合）

   統合と外部依存関係：

   • 外部サービス／API と障害モード
   • データのインポート／エクスポート形式
   • プロトコル／バージョン管理の想定

   エッジケースと障害処理：

   • 想定外のシナリオ
   • レート制限／スロットリング
   • 競合解決（例：同時編集）

   制約とトレードオフ：

   • 技術的制約（言語、ストレージ、ホスティング）
   • 明示的なトレードオフ、または却下した代替案

   用語と一貫性：

   • 正式な用語集
   • 避ける同義語／非推奨用語

   完了の判断基準：

   • 受け入れ基準のテスト可能性
   • 測定可能な「完了の定義」形式の指標

   その他／プレースホルダー：

   • TODO マーカー／未解決の決定事項
   • 定量化されていない曖昧な形容詞（「堅牢」「直感的」など）

   Partial または Missing のステータスが付いている各カテゴリについて、以下に該当しない限り、候補となる質問を追加してください。

   • 明確化しても、実装や検証の方針が実質的に変わらない場合
   • 情報を計画フェーズまで保留するのが望ましい場合（内部で注記してください）

4. 候補となる確認質問の優先順位付きキューを（内部で）生成してください（最大 5 件）。一度にすべて出力しないでください。次の制約を適用してください。

   • セッション全体で質問は最大 5 件までです。
   • 各質問は、次のいずれかで回答できるものにしてください。
     • 短い選択式（相互に排他的な選択肢を 2～5 個）、または
     • 1 語／短い語句での回答（「5 語以内で回答してください」と明示）
   • 回答がアーキテクチャ、データモデリング、タスク分割、テスト設計、UX の動作、運用準備、またはコンプライアンス検証に実質的な影響を与える質問のみを含めてください。
   • カテゴリの網羅性のバランスを確保してください。影響の最も大きい未解決カテゴリを優先し、影響の小さい質問を 2 件尋ねるより、未解決の重要領域（セキュリティ方針など）を優先してください。
   • すでに回答済みの質問、些細なスタイル上の好み、計画段階の実行詳細（正確性を妨げる場合を除く）は含めないでください。
   • 後工程での手戻りリスクを減らす、または受け入れテストの不整合を防ぐ確認を優先してください。
   • 未解決のカテゴリが 5 件を超える場合は、（影響度 × 不確実性）のヒューリスティックに基づき、上位 5 件を選んでください。

5. 順番に質問するループ（対話形式）：

   • 一度に提示する質問は必ず1つだけにしてください。

   • 質問文の品質（選択式と短答式のすべての質問に適用）：

     • **Question:** に続けて、? で終わる完全な疑問文を記述してください。? より前の質問文だけで意味が通じる必要があります。
     • 質問そのものに、トピックラベル、セクション見出し、要件 ID を絶対に使わないでください。たとえば、Acceptance device/runtime matrix (FR-023) は無効です。これは質問ではなくラベルです。
     • ? の後に付けられるのは、任意の要件 ID／質問 ID を丸括弧で囲んだものだけです。正確な形式は **Question:** <疑問文>? または **Question:** <疑問文>? (FR-023) です。ID を ? より前に置いたり、ID 単独、またはトピックラベルと組み合わせたものを質問文全体として使ったりしないでください。
     • 質問行の直後、推奨事項／選択肢の前に、受け入れやリリースにとって重要な理由を平易な言葉で説明する「重要な理由」の文を1文加えてください。
     • 日常的な表現を使い、専門用語を導入する場合は同じ文の中で定義してください。自己確認として、Spec Kit を知らない読者でも質問行だけを見て答えられる必要があります。簡潔で構いませんが、意味が分かりにくいラベルは避けてください。

   • 選択式の質問の場合：

     • すべての選択肢を分析し、次の点に基づいて最適な選択肢を判断してください。
       • プロジェクトの種類に応じたベストプラクティス
       • 類似した実装でよく使われるパターン
       • リスクの低減（セキュリティ、パフォーマンス、保守性）
       • 仕様に明記されているプロジェクトの目標や制約との整合性
     • 推奨する選択肢を、明確な根拠（これが最適な理由を説明する1～2文）とともに先頭に目立つ形で提示してください。
     • 次の形式にしてください。**Recommended:** Option [X] - <reasoning>
     • 続いて、すべての選択肢を Markdown テーブルで示してください。

     選択肢	説明
     A	<選択肢 A の説明>
     B	<選択肢 B の説明>
     C	<選択肢 C の説明>（必要に応じて最大5つまで D／E を追加）
     Short	別の短い回答を入力（5語以内）（自由回答の代替が適切な場合のみ含める）

     • テーブルの後に、次の文を追加してください。You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.

   • 短答式の質問（意味のある個別の選択肢がない場合）の場合：

     • ベストプラクティスと文脈に基づく推奨回答を提示してください。
     • 次の形式にしてください。**Suggested:** <your proposed answer> - <brief reasoning>
     • 続けて、次の文を出力してください。Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.

   • ユーザーが回答した後：

     • ユーザーが "yes"、"recommended"、または "suggested" と回答した場合は、先に提示した推奨内容を回答として使用してください。
     • それ以外の場合は、回答がいずれかの選択肢に該当するか、5語以内の制約を満たしているかを確認してください。
     • 曖昧な場合は、簡潔な確認を求めてください（同じ質問の続きとして数え、次へ進まないでください）。
     • 回答が適切であれば、作業メモリに記録し（まだディスクには書き込まず）、次に待機している質問へ進んでください。

   • 次の場合は、それ以上質問しないでください。

     • 重要な曖昧さがすべて早い段階で解消され、残りの待機中の質問が不要になった場合、または
     • ユーザーが完了を示した場合（"done"、"good"、"no more"）、または
     • 質問数が5つに達した場合

   • 待機中の質問を事前に明かさないでください。

   • 最初に有効な質問がない場合は、重要な曖昧さがないことを直ちに報告してください。

6. 承認された各回答の後に統合（段階的な更新方式）：

   • 仕様のメモリ内表現（開始時に一度だけ読み込みます）と、ファイルの生の内容を保持します。
   • このセッションで最初に回答を統合する際：
     • ## Clarifications セクションが存在することを確認します。存在しない場合は、仕様テンプレートに従い、最上位のコンテキスト／概要セクションの直後に作成します。
     • その下に、本日の日付の ### Session YYYY-MM-DD 見出しを作成します（まだ存在しない場合）。
   • 承認後すぐに、次の箇条書きを追加します：- Q: <question> → A: <final answer>。
   • その後すぐに、確認内容を最も適切なセクションに反映します：
     • 機能に関する曖昧さ → Functional Requirements の箇条書きを更新または追加します。
     • ユーザーとのやり取り／アクターの区別 → 明確化された役割、制約、シナリオを、User Stories または Actors サブセクション（存在する場合）で更新します。
     • データの形状／エンティティ → 順序を維持しながら、Data Model にフィールド、型、関係を追加します。追加した制約は簡潔に記載します。
     • 非機能制約 → Success Criteria > Measurable Outcomes に、曖昧な形容表現を指標または明示的な目標値に変換して、測定可能な基準を追加または変更します。
     • エッジケース／異常フロー → Edge Cases / Error Handling の下に新しい箇条書きを追加します（または、テンプレートにプレースホルダーがある場合は該当するサブセクションを作成します）。
     • 用語の不一致 → 仕様全体で用語を統一します。元の表現を残す必要がある場合に限り、一度だけ (formerly referred to as "X") を追加します。
   • 明確化により以前の曖昧な記述が無効になる場合は、重複させずにその記述を置き換えます。矛盾する古い記述を残さないでください。
   • コンテキストの喪失を最小限に抑えるため、統合のたびに仕様ファイルを保存します（アトミックな上書き）。
   • 書式を維持します。無関係なセクションの順序を変更せず、見出し階層を保ちます。
   • 追加する明確化は、簡潔かつ検証可能なものにします（説明を不必要に膨らませないでください）。

7. 検証（書き込みのたび、および最終確認時に実施）：

   • Clarifications セッションに、承認された回答ごとに箇条書きがちょうど1つあること（重複がないこと）。
   • 質問数（承認済み）が5件以下であること。
   • 更新したセクションに、新しい回答で解消するはずの曖昧なプレースホルダーが残っていないこと。
   • 以前の記述に矛盾が残っていないこと（現在無効となった選択肢が削除されていることを確認します）。
   • Markdown の構造が有効であること。新たに追加できる見出しは ## Clarifications と ### Session YYYY-MM-DD のみです。
   • 用語の一貫性：更新したすべてのセクションで、同じ標準用語が使われていること。

8. 更新した仕様を FEATURE_SPEC に書き戻します。

9. 仕様品質チェックリストを再検証する（存在する場合）：

   • FEATURE_DIR/checklists/requirements.md が存在するか確認します。
   • 存在しない場合は、この手順を何も通知せずにスキップします。
   • 存在する場合：
     1. チェックリストファイルを読み込みます。
     2. コードフェンスの外にある、GitHub のタスクリストのチェックボックス行（- [ ]、- [x]、または - [X] に一致する行。大文字と小文字は区別せず、ネストされた項目の先頭の空白も許容）をすべて特定します。その他の内容（見出し、注記、チェックボックス以外の箇条書き、メタデータ）は無視します。
     3. 各チェックボックス行について、現在のマーカー状態（チェック済みまたは未チェック）と項目のテキストを記録し、変更前のスナップショットリストを作成します。
     4. 更新済みの仕様（手順 7 で保存したバージョン）に照らして、各チェックボックス項目を再評価します。
     5. チェック状態が実際に変わる場合に限り、各チェックボックス項目を更新します。
        • 項目に合格し、未チェックだった場合：[ ] を [x] に変更します。
        • 項目に不合格となり、チェック済みだった場合：[x]／[X] を [ ] に変更します。
        • 状態に変化がない場合：見た目だけの差分を避けるため、既存の大文字・小文字を保持し、マーカーをそのままにします。
     6. 更新したチェックリストファイルを保存します。**状態が変わったチェックボックス行の [ ]／[x] マーカー部分のみを切り替えてください。**差分が不必要に増えるのを避けるため、見出し、メタデータ、注記、行順、空白など、その他のファイル内容はすべて変更しないでください。
     7. 変更前のスナップショットと現在の状態を比較して、完了レポート用に次の 3 つのリストを作成します。
        • 新たに合格：未チェックからチェック済みに変わった項目。
        • 不合格への変更：チェック済みから未チェックに変わった項目。
        • 未チェックのまま：未チェックの状態が続いている項目。
     8. 変更前後の合格数を、チェック済み項目数／チェックボックス項目の総数として記録します（例：「12/16 → 15/16 項目が合格」）。

動作ルール：

• 重要な曖昧さが見つからない場合（または、考えられる質問がすべて影響の小さいものである場合）は、「正式な確認が必要な重大な曖昧さは検出されませんでした。」と回答し、次に進むことを提案します。
• 仕様ファイルが見つからない場合は、まず __SPECKIT_COMMAND_SPECIFY__ を実行するようユーザーに案内します（ここで新しい仕様を作成しないでください）。
• 質問は合計 5 件を超えてはいけません（1 つの質問に対する確認のやり取りは、新しい質問として数えません）。
• 機能要件の明確化を妨げる場合を除き、技術スタックについて推測に基づく質問を避けてください。
• ユーザーからの早期終了の合図（「stop」「done」「proceed」）を尊重してください。
• 網羅性が十分で質問がない場合は、簡潔な網羅状況の概要（すべてのカテゴリが「明確」）を示してから、次に進むことを提案します。
• 質問の上限に達しても影響の大きいカテゴリが未解決の場合は、理由を添えて「保留」項目として明示します。

優先順位付けのコンテキスト：{ARGS}

実行後に必須のフック

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

プロジェクトのルートに .specify/extensions.yml があるか確認します。

• 存在しない場合、または hooks.after_clarify の下に登録されたフックがない場合は、完了レポートに進みます。
• 存在する場合は読み込み、hooks.after_clarify キーの下にあるエントリを確認します。
• YAML を解析できない場合、または無効な場合は、黙ってスキップせず、.specify/extensions.yml を読み込めなかったこと（パーサーエラーを含む）と、そこに登録された必須（optional: false）フックも含め、フックを一切確認していないことをユーザーに伝えてから、完了レポートに進みます。
• enabled が明示的に false のフックを除外します。enabled フィールドがないフックは、デフォルトで有効として扱います。
• 残りの各フックについて、フックの condition 式を解釈または評価しようとしないでください。
  • フックに condition フィールドがない場合、またはその値が null／空の場合、フックは実行可能として扱います。
  • フックに空でない condition が定義されている場合はフックをスキップし、条件の評価は HookExecutor の実装に委ねます。
• 実行可能な各フックについて、optional フラグに基づいて次を出力します。
  • 必須フック（optional: false） — 必須フックごとに、必ず EXECUTE_COMMAND: を出力してください。

    ## 拡張フック
    
    **自動フック**：{extension}
    実行中：`/{command}`
    EXECUTE_COMMAND: {command}
    

    上記のブロックを出力した後、続行する前に必ず実際にフックを呼び出し、完了するまで待機してください。自分でこのエージェント／セッション内でコマンドを実行するのと同じ方法で実行してください（呼び出し方は、上記の {command} の ID 表記と異なる場合があります。たとえば、skills モードのエージェントでは /skill:speckit-... や $speckit-... のようになります）。ブロックを出力するだけでは実行したことになりません。
  • 任意フック（optional: true）：

    ## 拡張フック
    
    **任意フック**：{extension}
    コマンド：`/{command}`
    説明：{description}
    
    プロンプト：{prompt}
    実行するには：`/{command}`
    

完了レポート

（質問のやり取りが終了した後、または早期終了した後に）完了を報告します。

• 質問した数と回答済みの数。
• 更新した仕様のパス。
• 変更したセクション（名前の一覧）。
• 仕様品質チェックリストの状態（FEATURE_DIR/checklists/requirements.md を再検証した場合）：変更前／変更後の合格数（例：「仕様品質チェックリスト：12/16 → 15/16 項目が合格」）を示し、状態が変わった項目を列挙します。新たにチェックされた項目（未チェック → チェック済み）と、後退した項目（チェック済み → 未チェック）の両方を示してください。未チェック項目が残っている場合は、注意が必要な項目として列挙します。
• 各分類カテゴリとステータスを記載した網羅性の概要表：解決済み（部分的／不足していたが対応済み）、保留（質問数の上限を超える、または計画段階で扱うのが適切）、明確（すでに十分）、未解決（影響は小さいが、依然として部分的／不足）。
• 未解決または保留が残っている場合は、__SPECKIT_COMMAND_PLAN__ に進むか、計画後に改めて __SPECKIT_COMMAND_CLARIFY__ を実行するかを推奨します。
• 次に実行するコマンドを提案します。

完了条件

• 仕様の曖昧さを特定し、確認事項を仕様ファイルに反映した
• 仕様品質チェックリストが存在する場合は、更新した仕様に対して再検証した
• 上記「実行後に必須のフック」の規則に従って、拡張フックを呼び出すかスキップした
• 質問と回答、変更したセクション、チェックリストの状態、網羅性の概要を含めて、ユーザーに完了を報告した