speckit-checklist

チェックリストの目的：「英語のユニットテスト」

重要な概念：チェックリストは要件記述のユニットテストです。特定のドメインにおける要件の品質、明確さ、完全性を検証します。

検証やテストには使用しません：

• ❌ 「ボタンが正しくクリックできることを検証する」
• ❌ 「エラー処理が機能することをテストする」
• ❌ 「API が 200 を返すことを確認する」
• ❌ コードや実装が仕様に合っているかを確認する

要件の品質検証に使用します：

• ✅ 「すべてのカードタイプについて、視覚的な階層の要件が定義されていますか？」（完全性）
• ✅ 「『目立つ表示』は、具体的なサイズや配置で定量化されていますか？」（明確さ）
• ✅ 「すべてのインタラクティブな要素で、ホバー状態の要件に一貫性がありますか？」（一貫性）
• ✅ 「キーボードナビゲーションのアクセシビリティ要件が定義されていますか？」（網羅性）
• ✅ 「ロゴ画像の読み込みに失敗した場合の動作が仕様で定義されていますか？」（エッジケース）

たとえ：仕様が英語で書かれたコードだとすれば、チェックリストはそのユニットテストスイートです。テストするのは、要件が適切に記述され、完全で、曖昧さがなく、実装の準備ができているかどうかです。実装が動作するかどうかではありません。

所有権とチェックボックスのライフサイクル：

• このコマンドで生成するカスタムチェックリストは、レビュー担当者が所有する、要件品質のレビュー用成果物です。
• [x] は、レビュー担当者が要件品質の基準を満たしていると判断したことを意味します。
• [x] は、実装作業が完了したことを意味しません。
• このコマンドはチェックリスト項目を生成または追加します。生成した項目に [x] を付けてはいけません。
• エージェントは、レビュー担当者から明示的に依頼された場合にのみ、項目の評価を支援できます。
• checklists/requirements.md は /speckit-specify と /speckit-clarify が管理する、別個の組み込み仕様品質チェックリストです。この例外が、ここで生成するカスタムチェックリストにも適用されると解釈してはいけません。

ユーザー入力

$ARGUMENTS

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

実行前チェック

拡張フックを確認する（チェックリストの生成前）：

• プロジェクトのルートに .specify/extensions.yml が存在するか確認します。
• 存在する場合はその内容を読み、hooks.before_checklist キーの下にあるエントリを確認します。
• 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 Execution Steps.
    

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

• フックが登録されていない場合、または .specify/extensions.yml が存在しない場合は、何もせずに続行します。

実行手順

1. セットアップ：リポジトリのルートから .specify/scripts/bash/check-prerequisites.sh --json --template checklist-template を実行し、JSON を解析して FEATURE_DIR、AVAILABLE_DOCS リスト、TEMPLATE_CONTENT を取得します。

   • すべてのファイルパスは絶対パスでなければなりません。
   • "I'm Groot" のように引数にシングルクォートを含める場合は、エスケープ構文を使用します。例：'I'\''m Groot'（または可能であればダブルクォート："I'm Groot"）。

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

