spec-kit-checklist

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Kit Checklist

Spec Kit 检查清单

Generate domain-specific checklists that evaluate requirement quality in Spec Kit artifacts.

生成特定领域的检查清单，用于评估Spec Kit工件中的需求质量。

When to Use

适用场景

```
spec.md
```
exists and you need a checklist to review requirement quality before implementation.
You want a focused lens (for example UX, API, security, performance, accessibility) over requirement quality.
You need to surface ambiguity, missing coverage, or weak acceptance criteria in writing.

已存在
```
spec.md
```
文件，且你需要一份在实现前评审需求质量的检查清单。
你希望聚焦特定维度（例如用户体验、API、安全、性能、可访问性）评估需求质量。
你需要在文档中找出模糊点、覆盖缺失或不够严谨的验收标准。

When Not to Use

不适用场景

You are writing runtime tests, QA scripts, or implementation verification steps.
```
spec.md
```
does not exist yet (
```
spec-kit-specify
```
first).
High-impact ambiguity must be resolved in-spec before checklist generation (
```
spec-kit-clarify
```
).
You are generating executable tasks (
```
spec-kit-tasks
```
) or implementing tasks (
```
spec-kit-implement
```
).

你正在编写运行时测试、QA脚本或实现验证步骤。
尚未生成
```
spec.md
```
文件（需先使用
```
spec-kit-specify
```
）。
高影响的模糊点必须先在规格文档中解决，再生成检查清单（需先使用
```
spec-kit-clarify
```
）。
你正在生成可执行任务（
```
spec-kit-tasks
```
）或实现任务（
```
spec-kit-implement
```
）。

Router Fit

路由适配

Primary route from
```
spec-kit
```
when the intent is requirement-quality checklist generation.
Can be run as a standalone quality pass after
```
spec-kit-specify
```
/
```
spec-kit-clarify
```
and before or during implementation.
Output checklists feed the optional checklist gate in
```
spec-kit-implement
```
.

当意图是生成需求质量检查清单时，是
```
spec-kit
```
的主要路由。
可在
```
spec-kit-specify
```
/
```
spec-kit-clarify
```
之后、实现之前或期间作为独立的质量检查步骤运行。
输出的检查清单可作为
```
spec-kit-implement
```
中可选的检查门控输入。

Preconditions

前置条件

Run from repository root (or a subdirectory inside it).
Active feature context resolves to one
```
specs/<feature>/
```
directory.
```
spec.md
```
exists for that feature.

从仓库根目录（或其下的子目录）运行。
激活的功能上下文可解析到一个
```
specs/<feature>/
```
目录。
该功能对应的
```
spec.md
```
文件已存在。

Workflow

工作流程

Resolve feature paths and enforce the checklist prerequisite gate:
- Run
```
scripts/check-prerequisites.sh --paths-only --json
```
  exactly once.
- Parse and retain
```
REPO_ROOT
```
  ,
```
FEATURE_DIR
```
  , and
```
FEATURE_SPEC
```
  .
- If
```
FEATURE_SPEC
```
  (
```
spec.md
```
  ) is missing, stop and route to
```
spec-kit-specify
```
  .
Load checklist context:
- Required:
```
spec.md
```
  .
- Optional when present:
```
plan.md
```
  ,
```
tasks.md
```
  .
- Extract only requirement-relevant content: requirements, acceptance criteria, edge/error cases, non-functional constraints, assumptions/dependencies.
Clarify checklist scope only when needed:
- Ask up to 3 concise, high-impact questions if scope/risk/audience is unclear.
- Skip questions already answered in user input or artifacts.
- If ambiguity still blocks item quality, ask up to 2 targeted follow-ups (max 5 total).
Choose checklist file target:
- Ensure
```
FEATURE_DIR/checklists/
```
  exists.
- Derive a short domain slug from intent (for example
```
ux
```
  ,
```
api
```
  ,
```
security
```
  ,
```
performance
```
  ).
- Create a new file per run: prefer
```
<slug>.md
```
  ; if it exists, create
```
<slug>-2.md
```
  ,
```
<slug>-3.md
```
  , etc.
- Never overwrite existing checklist files.
Generate requirement-quality checklist items:
- Treat each item as a "unit test for requirement writing," not implementation behavior.
- Group items under quality categories as needed:
  - Requirement Completeness
  - Requirement Clarity
  - Requirement Consistency
  - Acceptance Criteria Quality / Measurability
  - Scenario and Edge-Case Coverage
  - Non-Functional Requirements
  - Dependencies and Assumptions
  - Ambiguities and Conflicts
- Use
```
CHK###
```
  IDs starting at
```
CHK001
```
  and increment sequentially.
- Keep items in question form and focused on what is documented or missing.
Apply strict item-quality rules:
- Prefer patterns such as:
  - ```
  Are <requirements> defined/specified for <scenario>?
```
- ```
Is <term> quantified with measurable criteria?
```
  - ```
  Are requirements consistent between <section A> and <section B>?
```
- Do not generate implementation checks (for example click/render/load/execute behavior checks).
- Do not use runtime-verification framing (
```
Verify
```
  ,
```
Test
```
  ,
```
Confirm
```
  ) for system behavior.
- Include traceability on most items (target: >=80%) using markers like
```
[Spec §...]
```
  ,
```
[Gap]
```
  ,
```
[Ambiguity]
```
  ,
```
[Conflict]
```
  ,
```
[Assumption]
```
  .
Write output using template structure:
- Preferred template:
```
{REPO_ROOT}/templates/checklist-template.md
```
  .
- Fallback template:
```
assets/checklist-template.md
```
  .
