Back to Details

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

工作流程

  1. Gather context: Collect feature description, target users, problem statement, and constraints from user input or $ARGUMENTS. Ask clarifying questions for missing information.
  2. Create directory: 
    specs/feature-name/
  3. Copy 
    assets/spec.md
    to 
    specs/feature-name/README.md
  4. Complete every section from the Required Sections table below
  5. Validate against the checklist before completing
  1. 收集上下文：从用户输入或$ARGUMENTS中收集功能描述、目标用户、问题说明和约束条件。若信息缺失，提出澄清问题。
  2. 创建目录：
    specs/feature-name/
  3. 将
    assets/spec.md
    复制到
    specs/feature-name/README.md
  4. 完成下方必填章节表格中的所有章节内容
  5. 完成前对照检查清单进行验证

Required Sections

必填章节

SectionContent
Feature Overview2-3 paragraphs: what, who, problem solved
Success CriteriaMeasurable outcomes defining "done"
Design GoalsPrimary (must) and secondary (nice to have)
User Experience1-2 paragraphs: interaction, journey
Design Rationale1-2 paragraphs: why this approach, trade-offs
Constraints/AssumptionsTechnical constraints, business assumptions
Functional RequirementsFR-N format, max 6-8, with acceptance criteria
Edge CasesUnusual 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和归档的扩展指南