3. 意図を明確にする（動的）：事前に用意された質問集は使用せず、最初の状況に応じた確認質問を最大3つ導き出します。質問は次の条件を満たす必要があります。

   • ユーザーの表現と、仕様書／計画／タスクから抽出した手がかりに基づいて作成すること
   • チェックリストの内容を実質的に変える情報のみを尋ねること
   • $ARGUMENTS ですでに明確な場合は、個別に質問を省略すること
   • 幅広さよりも正確さを優先すること 生成アルゴリズム：
   1. シグナルを抽出します。機能領域のキーワード（例：auth、latency、UX、API）、リスク指標（「critical」「must」「compliance」）、関係者のヒント（「QA」「review」「security team」）、明示された成果物（「a11y」「rollback」「contracts」）を確認します。
   2. シグナルを候補となる重点領域（最大4つ）に分類し、関連性の高い順に並べます。
   3. 明示されていない場合は、想定される対象者とタイミング（作成者、レビュー担当者、QA、リリース）を特定します。
   4. 不足している観点を検出します。対象範囲の広さ、深さ／厳密さ、リスクの重視度、除外する範囲、測定可能な受け入れ基準を確認します。
   5. 次の類型から質問を作成します。
      • 対象範囲の明確化（例：「XとYとの統合ポイントも含めますか。それともローカルモジュールの正確性に限定しますか？」）
      • リスクの優先順位付け（例：「これらの潜在的なリスク領域のうち、必須のゲートチェックを設けるべきものはどれですか？」）
      • 深さの調整（例：「これは軽量なコミット前の確認リストですか。それとも正式なリリースゲートですか？」）
      • 対象者の明確化（例：「これは作成者のみが使いますか。それともPRレビューで同僚も使いますか？」）
      • 除外範囲の明確化（例：「今回はパフォーマンス調整項目を明示的に除外しますか？」）
      • シナリオ分類の不足（例：「復旧フローが検出されませんでした。ロールバック／部分的な障害への対応経路も対象に含めますか？」）

   質問の形式に関するルール：

   • 選択肢を提示する場合は、「Option | Candidate | Why It Matters」の列を持つ簡潔な表を作成します。
   • 選択肢はA～Eの最大5つまでとし、自由回答のほうが明確な場合は表を省略します。
   • ユーザーがすでに述べた内容を言い直すよう求めてはいけません。
   • 推測に基づく分類は避けます（捏造しない）。不確かな場合は、「Xが対象に含まれるか確認してください」と明示的に尋ねます。

   対話ができない場合のデフォルト：

   • 深さ：標準
   • 対象者：コード関連の場合はレビュー担当者（PR）、それ以外は作成者
   • 重点領域：関連性の高い上位2つの分類

   質問にはQ1/Q2/Q3のラベルを付けて出力します。回答後、シナリオ分類（代替／例外／復旧／非機能領域）のうち2つ以上が不明なままの場合は、理由を1行添えて（例：「復旧経路のリスクが未解決」）、追加の確認質問を最大2つ（Q4/Q5）まで行ってもかまいません。質問は合計5つを超えてはいけません。ユーザーが追加質問を明示的に断った場合は、追加確認を省略します。

4. ユーザーのリクエストを理解する：$ARGUMENTS と確認質問への回答を組み合わせます。

   • チェックリストのテーマ（例：セキュリティ、レビュー、デプロイ、UX）を導き出します。
   • ユーザーが明示した必須項目を統合します。
   • 選択された重点領域をカテゴリの枠組みに対応付けます。
   • 仕様／計画／タスクから不足しているコンテキストを推測します（捏造してはいけません）。

5. 機能のコンテキストを読み込む：FEATURE_DIR から次を読み込みます。

   • spec.md：機能要件と対象範囲
   • plan.md（存在する場合）：技術的な詳細と依存関係
   • tasks.md（存在する場合）：実装タスク

   コンテキストの読み込み方針：

   • 対象となる重点領域に関連する必要な部分のみを読み込みます（ファイル全体を出力することは避けます）。
   • 長いセクションは、簡潔なシナリオ／要件の箇条書きにまとめることを優先します。
   • 段階的に情報を開示し、不足が検出された場合にのみ追加の情報を取得します。
   • 元文書が大きい場合は、生の内容を埋め込む代わりに中間要約項目を作成します。