- Preserve heading order and emit checklist rows in this format:
  - ```
  - [ ] CHK### <question> [markers]
```
Validate before final report:
- No implementation/runtime verification items.
- IDs are unique and sequential.
- Items are requirement-quality questions.
- Traceability markers meet target coverage.
Report completion:
- Absolute checklist path.
- Item count.
- Selected focus areas, depth/audience assumptions, and any explicit must-have user constraints incorporated.
- Reminder that each run creates a new checklist file.

解析功能路径并强制执行检查清单前置门控：
- 精确运行一次
```
scripts/check-prerequisites.sh --paths-only --json
```
  。
- 解析并保留
```
REPO_ROOT
```
  、
```
FEATURE_DIR
```
  和
```
FEATURE_SPEC
```
  。
- 如果
```
FEATURE_SPEC
```
  （即
```
spec.md
```
  ）缺失，停止操作并路由到
```
spec-kit-specify
```
  。
加载检查清单上下文：
- 必需：
```
spec.md
```
  文件。
- 可选（若存在）：
```
plan.md
```
  、
```
tasks.md
```
  文件。
- 仅提取与需求相关的内容：需求、验收标准、边缘/错误场景、非功能约束、假设/依赖项。
仅在需要时明确检查清单范围：
- 如果范围/风险/受众不明确，最多提出3个简洁、高影响力的问题。
- 跳过用户输入或工件中已回答的问题。
- 如果模糊点仍阻碍条目质量，最多提出2个针对性的跟进问题（总计不超过5个）。
选择检查清单文件目标：
- 确保
```
FEATURE_DIR/checklists/
```
  目录存在。
- 根据意图生成简短的领域标识（例如
```
ux
```
  、
```
api
```
  、
```
security
```
  、
```
performance
```
  ）。
- 每次运行创建一个新文件：优先使用
```
<slug>.md
```
  ；若该文件已存在，则创建
```
<slug>-2.md
```
  、
```
<slug>-3.md
```
  等。
- 绝不覆盖现有检查清单文件。
生成需求质量检查清单条目：
- 将每个条目视为“需求文档的单元测试”，而非实现行为的测试。
- 根据需要将条目归类到质量类别下：
  - 需求完整性
  - 需求清晰性
  - 需求一致性
  - 验收标准质量/可衡量性
  - 场景与边缘案例覆盖
  - 非功能需求
  - 依赖项与假设
  - 模糊点与冲突
- 使用从
```
CHK001
```
  开始的连续
```
CHK###
```
  编号。
- 条目以问题形式呈现，聚焦于已记录的内容或缺失的内容。
应用严格的条目质量规则：
- 优先使用以下模式：
  - ```
  是否为<场景>定义了<需求>？
```
- ```
是否为<术语>制定了可衡量的标准？
```
  - ```
  <章节A>与<章节B>中的需求是否一致？
```
- 不要生成实现相关的检查项（例如点击/渲染/加载/执行行为检查）。
- 不要使用运行时验证的表述（如
```
验证
```
  、
```
测试
```
  、
```
确认
```
  ）来描述系统行为。
- 大多数条目需包含可追溯性标记（目标覆盖率≥80%），例如
```
[Spec §...]
```
  、
```
[Gap]
```
  、
```
[Ambiguity]
```
  、
```
[Conflict]
```
  、
```
[Assumption]
```
  。
使用模板结构编写输出：
- 首选模板：
```
{REPO_ROOT}/templates/checklist-template.md
```
  。
- 备用模板：
```
assets/checklist-template.md
```
  。
- 保留标题顺序，并按以下格式输出检查清单行：
  - ```
  - [ ] CHK### <问题> [标记]
```
最终报告前进行验证：
- 无实现/运行时验证条目。
- 编号唯一且连续。
- 条目均为需求质量相关问题。
- 可追溯性标记达到目标覆盖率。
报告完成情况：
- 检查清单的绝对路径。
- 条目数量。
- 选定的聚焦领域、深度/受众假设，以及纳入的任何明确的用户强制约束。
- 提醒每次运行都会创建一个新的检查清单文件。

Output

输出结果

New checklist file in
```
specs/<feature>/checklists/
```
.
Requirement-quality checklist items with sequential
```
CHK###
```
IDs.
Summary of scope assumptions and checklist focus.

新的检查清单文件位于
```
specs/<feature>/checklists/
```
目录下。
带有连续
```
CHK###
```
编号的需求质量检查清单条目。
范围假设与检查清单聚焦点的摘要。

Key Rules

核心规则

Evaluate the quality of requirements writing, not whether implementation works.
Keep items objective, reviewable, and traceable to artifacts.
Prefer concise, high-signal checklists over exhaustive low-value lists.

评估需求文档的质量，而非实现是否可行。
条目需客观、可评审，并可追溯到对应工件。
优先选择简洁、高价值的检查清单，而非详尽但低价值的列表。

Common Mistakes

常见错误

Writing QA/runtime checks ("verify the API returns 200") instead of requirement-quality checks ("requirement specifies expected response codes").
Producing vague items with no traceability marker.
Overfitting to implementation details that do not belong in requirements artifacts.
Overwriting an existing checklist instead of creating a new file for the run.

编写QA/运行时检查项（如“验证API返回200”）而非需求质量检查项（如“需求中明确了预期的响应码”）。
生成无追溯性标记的模糊条目。
过度贴合不属于需求工件的实现细节。
覆盖现有检查清单文件，而非为本次运行创建新文件。

References

参考资料

```
scripts/check-prerequisites.sh
```
```
assets/checklist-template.md
```

https://github.com/github/spec-kit/blob/9111699cd27879e3e6301651a03e502ecb6dd65d/templates/commands/checklist.md

```
scripts/check-prerequisites.sh
```
```
assets/checklist-template.md
```

https://github.com/github/spec-kit/blob/9111699cd27879e3e6301651a03e502ecb6dd65d/templates/commands/checklist.md