チェックリストの目的: 「ユニットテスト for 英語の仕様」
重要概念: チェックリストは 要件記述のユニットテスト です。特定ドメインにおける要件の品質、明確さ、完全性を検証します。
検証/テストではありません:
- ❌ 「ボタンが正しくクリックされることを確認する」
- ❌ 「エラーハンドリングが動作することをテストする」
- ❌ 「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} コマンド: `/{command}` 説明: {description} プロンプト: {prompt} 実行するには: `/{command}` - 必須フック (
optional: false):
上記のブロックを出力した後、実際にフックを呼び出し、その終了を待ってから続行する必要があります。このエージェント/セッションでコマンド自体を実行するのと同じ方法で実行します(呼び出し方法は上記のリテラルな## 拡張フック **自動プリフック**: {extension} 実行中: `/{command}` EXECUTE_COMMAND: {command} 実行ステップに進む前に、フックコマンドの結果を待ちます。{command}ID と異なる場合があります。たとえば、スキルモードのエージェントは/skill:speckit-...または$speckit-...として実行します)。ブロックを出力するだけではフックは実行されません。
- オプショナルフック (
- フックが登録されていない場合、または
.specify/extensions.ymlが存在しない場合は、静かにスキップします。
実行ステップ
-
セットアップ: リポジトリルートから
.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")を使用します。
-
存在する場合:
.specify/memory/constitution.mdを読み込み、プロジェクトの原則とガバナンスの制約を取得します。 -
意図の明確化(動的): 最大3つの初期コンテキスト明確化質問を導き出します(事前定義されたカタログは使用しません)。これらは以下を満たす必要があります:
- ユーザーの表現 + 仕様/計画/タスクから抽出されたシグナルから生成される
- チェックリストの内容に実質的に影響を与える情報についてのみ質問する
$ARGUMENTSですでに明確な場合は個別にスキップする- 幅広さよりも正確さを優先する
生成アルゴリズム:
- シグナルを抽出: 機能ドメインのキーワード(例: auth, latency, UX, API)、リスク指標("critical", "must", "compliance")、ステークホルダーへのヒント("QA", "review", "security team")、明示的な成果物("a11y", "rollback", "contracts")。
- シグナルを候補のフォーカスエリア(最大4つ)にクラスタリングし、関連性でランク付けします。
- 明示的でない場合は、想定されるオーディエンスとタイミング(作成者、レビュアー、QA、リリース)を特定します。
- 欠落している次元を検出: スコープの広さ、深さ/厳密さ、リスクの強調、除外境界、測定可能な受け入れ基準。
- 以下のアーキタイプから選択した質問を formulation します:
- スコープの絞り込み(例: 「これには X と Y との統合タッチポイントを含めるべきですか、それともローカルモジュールの正確性に限定すべきですか?」)
- リスクの優先順位付け(例: 「これらの潜在的なリスク領域のうち、必須ゲートチェックを受けるべきものはどれですか?」)
- 深さの調整(例: 「これは軽量なコミット前の sanity リストですか、それとも正式なリリースゲートですか?」)
- オーディエンスのフレーミング(例: 「これは作成者のみが使用するものですか、それとも PR レビュー中にピアも使用しますか?」)
- 境界の除外(例: 「今回のラウンドではパフォーマンスチューニングの項目を明示的に除外すべきですか?」)
- シナリオクラスのギャップ(例: 「リカバリフローが検出されませんでした。ロールバック/部分障害パスはスコープ内ですか?」)
質問のフォーマットルール:
- オプションを提示する場合は、次の列を持つコンパクトなテーブルを生成します: オプション | 候補 | なぜ重要か
- オプションは最大で A~E に制限し、自由形式の回答の方が明確な場合はテーブルを省略します
- ユーザーがすでに述べたことを再度述べさせるような質問は決してしないでください
- 推測によるカテゴリを避ける(幻覚を起こさない)。不確かな場合は、明示的に「X がスコープに含まれるか確認してください」と質問します。
対話が不可能な場合のデフォルト:
- 深さ: 標準
- オーディエンス: コード関連の場合はレビュアー(PR)、それ以外は作成者
- フォーカス: 関連性の高いトップ2クラスタ
質問を出力します(Q1/Q2/Q3 とラベル付け)。回答後: 2つ以上のシナリオクラス(代替 / 例外 / リカバリ / 非機能ドメイン)が不明確なままの場合は、最大2つの追加フォローアップ質問(Q4/Q5)を、それぞれ1行の正当化(例:「未解決のリカバリパスリスク」)とともに質問してもかまいません。合計質問数は5を超えないようにしてください。ユーザーが明示的に追加を拒否した場合は、エスカレーションをスキップします。
-
ユーザーリクエストを理解する:
$ARGUMENTS+ 明確化の回答を組み合わせます:- チェックリストのテーマを導き出す(例: セキュリティ、レビュー、デプロイ、UX)
- ユーザーが言及した明示的な必須アイテムを統合する
- フォーカスの選択をカテゴリの枠組みにマッピングする
- 仕様/計画/タスクから欠落しているコンテキストを推測する(幻覚を起こさない)
-
機能コンテキストを読み込む: FEATURE_DIR から以下を読み込みます:
- spec.md: 機能の要件とスコープ
- plan.md(存在する場合): 技術的な詳細、依存関係
- tasks.md(存在する場合): 実装タスク
コンテキスト読み込み戦略:
- アクティブなフォーカスエリアに関連する必要な部分のみを読み込む(全ファイルのダンプを避ける)
- 長いセクションは、簡潔なシナリオ/要件の箇条書きに要約することを優先する
- 段階的な開示を使用する: ギャップが検出された場合にのみ、追加の取得を実行する
- ソースドキュメントが大きい場合は、生のテキストを埋め込む代わりに中間サマリーアイテムを生成する
-
チェックリストを生成する - TEMPLATE_CONTENT を構造テンプレートとして使用し、「要件のユニットテスト」を作成します:
- 存在しない場合は
FEATURE_DIR/checklists/ディレクトリを作成します - 一意のチェックリストファイル名を生成します:
- ドメインに基づいた、短く説明的な名前を使用します(例:
ux.md,api.md,security.md) - 形式:
[domain].md
- ドメインに基づいた、短く説明的な名前を使用します(例:
- ファイルの処理動作:
- ファイルが存在しない場合: 新しいファイルを作成し、CHK001 からアイテムに番号を付けます
- ファイルが存在する場合: 既存のファイルに新しいアイテムを追加し、最後の CHK ID から続行します(例: 最後のアイテムが CHK015 の場合、新しいアイテムは CHK016 から開始)
- 既存のチェックリストの内容を削除または置き換えないでください。常に保存して追加します
- 新しく生成されたすべてのアイテムはチェックなし(
[ ])のままにします。チェックボックスの状態はレビュアーに属します
中核原則 - 実装ではなく要件をテストする: すべてのチェックリストアイテムは、要件自体を以下の観点で評価する必要があります:
- 完全性: 必要な要件がすべて存在していますか?
- 明確さ: 要件は曖昧でなく、具体的ですか?
- 一貫性: 要件は互いに矛盾なく整合していますか?
- 測定可能性: 要件は客観的に検証できますか?
- カバレッジ: すべてのシナリオ/エッジケースが対処されていますか?
カテゴリ構造 - 要件品質の次元ごとにアイテムをグループ化:
- 要件の完全性(必要な要件はすべて文書化されていますか?)
- 要件の明確さ(要件は具体的で曖昧さがありませんか?)
- 要件の一貫性(要件は矛盾なく整合していますか?)
- 受け入れ基準の品質(成功基準は測定可能ですか?)
- シナリオカバレッジ(すべてのフロー/ケースが対処されていますか?)
- エッジケースカバレッジ(境界条件は定義されていますか?)
- 非機能要件(パフォーマンス、セキュリティ、アクセシビリティなど - それらは指定されていますか?)
- 依存関係と前提条件(それらは文書化され、検証されていますか?)
- 曖昧さと競合(明確化が必要なものは何ですか?)
チェックリストアイテムの書き方 - 「ユニットテスト for 英語の仕様」:
❌ 間違い(実装のテスト):
- 「ランディングページに3つのエピソードカードが表示されることを確認する」
- 「デスクトップでホバー状態が機能することをテストする」
- 「ロゴのクリックでホームに移動することを確認する」
✅ 正しい(要件品質のテスト):
- 「注目エピソードの正確な数とレイアウトが指定されていますか?」 [完全性]
- 「'目立つ表示' は具体的なサイズ/配置で定量化されていますか?」 [明確さ]
- 「すべてのインタラクティブ要素でホバー状態の要件は一貫していますか?」 [一貫性]
- 「すべてのインタラクティブ UI でキーボードナビゲーションの要件が定義されていますか?」 [カバレッジ]
- 「ロゴ画像の読み込みに失敗した場合のフォールバック動作は指定されていますか?」 [エッジケース]
- 「非同期エピソードデータのローディング状態は定義されていますか?」 [完全性]
- 「競合する UI 要素の視覚的階層を仕様は定義していますか?」 [明確さ]
アイテム構造: 各アイテムは次のパターンに従う必要があります:
- 要件の品質について質問する形式
- 仕様/計画に書かれていること(または書かれていないこと) に焦点を当てる
- 品質次元を角括弧で含める [完全性/明確さ/一貫性/など]
- 既存の要件を確認する場合は仕様セクション
[仕様 §X.Y]を参照 - 欠落している要件を確認する場合は
[ギャップ]マーカーを使用する
品質次元別の例:
完全性:
- 「すべてのAPI障害モードに対してエラーハンドリング要件が定義されていますか? [ギャップ]」
- 「すべてのインタラクティブ要素に対してアクセシビリティ要件が指定されていますか? [完全性]」
- 「レスポンシブレイアウトに対してモバイルブレークポイントの要件が定義されていますか? [ギャップ]」
明確さ:
- 「'高速な読み込み' は具体的なタイミングしきい値で定量化されていますか? [明確さ, 仕様 §NFR-2]」
- 「'関連エピソード' の選択基準は明示的に定義されていますか? [明確さ, 仕様 §FR-5]」
- 「'目立つ' は測定可能な視覚的特性で定義されていますか? [曖昧さ, 仕様 §FR-4]」
一貫性:
- 「ナビゲーション要件はすべてのページで整合していますか? [一貫性, 仕様 §FR-10]」
- 「カードコンポーネントの要件はランディングページと詳細ページで一貫していますか? [一貫性]」
カバレッジ:
- 「ゼロ状態のシナリオ(エピソードなし)の要件は定義されていますか? [カバレッジ, エッジケース]」
- 「同時ユーザーインタラクションのシナリオは対処されていますか? [カバレッジ, ギャップ]」
- 「部分的なデータ読み込み失敗の要件は指定されていますか? [カバレッジ, 例外フロー]」
測定可能性:
- 「視覚的階層の要件は測定可能/テスト可能ですか? [受け入れ基準, 仕様 §FR-1]」
- 「'バランスの取れた視覚的重み' は客観的に検証できますか? [測定可能性, 仕様 §FR-2]」
シナリオ分類とカバレッジ(要件品質重視):
- 以下の要件が存在するか確認: 主、代替、例外/エラー、リカバリ、非機能シナリオ
- 各シナリオクラスについて、「[シナリオタイプ] 要件は完全で、明確で、一貫していますか?」と質問する
- シナリオクラスが欠落している場合:「[シナリオタイプ] 要件は意図的に除外されていますか、それとも欠落していますか? [ギャップ]」
- 状態変更が発生する場合の回復力/ロールバックを含める:「移行障害に対するロールバック要件は定義されていますか? [ギャップ]」
トレーサビリティ要件:
- 最小: アイテムの ≥80% に少なくとも1つのトレーサビリティ参照を含める必要があります
- 各アイテムは以下を参照する必要があります: 仕様セクション
[仕様 §X.Y]、またはマーカー[ギャップ]、[曖昧さ]、[競合]、[前提条件]を使用 - ID システムが存在しない場合:「要件と受け入れ基準の ID スキームは確立されていますか? [トレーサビリティ]」
問題の表面化と解決(要件品質の問題): 要件自体について質問します:
- 曖昧さ:「「高速」という用語は特定のメトリクスで定量化されていますか? [曖昧さ, 仕様 §NFR-1]」
- 競合:「§FR-10 と §FR-10a の間でナビゲーション要件が競合していますか? [競合]」
- 前提条件:「「常に利用可能なポッドキャスト API」という前提は検証されていますか? [前提条件]」
- 依存関係:
- 存在しない場合は