6. チェックリストを生成する — TEMPLATE_CONTENT を構造上のテンプレートとして使用し、「要件の単体テスト」を作成します。

   • FEATURE_DIR/checklists/ ディレクトリが存在しない場合は作成します。
   • 一意のチェックリストファイル名を生成します。
     • ドメインに基づく短く説明的な名前を使用します（例：ux.md、api.md、security.md）。
     • 形式：[domain].md
   • ファイルの扱い：
     • ファイルが存在しない場合：新しいファイルを作成し、項目番号は CHK001 から始めます。
     • ファイルが存在する場合：既存のファイルに項目を追記し、最後の CHK ID の次から番号を続けます（例：最後の項目が CHK015 の場合、新しい項目は CHK016 から始めます）。
   • 既存のチェックリストの内容を削除または置換してはいけません。常に保持して追記します。
   • 新しく生成する項目はすべて未チェック（[ ]）のままにします。チェックボックスの状態はレビュー担当者が決めます。 中核原則 - 実装ではなく要件をテストする： チェックリストの各項目では、以下の観点から要件そのものを必ず評価してください。
   • 完全性：必要な要件がすべて含まれていますか？
   • 明確性：要件は曖昧さがなく、具体的ですか？
   • 一貫性：要件同士は整合していますか？
   • 測定可能性：要件を客観的に検証できますか？
   • 網羅性：すべてのシナリオやエッジケースに対応していますか？

   カテゴリ構成 - 要件の品質の観点ごとに項目をまとめます。

   • 要件の完全性（必要な要件がすべて文書化されていますか？）
   • 要件の明確性（要件は具体的で、曖昧さがありませんか？）
   • 要件の一貫性（要件同士に矛盾なく整合していますか？）
   • 受け入れ基準の品質（成功基準は測定可能ですか？）
   • シナリオの網羅性（すべてのフローやケースに対応していますか？）
   • エッジケースの網羅性（境界条件は定義されていますか？）
   • 非機能要件（パフォーマンス、セキュリティ、アクセシビリティなどは指定されていますか？）
   • 依存関係と前提条件（文書化され、検証されていますか？）
   • 曖昧さと矛盾（何を明確にする必要がありますか？）

   チェックリスト項目の書き方 - 「英語のユニットテスト」：

   ❌ 誤り（実装をテストする）：

   • 「ランディングページにエピソードカードが3枚表示されることを確認する」
   • 「デスクトップでホバー状態が機能することをテストする」
   • 「ロゴをクリックするとホームに移動することを確認する」

   ✅ 正しい（要件の品質をテストする）：

   • 「注目エピソードの正確な数とレイアウトは指定されていますか？」[完全性]
   • 「『目立つ表示』は具体的なサイズや配置で定量化されていますか？」[明確性]
   • 「ホバー状態の要件は、すべてのインタラクティブ要素で一貫していますか？」[一貫性]
   • 「すべてのインタラクティブ UI に対するキーボード操作の要件は定義されていますか？」[網羅性]
   • 「ロゴ画像の読み込みに失敗した場合の代替動作は指定されていますか？」[エッジケース]
   • 「非同期のエピソードデータに対する読み込み状態は定義されていますか？」[完全性]
   • 「競合する UI 要素の視覚的階層は仕様で定義されていますか？」[明確性]

   項目の構成： 各項目は、次のパターンに従ってください。

   • 要件の品質について尋ねる質問形式にする
   • 仕様や計画に何が記載されているか（または記載されていないか）に焦点を当てる
   • 品質の観点を角括弧内に記載する [完全性/明確性/一貫性など]
   • 既存の要件を確認する場合は、仕様のセクション [Spec §X.Y] を参照する
   • 要件の欠落を確認する場合は、[Gap] マーカーを使用する

   品質の観点ごとの例：

   完全性：

   • 「すべての API 障害モードに対するエラー処理要件は定義されていますか？[Gap]」
   • 「すべてのインタラクティブ要素に対するアクセシビリティ要件は指定されていますか？[完全性]」
   • 「レスポンシブレイアウトに対するモバイルのブレークポイント要件は定義されていますか？[Gap]」

   明確性：

   • 「『高速な読み込み』は具体的な時間のしきい値で定量化されていますか？[明確性, Spec §NFR-2]」
   • 「『関連エピソード』の選定基準は明示的に定義されていますか？[明確性, Spec §FR-5]」
   • 「『目立つ』は測定可能な視覚的特性で定義されていますか？[曖昧さ, Spec §FR-4]」

   一貫性：

   • 「ナビゲーション要件はすべてのページで整合していますか？[一貫性, Spec §FR-10]」
   • 「カードコンポーネントの要件はランディングページと詳細ページで一貫していますか？[一貫性]」

   網羅性：

   • 「ゼロ状態のシナリオ（エピソードがない場合）に対する要件は定義されていますか？[網羅性, エッジケース]」
   • 「ユーザーが同時に操作するシナリオに対応していますか？[網羅性, Gap]」
   • 「データの一部の読み込みに失敗した場合の要件は指定されていますか？[網羅性, 例外フロー]」

   測定可能性：

   • 「視覚的階層の要件は測定またはテストできますか？[受け入れ基準, Spec §FR-1]」
   • 「『バランスの取れた視覚的な重み』を客観的に検証できますか？[測定可能性, Spec §FR-2]」 シナリオの分類と網羅性（要件品質を重視）：
   • 次のシナリオに関する要件が存在するか確認します：主要、代替、例外／エラー、復旧、非機能
   • 各シナリオ分類について、次のように質問します：「[シナリオの種類] の要件は完全で、明確で、一貫していますか？」
   • シナリオ分類が欠けている場合：「[シナリオの種類] の要件は意図的に除外されていますか、それとも不足していますか？ [Gap]」
   • 状態変更が発生する場合は、レジリエンス／ロールバックを含めます：「移行に失敗した場合のロールバック要件は定義されていますか？ [Gap]」

   トレーサビリティ要件：

   • 最低基準：項目の80％以上に、少なくとも1つのトレーサビリティ参照を含める必要があります
   • 各項目では、仕様のセクション [Spec §X.Y] を参照するか、次のマーカーを使用します：[Gap]、[Ambiguity]、[Conflict]、[Assumption]
   • ID の仕組みが存在しない場合：「要件と受け入れ基準の ID 体系は確立されていますか？ [Traceability]」

   問題の洗い出しと解決（要件品質の問題）： 要件そのものについて質問します：

   • 曖昧さ：「『高速』という用語は具体的な指標で数値化されていますか？ [Ambiguity, Spec §NFR-1]」
   • 矛盾：「ナビゲーション要件は §FR-10 と §FR-10a の間で矛盾していますか？ [Conflict]」
   • 仮定：「『ポッドキャスト API は常に利用可能』という仮定は検証されていますか？ [Assumption]」
   • 依存関係：「外部ポッドキャスト API の要件は文書化されていますか？ [Dependency, Gap]」
   • 定義の不足：「『視覚的階層』は測定可能な基準で定義されていますか？ [Gap]」

   内容の統合：

   • 上限の目安：候補項目の生データが40件を超える場合は、リスク／影響度に基づいて優先順位を付けます
   • 同じ要件の側面を確認する重複に近い項目を統合します
   • 影響度の低いエッジケースが5件を超える場合は、次のような項目を1つ作成します：「X、Y、Z のエッジケースは要件で扱われていますか？ [Coverage]」

   🚫 絶対に禁止 — これらは要件テストではなく実装テストになります：

   • ❌ 実装の動作について、「Verify」「Test」「Confirm」「Check」で始まる項目
   • ❌ コードの実行、ユーザー操作、システムの動作への言及
   • ❌ 「正しく表示される」「適切に動作する」「期待どおりに機能する」
   • ❌ 「Click」「navigate」「render」「load」「execute」
   • ❌ テストケース、テスト計画、QA 手順
   • ❌ 実装の詳細（フレームワーク、API、アルゴリズム）

   ✅ 必須のパターン — これらは要件品質を確認します：

   • ✅ 「[シナリオ] に対する [要件の種類] は定義／指定／文書化されていますか？」
   • ✅ 「[曖昧な用語] は具体的な基準で数値化／明確化されていますか？」
   • ✅ 「[セクション A] と [セクション B] の要件に一貫性はありますか？」
   • ✅ 「[要件] は客観的に測定／検証できますか？」
   • ✅ 「[エッジケース／シナリオ] は要件で扱われていますか？」
   • ✅ 「仕様では [不足している側面] が定義されていますか？」

