spec-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Writing

规格说明书编写

Capture WHAT and WHY. Never prescribe HOW.

When invoked with arguments, write a spec for: $ARGUMENTS

聚焦于“做什么”和“为什么做”，绝不规定“怎么做”。

当传入参数时，为以下内容编写规格说明书：$ARGUMENTS

Workflow

工作流程

Gather context: Collect feature description, target users, problem statement, and constraints from user input or $ARGUMENTS. Ask clarifying questions for missing information.
Create directory:
```
specs/feature-name/
```

Copy

assets/spec.md

specs/feature-name/README.md

Complete every section from the Required Sections table below
Validate against the checklist before completing

收集上下文：从用户输入或$ARGUMENTS中收集功能描述、目标用户、问题说明和约束条件。若信息缺失，提出澄清问题。
创建目录：
```
specs/feature-name/
```

将

assets/spec.md

复制到

specs/feature-name/README.md

完成下方必填章节表格中的所有章节内容
完成前对照检查清单进行验证

Required Sections

必填章节

Section	Content
Feature Overview	2-3 paragraphs: what, who, problem solved
Success Criteria	Measurable outcomes defining "done"
Design Goals	Primary (must) and secondary (nice to have)
User Experience	1-2 paragraphs: interaction, journey
Design Rationale	1-2 paragraphs: why this approach, trade-offs
Constraints/Assumptions	Technical constraints, business assumptions
Functional Requirements	FR-N format, max 6-8, with acceptance criteria
Edge Cases	Unusual inputs, failure scenarios

章节	内容
功能概述	2-3段：功能内容、目标用户、解决的问题
成功标准	定义“完成”的可衡量成果
设计目标	主要（必须实现）和次要（锦上添花）目标
用户体验	1-2段：交互方式、用户旅程
设计依据	1-2段：选择该方案的原因、权衡取舍
约束条件/假设前提	技术约束、业务假设
功能性需求	采用FR-N格式，最多6-8条，附带验收标准
边缘案例	异常输入、故障场景

Acceptance Criteria

验收标准

markdown

- [ ] Given [context], when [action], then [expected result]

Include 2-4 criteria per requirement: happy path + key failure cases.

markdown

- [ ] Given [context], when [action], then [expected result]

每条需求包含2-4条验收标准：正常流程 + 关键故障场景。

Scope Check

范围检查

More than 6-8 requirements = feature too large. Split: identify 3-4 core requirements, flag rest for separate spec in "Scope Notes" section.

若需求超过6-8条 = 功能范围过大。拆分方法：确定3-4条核心需求，将其余需求标记为单独规格说明书，放入“范围说明”章节。

Validation Checklist

验证检查清单

Single MVP focus (one deliverable)
All requirements have testable criteria
No TODO/TBD placeholders
Edge cases documented

聚焦单一MVP交付物
所有需求均具备可测试的标准
无TODO/TBD占位符
已记录边缘案例

Exclusions

排除内容

A spec defines WHAT to build, not HOW to build it. Exclude:

Implementation approach or technical strategy
Architecture diagrams
Code examples
Database schemas
API signatures
Technology or framework choices
Development estimates, timelines, or phase sections

规格说明书定义“要构建什么”，而非“如何构建”。需排除以下内容：

实现方案或技术策略
架构图
代码示例
数据库 schema
API 签名
技术或框架选择
开发估算、时间线或阶段划分章节

Supporting Files

支持文件

```
assets/spec.md
```
- Spec template
```
references/spec-guide.md
```
- Extended guidance on ADRs and archival

```
assets/spec.md
```
- 规格说明书模板
```
references/spec-guide.md
```
- 关于ADR和归档的扩展指南