speckit.checklist

Prompt file imported from Chabana1591/my-project (.codex/prompts/speckit.checklist.md). Fill in {{arguments}} before use. Copyright stays with the author.

チェックリストの目的: 「要件のユニットテスト」

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

検証/テスト用ではありません:

• ❌ 「ボタンが正しくクリックされることを確認する」ではない
• ❌ 「エラーハンドリングが動作することをテストする」ではない
• ❌ 「API が 200 を返すことを確認する」ではない
• ❌ コード/実装が仕様と一致するかをチェックするものではない

要件品質の検証用:

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

メタファー: 仕様が自然言語で書かれたコードなら、チェックリストはそのユニットテストスイートです。要件が適切に書かれ、完全で、曖昧さがなく、実装の準備ができているかをテストしています。実装が動作するかどうかではありません。

ユーザー入力

{{arguments}}

続行する前に、ユーザー入力を必ず考慮してください（空でない場合）。

実行ステップ

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

   • すべてのファイルパスは絶対パスである必要があります。
   • "I'm Groot" のような引数内のシングルクォートには、エスケープ構文を使用してください：例 'I'''m Groot'（または可能であればダブルクォート: "I'm Groot"）。

2. 意図の明確化（動的）: 最大 3 つの初期コンテキスト明確化質問を導出します（事前に用意されたカタログなし）。以下の条件を満たす必要があります：

   • ユーザーの表現 + spec/plan/tasks から抽出されたシグナルから生成
   • チェックリストの内容を実質的に変更する情報についてのみ質問
   • {{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 レビュー中に同僚も使用しますか？」）
      • 境界の除外（例: 「今回はパフォーマンスチューニング項目を明示的に除外すべきですか？」）
      • シナリオクラスのギャップ（例: 「リカバリフローが検出されませんでした - ロールバック/部分的な失敗パスはスコープ内ですか？」）

   質問のフォーマットルール:

   • オプションを提示する場合、列を持つコンパクトなテーブルを生成: オプション | 候補 | 重要な理由
   • 最大 A〜E オプションに制限；自由形式の回答がより明確な場合はテーブルを省略
   • ユーザーが既に言ったことを繰り返すことを求めない
   • 推測的なカテゴリを避ける（幻覚なし）。不確かな場合は明示的に尋ねる: 「X がスコープ内に含まれることを確認してください。」

   インタラクションが不可能な場合のデフォルト:

   • 深さ: 標準
   • 対象者: コード関連の場合はレビュアー（PR）；それ以外は作成者
   • フォーカス: 上位 2 つの関連性クラスタ

   質問を出力します（Q1/Q2/Q3 とラベル付け）。回答後: ≥2 のシナリオクラス（代替 / 例外 / リカバリ / 非機能ドメイン）が不明確なままの場合、最大 2 つのターゲット追加フォローアップ（Q4/Q5）を 1 行の正当化とともに尋ねてもよい（例: 「未解決のリカバリパスリスク」）。合計 5 つの質問を超えないでください。ユーザーが明示的にこれ以上を拒否した場合はエスカレーションをスキップ。

3. ユーザーリクエストの理解: {{arguments}} + 明確化回答を組み合わせる:

   • チェックリストテーマを導出（例: security、review、deploy、ux）
   • ユーザーが言及した明示的な必須項目を統合
   • フォーカス選択をカテゴリスキャフォールディングにマップ
   • spec/plan/tasks から欠落しているコンテキストを推測（幻覚しないでください）

4. 機能コンテキストの読み込み: FEATURE_DIR から読み込む:

   • spec.md: 機能要件とスコープ
   • plan.md（存在する場合）: 技術詳細、依存関係
   • tasks.md（存在する場合）: 実装タスク

   コンテキスト読み込み戦略:

   • アクティブなフォーカスエリアに関連する必要な部分のみを読み込む（ファイル全体のダンプを避ける）
   • 長いセクションを簡潔なシナリオ/要件の箇条書きに要約することを優先
   • 段階的開示を使用: ギャップが検出された場合にのみフォローオンの取得を追加
   • ソースドキュメントが大きい場合、生のテキストを埋め込む代わりに中間サマリー項目を生成

5. チェックリストの生成 - 「要件のユニットテスト」を作成:

   • FEATURE_DIR/checklists/ ディレクトリが存在しない場合は作成
   • 一意のチェックリストファイル名を生成:
     • ドメインに基づいた短く説明的な名前を使用（例: ux.md、api.md、security.md）
     • 形式: [domain].md
     • ファイルが存在する場合は既存のファイルに追加
   • 項目に CHK001 から始まる連番を付ける
   • 各 /speckit.checklist 実行は新しいファイルを作成（既存のチェックリストを上書きしない）

   コア原則 - 実装ではなく要件をテスト: すべてのチェックリスト項目は、以下について要件自体を評価する必要があります：

   • 完全性: 必要な要件がすべて存在するか？
   • 明確さ: 要件は曖昧さがなく具体的か？
   • 一貫性: 要件は互いに整合しているか？
   • 測定可能性: 要件は客観的に検証可能か？
   • カバレッジ: すべてのシナリオ/エッジケースが対処されているか？

   カテゴリ構造 - 要件品質の次元でグループ化:

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

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

   ❌ 間違い（実装をテスト）:

   • 「ランディングページに 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]、[曖昧さ]、[競合]、[仮定]
   • ID システムが存在しない場合: 「要件と受け入れ基準の ID スキームが確立されていますか？ [トレーサビリティ]」

   問題の表面化と解決（要件品質の問題）: 要件自体について質問:

   • 曖昧さ: 「'高速' という用語は具体的なメトリクスで定量化されていますか？ [曖昧さ, Spec §NFR-1]」
   • 競合: 「§FR-10 と §FR-10a の間でナビゲーション要件が競合していますか？ [競合]」
   • 仮定: 「'常に利用可能なポッドキャスト API' の仮定は検証されていますか？ [仮定]」
   • 依存関係: 「外部ポッドキャスト API 要件が文書化されていますか？ [依存関係, Gap]」
   • 定義の欠落: 「'視覚的階層' は測定可能な基準で定義されていますか？ [Gap]」

   コンテンツの統合:

   • ソフトキャップ: 生の候補項目が 40 を超える場合、リスク/影響で優先順位付け
   • 同じ要件側面をチェックするほぼ重複をマージ
   • 低影響のエッジケースが 5 を超える場合、1 つの項目を作成: 「エッジケース X、Y、Z は要件で対処されていますか？ [カバレッジ]」

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

   • ❌ 「確認する」、「テストする」、「確かめる」、「チェックする」+ 実装動作で始まる項目
   • ❌ コード実行、ユーザーアクション、システム動作への参照
   • ❌ 「正しく表示される」、「適切に動作する」、「期待通りに機能する」
   • ❌ 「クリック」、「ナビゲート」、「レンダリング」、「読み込み」、「実行」
   • ❌ テストケース、テスト計画、QA 手順
   • ❌ 実装詳細（フレームワーク、API、アルゴリズム）

   ✅ 必須パターン - これらは要件品質をテスト:

   • ✅ 「[要件タイプ] は [シナリオ] に対して定義/指定/文書化されていますか？」
   • ✅ 「[曖昧な用語] は具体的な基準で定量化/明確化されていますか？」
   • ✅ 「要件は [セクション A] と [セクション B] の間で一貫していますか？」
   • ✅ 「[要件] は客観的に測定/検証可能ですか？」
   • ✅ 「[エッジケース/シナリオ] は要件で対処されていますか？」
   • ✅ 「仕様は [欠落している側面] を定義していますか？」

6. 構造参照: .specify/templates/checklist-template.md の正規テンプレートに従ってチェックリストを生成し、タイトル、メタセクション、カテゴリ見出し、ID フォーマットを使用します。テンプレートが利用できない場合は、以下を使用: H1 タイトル、purpose/created メタ行、CHK001 から始まるグローバルにインクリメントする ID を持つ - [ ] CHK### <要件項目> 行を含む ## カテゴリセクション。

7. レポート: 作成されたチェックリストへのフルパス、項目数を出力し、各実行で新しいファイルが作成されることをユーザーに通知します。要約:

   • 選択されたフォーカスエリア
   • 深さレベル
   • アクター/タイミング
   • 組み込まれたユーザー指定の必須項目

重要: 各 /speckit.checklist コマンド呼び出しは、ファイルが既に存在しない限り、短く説明的な名前を使用してチェックリストファイルを作成します。これにより:

• 異なるタイプの複数のチェックリスト（例: ux.md、test.md、security.md）
• チェックリストの目的を示すシンプルで覚えやすいファイル名
• checklists/ フォルダでの簡単な識別とナビゲーション

混乱を避けるため、説明的なタイプを使用し、完了したら古いチェックリストをクリーンアップしてください。

チェックリストタイプと項目の例

UX 要件品質: ux.md

項目の例（実装ではなく要件をテスト）:

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

API 要件品質: api.md

項目の例:

• 「すべての障害シナリオにエラーレスポンス形式が指定されていますか？ [完全性]」
• 「レート制限要件は具体的な閾値で定量化されていますか？ [明確さ]」
• 「認証要件はすべてのエンドポイントで一貫していますか？ [一貫性]」
• 「外部依存関係のリトライ/タイムアウト要件が定義されていますか？ [カバレッジ, Gap]」
• 「バージョニング戦略は要件に文書化されていますか？ [Gap]」

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

項目の例:

• 「パフォーマンス要件は具体的なメトリクスで定量化されていますか？ [明確さ]」
• 「すべてのクリティカルユーザージャーニーにパフォーマンス目標が定義されていますか？ [カバレッジ]」
• 「異なる負荷条件下でのパフォーマンス要件が指定されていますか？ [完全性]」
• 「パフォーマンス要件は客観的に測定可能ですか？ [測定可能性]」
• 「高負荷シナリオの劣化要件が定義されていますか？ [エッジケース, Gap]」

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

項目の例:

• 「すべての保護リソースに認証要件が指定されていますか？ [カバレッジ]」
• 「機密情報にデータ保護要件が定義されていますか？ [完全性]」
• 「脅威モデルが文書化され、要件はそれに整合していますか？ [トレーサビリティ]」
• 「セキュリティ要件はコンプライアンス義務と一貫していますか？ [一貫性]」
• 「セキュリティ障害/侵害対応要件が定義されていますか？ [Gap, 例外フロー]」

アンチパターン: やってはいけないこと

❌ 間違い - これらは要件ではなく実装をテスト:

- [ ] CHK001 - ランディングページに 3 つのエピソードカードが表示されることを確認 [Spec §FR-001]
- [ ] CHK002 - デスクトップでホバー状態が正しく動作することをテスト [Spec §FR-003]
- [ ] CHK003 - ロゴクリックでホームページに移動することを確認 [Spec §FR-010]
- [ ] CHK004 - 関連エピソードセクションが 3〜5 項目を表示することをチェック [Spec §FR-005]

✅ 正しい - これらは要件品質をテスト:

- [ ] CHK001 - 注目エピソードの数とレイアウトは明示的に指定されていますか？ [完全性, Spec §FR-001]
- [ ] CHK002 - ホバー状態の要件はすべてのインタラクティブ要素で一貫して定義されていますか？ [一貫性, Spec §FR-003]
- [ ] CHK003 - クリック可能なブランド要素のナビゲーション要件は明確ですか？ [明確さ, Spec §FR-010]
- [ ] CHK004 - 関連エピソードの選択基準は文書化されていますか？ [Gap, Spec §FR-005]
- [ ] CHK005 - 非同期エピソードデータのローディング状態要件が定義されていますか？ [Gap]
- [ ] CHK006 - 「視覚的階層」要件は客観的に測定可能ですか？ [測定可能性, Spec §FR-001]

主な違い:

• 間違い: システムが正しく動作するかをテスト
• 正しい: 要件が正しく書かれているかをテスト
• 間違い: 動作の検証
• 正しい: 要件品質の検証
• 間違い: 「X は動作しますか？」
• 正しい: 「X は明確に指定されていますか？」