7. 構成の参照：タイトル、メタセクション、カテゴリ見出し、担当者に関する注記、メモセクション、ID 形式については、.specify/templates/checklist-template.md の標準テンプレートに従ってチェックリストを作成します。テンプレートを利用できない場合は、次の形式を使用します：H1 タイトル、目的／作成日のメタ情報、[x] は要件品質に対するレビュアーの承認を意味するという担当者に関する注記、グローバルに連番となる CHK001 から始まる ID を付けた - [ ] CHK### <要件項目> 行を含む ## カテゴリセクション、チェックリストの状態を読み取るがマーカーは変更しないことを示す /speckit-implement に関するメモ。

8. 報告：チェックリストファイルのフルパス、項目数、新規ファイルを作成したか既存ファイルに追記したかの概要を出力します。次の内容も要約します：

   • 選択した重点領域
   • 詳細度
   • 担当者／タイミング
   • ユーザーが明示した必須項目のうち、反映したもの

重要：/speckit-checklist コマンドを実行するたびに、短く分かりやすいチェックリストファイル名を使用し、新規作成するか既存ファイルに追記します。これにより、次のことが可能になります：

• 種類の異なる複数のチェックリスト（例：ux.md、test.md、security.md）
• チェックリストの目的が分かる、シンプルで覚えやすいファイル名
• checklists/ フォルダー内での識別と移動が容易 散らかるのを避けるため、内容が分かる型を使い、不要になったチェックリストは削除してください。

