spec-kit-specify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Kit Specify

Create or refresh the feature specification for the active Spec Kit feature.

为当前激活的Spec Kit功能创建或更新功能规范文档。

When to Use

适用场景

Start a new feature and create the first
```
spec.md
```
.
Convert free-form requirements into a structured, testable, implementation-agnostic specification.
Rework an existing spec draft so it is ready for
```
spec-kit-clarify
```
or
```
spec-kit-plan
```
.

启动新功能并创建首份
```
spec.md
```
文档。
将自由格式的需求转换为结构化、可测试、与实现无关的规范文档。
重写现有规范草稿，使其可用于
```
spec-kit-clarify
```
或
```
spec-kit-plan
```
命令。

When Not to Use

不适用场景

Clarify ambiguity in an already-written spec without redrafting it (
```
spec-kit-clarify
```
).
Generate design artifacts or tasks from an approved spec (
```
spec-kit-plan
```
,
```
spec-kit-tasks
```
).
Reconcile cross-artifact drift in an existing feature (
```
spec-kit-reconcile
```
).

无需重写即可澄清已有规范中的歧义（使用
```
spec-kit-clarify
```
命令）。
基于已批准的规范生成设计工件或任务（使用
```
spec-kit-plan
```
、
```
spec-kit-tasks
```
命令）。
协调现有功能中跨工件的差异（使用
```
spec-kit-reconcile
```
命令）。

Router Fit

工作流适配

Primary route from
```
spec-kit
```
when
```
spec.md
```
does not exist yet.
Downstream: hand off to
```
spec-kit-clarify
```
(if high-impact ambiguity remains) or
```
spec-kit-plan
```
(if spec is ready).

当
```
spec.md
```
尚未存在时，是
```
spec-kit
```
的首要入口命令。
后续流程：若仍存在高影响歧义，移交至
```
spec-kit-clarify
```
；若规范已就绪，移交至
```
spec-kit-plan
```
。

Preconditions

前置条件

User provided a non-empty feature description.
Run from repository root (or a subdirectory inside the repository).

用户已提供非空的功能描述。
从仓库根目录（或仓库内子目录）运行该命令。

Workflow

工作流程

Normalize input:
- Treat the full user request as the feature description.
- If empty, stop:
```
ERROR: No feature description provided
```
  .
Generate a short branch suffix (2-4 words, kebab-case):
- Preserve meaningful technical terms/acronyms.
- Prefer action-noun phrasing (for example
```
user-auth
```
  ,
```
bulk-export-audit-log
```
  ).
Bootstrap feature branch and spec exactly once:
- Run
```
scripts/create-new-feature.sh --json --short-name "<short-name>" "<feature description>"
```
  .
- Do not manually pre-compute branch numbers; let the script assign the next number.
- Parse JSON output and capture:
  - ```
  BRANCH_NAME
```
- ```
SPEC_FILE
```
  - ```
  FEATURE_NUM
```
- Derive
```
FEATURE_DIR
```
  as
```
dirname(SPEC_FILE)
```
  .
Load template context:
- Preferred template:
```
{REPO_ROOT}/templates/spec-template.md
```
  .
- Fallback template:
```
assets/spec-template.md
```
  .
- Preserve heading order from the selected template.
Draft
```
spec.md
```
content (focus on WHAT/WHY, not HOW):
- Fill prioritized user stories with independent tests and acceptance scenarios.
- Write testable functional requirements.
- Add edge cases and scope boundaries.
- Add measurable, technology-agnostic success criteria.
- Include key entities when data is central.
- Use reasonable defaults and document assumptions when needed.
Clarification policy while drafting:
- First, make informed defaults using domain norms.
- Add
```
[NEEDS CLARIFICATION: ...]
```
  only for high-impact uncertainty.
- Hard limit: at most 3 clarification markers.
- Prioritize by impact: scope > security/privacy > UX > technical detail.
Write the spec to
```
SPEC_FILE
```
.
Create and run requirements quality validation:
- Create
```
FEATURE_DIR/checklists/requirements.md
```
  .
- Validate spec against this checklist:
  - No implementation details (frameworks, languages, APIs, internal architecture).
  - Mandatory sections are complete.
  - Requirements are unambiguous and testable.
  - Success criteria are measurable and technology-agnostic.
  - User scenarios and edge cases are covered.
  - Scope boundaries, dependencies, and assumptions are explicit.
  - No unresolved
```
[NEEDS CLARIFICATION]
```
    markers for plan-ready specs.
- If non-clarification issues fail, revise spec and re-validate (max 3 passes).
If clarification markers remain after validation:
- Ask up to 3 numbered clarification questions total.
- For each question, present 2-3 concrete options plus a short custom answer path.
- Wait for user responses, update
```
spec.md
```
  , then re-run validation.
