speckit-checklist-zh

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

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

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

• ❌ 「ボタンが正しくクリックされることを検証する」ものではありません
• ❌ 「エラー処理が機能するかをテストする」ものではありません
• ❌ 「API が 200 を返すことを確認する」ものではありません
• ❌ コード／実装が仕様に適合しているかを検査するものではありません

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

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

たとえ：仕様が書かれたコードだとしたら、チェックリストはそのユニットテストスイートです。要件が適切に記述され、完全で、明確であり、実装の準備が整っているかをテストします。実装が有効に機能するかをテストするのではありません。

ユーザー入力

$ARGUMENTS

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

実行手順

scripts: sh: .specify/scripts/bash/check-prerequisites.sh --json ps: .specify/scripts/powershell/check-prerequisites.ps1 -Json

1. セットアップ：リポジトリのルートから {SCRIPT} を実行し、JSON を解析して FEATURE_DIR と AVAILABLE_DOCS の一覧を取得します。

   • すべてのファイルパスは絶対パスでなければなりません。
   • 引数内の一重引用符（例："I'm Groot"）には、エスケープ構文を使用します。例：'I'''m Groot'（または可能であれば二重引用符："I'm Groot"）。

2. 意図の明確化（動的）：固定のカテゴリ一覧を使わず、初期コンテキストを明確にする質問を最大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 レビュー時に同僚も使用しますか？」）
      • 除外範囲の明確化（例：「今回、パフォーマンスチューニング項目は明示的に除外しますか？」）
      • シナリオ分類の不足（例：「リカバリーフローが検出されませんでした。ロールバック／部分障害の経路も対象に含めますか？」）

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

   • 選択肢を提示する場合は、列を「選択肢 | 候補 | 理由」とする簡潔な表を作成します。
   • 選択肢は A〜E の最大5つに制限します。自由形式の回答がより明確な場合は、表を省略します。
   • ユーザーがすでに述べた内容を繰り返すよう求めてはいけません。
   • 推測に基づくカテゴリは避けます（幻覚を生じさせないでください）。不確かな場合は、「X が対象範囲に含まれるか確認してください」と明示的に尋ねます。

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

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

   質問には Q1／Q2／Q3 のラベルを付けます。回答後も、シナリオ分類（代替／異常／リカバリー／非機能領域）のうち2つ以上が不明な場合は、さらに焦点を絞った質問を最大2つ（Q4／Q5）追加できます。各質問には1行の理由を添えます（例：「未解決のリカバリーパスに関するリスク」）。質問は合計5つを超えないでください。ユーザーが追加の質問を明確に拒否した場合は、追加質問を省略します。

3. ユーザーの依頼を理解する：$ARGUMENTS と明確化の回答を組み合わせます。

   • チェックリストのテーマ（例：セキュリティ、レビュー、デプロイ、ユーザーエクスペリエンス）を導き出す
   • ユーザーが明示した必須項目を取り込む
   • 選択された焦点をカテゴリの枠組みに対応付ける
   • 仕様／計画／タスクから、不足しているコンテキストを推測する（幻覚を起こさない）

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% 的项目必须至少包含一个可追溯性引用
   • 每个项目应引用：规格部分 [Spec §X.Y]，或使用标记：[Gap]、[Ambiguity]、[Conflict]、[Assumption]
   • 如果不存在 ID 系统："是否建立了要求和验收标准 ID 方案？ [可追溯性]"

   表面和解决问题（要求质量问题）： 询问有关要求本身的问题：

   • 歧义："'快速' 一词是否用具体指标量化？ [歧义, Spec §NFR-1]"
   • 冲突："§FR-10 和 §FR-10a 中的导航要求是否冲突？ [冲突]"
   • 假设："'始终可用的播客 API' 假设是否已验证？ [假设]"
   • 依赖关系："是否记录了外部播客 API 要求？ [依赖关系, Gap]"
   • 缺失定义："是否用可测量的标准定义了'视觉层次'？ [Gap]"

   内容整合：

   • 软上限：如果原始候选项目 > 40，按风险/影响优先排序
   • 合并检查相同要求方面的近似重复项
   • 如果 >5 个低影响边缘情况，创建一个项目："边缘情况 X、Y、Z 是否在要求中解决？ [覆盖范围]"

   🚫 绝对禁止 - 这些使其成为实现测试，而不是要求测试：

   • ❌ 任何以"验证"、"测试"、"确认"、"检查" + 实现行为开头的项目
   • ❌ 引用代码执行、用户操作、系统行为
   • ❌ "正确显示"、"正常工作"、"按预期功能"
   • ❌ "点击"、"导航"、"渲染"、"加载"、"执行"
   • ❌ 测试用例、测试计划、QA 程序
   • ❌ 实现细节（框架、API、算法）

   ✅ 必需模式 - 这些测试要求质量：

   • ✅ "是否为 [场景] 定义/指定/记录了 [要求类型]？"
   • ✅ "是否用具体标准量化/澄清了 [模糊术语]？"
   • ✅ "[部分 A] 和 [部分 B] 的要求是否一致？"
   • ✅ "是否可以客观测量/验证 [要求]？"
   • ✅ "要求中是否解决了 [边缘情况/场景]？"
   • ✅ "规格是否定义了 [缺失方面]？"

6. 结构参考：按照 .specify/templates/checklist-template.md 中的规范模板生成检查表，包括标题、元部分、类别标题和 ID 格式。如果模板不可用，使用：H1 标题、目的/创建的元行、包含 - [ ] CHK### <要求项目> 行的 ## 类别部分，全局递增 ID 从 CHK001 开始。

7. 报告：输出创建的检查表的完整路径、项目计数，并提醒用户每次运行都会创建一个新文件。总结：

   • 选择的关注领域
   • 深度级别
   • 参与者/时机
   • 任何包含的用户明确指定的必备项目

重要：每个 speckit-checklist 命令调用都使用简短的描述性名称创建检查表文件，除非文件已存在。这允许：

• 不同类型的多个检查表（例如，ux.md, test.md, security.md）
• 简单、易记的文件名，指示检查表目的
• 在 checklists/ 文件夹中轻松识别和导航

为避免混乱，使用描述性类型并在完成后清理过时的检查表。

示例检查表类型和示例项目

用户体验要求质量： ux.md

示例项目（测试要求，而不是实现）：

• "是否用可测量的标准定义了视觉层次要求？ [清晰度, Spec §FR-1]"
• "是否明确定义了 UI 元素的数量和定位？ [完整性, Spec §FR-1]"
• "交互状态要求（悬停、焦点、活动）是否一致定义？ [一致性]"
• "是否为所有交互元素指定了可访问性要求？ [覆盖范围, 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 是否明确定义？"