チェックリストの型と項目例

UX 要件の品質: ux.md

項目例（実装ではなく、要件をテストします）：

• 「視覚的な階層の要件は、測定可能な基準とともに定義されていますか？ [明確性、仕様 §FR-1]」
• 「UI 要素の数と配置は明示的に指定されていますか？ [完全性、仕様 §FR-1]」
• 「操作状態の要件（ホバー、フォーカス、アクティブ）は一貫して定義されていますか？ [一貫性]」
• 「すべてのインタラクティブ要素について、アクセシビリティ要件が指定されていますか？ [網羅性]」
• 「画像の読み込みに失敗した場合のフォールバック動作は定義されていますか？ [エッジケース、漏れ]」
• 「『目立つ表示』を客観的に測定できますか？ [測定可能性、仕様 §FR-4]」

API 要件の品質: api.md

項目例：

• 「すべての失敗シナリオについて、エラーレスポンスの形式が指定されていますか？ [完全性]」
• 「レート制限の要件は、具体的なしきい値を用いて定量化されていますか？ [明確性]」
• 「認証要件は、すべてのエンドポイントで一貫していますか？ [一貫性]」
• 「外部依存関係に対する再試行／タイムアウトの要件は定義されていますか？ [網羅性、漏れ]」
• 「バージョニング戦略は要件に記載されていますか？ [漏れ]」

パフォーマンス要件の品質: performance.md

項目例：

• 「パフォーマンス要件は、具体的な指標を用いて定量化されていますか？ [明確性]」
• 「重要なユーザージャーニーすべてについて、パフォーマンス目標が定義されていますか？ [網羅性]」
• 「さまざまな負荷条件下でのパフォーマンス要件が指定されていますか？ [完全性]」
• 「パフォーマンス要件を客観的に測定できますか？ [測定可能性]」
• 「高負荷シナリオにおける性能劣化の要件は定義されていますか？ [エッジケース、漏れ]」

セキュリティ要件の品質: security.md

項目例：

• 「すべての保護対象リソースについて、認証要件が指定されていますか？ [網羅性]」
• 「機密情報に対するデータ保護要件が定義されていますか？ [完全性]」
• 「脅威モデルが文書化され、要件がそれに沿っていますか？ [トレーサビリティ]」
• 「セキュリティ要件は、コンプライアンス上の義務と一貫していますか？ [一貫性]」
• 「セキュリティ上の障害／侵害への対応要件が定義されていますか？ [漏れ、例外フロー]」

悪い例：避けるべきこと

❌ 誤り — 要件ではなく、実装をテストしています：

- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]

✅ 正しい — 要件の品質をテストしています：

- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]

主な違い：

• 誤り：システムが正しく動作するかをテストする
• 正しい：要件が正しく記述されているかをテストする
• 誤り：動作の検証
• 正しい：要件の品質の妥当性確認
• 誤り：「Xを実行しますか？」
• 正しい：「Xは明確に指定されていますか？」

実行後のチェック

拡張フックを確認する（チェックリストの生成後）： プロジェクトのルートに .specify/extensions.yml が存在するか確認します。

• 存在する場合は読み込み、hooks.after_checklist キーの下にあるエントリを確認します
• 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 Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

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

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

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

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