Report completion:

Branch name.
```
spec.md
```
path.
```
requirements.md
```
path and pass/fail summary.
Recommended next step:
- ```
spec-kit-clarify
```
  if high-impact ambiguity remains.
- ```
spec-kit-plan
```
  if ready.

标准化输入：
- 将用户的完整请求视为功能描述。
- 若输入为空，终止操作：
```
ERROR: No feature description provided
```
  。
生成简短分支后缀（2-4个单词，短横线分隔小写格式）：
- 保留有意义的技术术语/缩写。
- 优先采用动作-名词结构（例如
```
user-auth
```
  、
```
bulk-export-audit-log
```
  ）。
仅执行一次功能分支与规范初始化：
- 运行
```
scripts/create-new-feature.sh --json --short-name "<short-name>" "<feature description>"
```
  。
- 请勿手动预计算分支编号，由脚本分配下一个编号。
- 解析JSON输出并捕获：
  - ```
  BRANCH_NAME
```
- ```
SPEC_FILE
```
  - ```
  FEATURE_NUM
```
- 推导
```
FEATURE_DIR
```
  为
```
dirname(SPEC_FILE)
```
  。
加载模板上下文：
- 首选模板：
```
{REPO_ROOT}/templates/spec-template.md
```
  。
- 备用模板：
```
assets/spec-template.md
```
  。
- 保留所选模板的标题顺序。
起草
```
spec.md
```
内容（聚焦于WHAT/WHY，而非HOW）：
- 填充优先级明确的用户故事，包含独立测试与验收场景。
- 编写可测试的功能需求。
- 添加边缘案例与范围边界。
- 添加可衡量、与技术无关的成功标准。
- 若数据为核心要素，包含关键实体。
- 必要时使用合理默认值并记录假设。
起草时的澄清规则：
- 首先，使用领域规范做出合理默认假设。
- 仅对高影响不确定性添加
```
[NEEDS CLARIFICATION: ...]
```
  标记。
- 严格限制：最多添加3个澄清标记。
- 按影响优先级排序：范围 > 安全/隐私 > 用户体验 > 技术细节。
将规范写入
```
SPEC_FILE
```
。
创建并运行需求质量验证：
- 创建
```
FEATURE_DIR/checklists/requirements.md
```
  。
- 对照以下检查清单验证规范：
  - 不包含实现细节（框架、语言、API、内部架构）。
  - 必填章节完整。
  - 需求明确且可测试。
  - 成功标准可衡量且与技术无关。
  - 覆盖用户场景与边缘案例。
  - 明确范围边界、依赖关系与假设。
  - 就绪待规划的规范中无未解决的
```
[NEEDS CLARIFICATION]
```
    标记。
- 若存在非澄清类问题导致验证失败，修订规范并重新验证（最多3次）。
若验证后仍存在澄清标记：
- 最多提出3个编号的澄清问题。
- 每个问题提供2-3个具体选项，外加简短自定义回答路径。
- 等待用户回复，更新
```
spec.md
```
  ，然后重新运行验证。
报告完成情况：

分支名称。
```
spec.md
```
路径。
```
requirements.md
```
路径与通过/失败摘要。
推荐下一步操作：
- 若仍存在高影响歧义，使用
```
spec-kit-clarify
```
  。
- 若规范已就绪，使用
```
spec-kit-plan
```
  。

Output

输出结果

Active feature branch from
```
scripts/create-new-feature.sh
```
```
specs/<feature>/spec.md
```

specs/<feature>/checklists/requirements.md

readiness handoff for
```
spec-kit-clarify
```
or
```
spec-kit-plan
```

由
```
scripts/create-new-feature.sh
```
生成的激活功能分支
```
specs/<feature>/spec.md
```

specs/<feature>/checklists/requirements.md

可移交至
```
spec-kit-clarify
```
或
```
spec-kit-plan
```
的就绪状态

Common Mistakes

常见错误

Writing implementation design into the spec instead of user-visible behavior and outcomes.
Leaving vague requirements that cannot be acceptance-tested.
Asking too many clarification questions instead of making reasonable defaults.
Running feature bootstrap script multiple times for one request.

在规范中写入实现设计，而非用户可见的行为与结果。
留下无法进行验收测试的模糊需求。
提出过多澄清问题，而非做出合理默认假设。
针对同一请求多次运行功能初始化脚本。

References

参考资料

```
references/spec-kit-workflow.dot
```
```
scripts/create-new-feature.sh
```
```
assets/spec-template.md
```

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

```
references/spec-kit-workflow.dot
```
```
scripts/create-new-feature.sh
```
```
assets/spec-template.md
```

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