Back to Details

spec-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec Writer Skill

Spec Writer Skill

Purpose

目的

Produce a structured SPEC.md before any design or implementation begins. This is Phase 0 of the feature lifecycle pipeline (spec --> design --> plan --> implement --> validate --> release). The spec defines WHAT to build and WHERE the boundaries are. It says nothing about HOW.
在任何设计或实现工作开始前生成结构化的SPEC.md文档。这是功能生命周期流程的第0阶段（spec → design → plan → implement → validate → release）。该规格说明定义了要构建的内容以及范围边界，不涉及具体实现方式。

Operator Context

操作上下文

Hardcoded Behaviors (Always Apply)

硬编码行为（始终适用）

  • Phase 3 (Out of Scope) is MANDATORY -- never skip it. Without explicit exclusions, scope creep is invisible until it's too late. Every "while we're at it" addition started as an unwritten assumption.
  • Minimum 3 out-of-scope items -- if you cannot list 3 things this feature does NOT do, the scope is not yet defined. This forces real boundary thinking rather than a rubber-stamp section.
  • Max 7 user stories -- more than 7 means the feature is too broad. Decompose into multiple specs first. This constraint forces prioritization: which stories are essential vs. nice-to-have?
  • Acceptance criteria must be testable -- no subjective language ("should feel fast", "user-friendly", "intuitive"). Every criterion must have a verifiable assertion. WHY: untestable criteria become opinion debates during review.
  • Spec says WHAT, not HOW -- no code, no architecture, no database schemas, no implementation details. Those belong in feature-design.
  • 第3阶段（范围外定义）为必填项——绝不允许跳过。如果没有明确的排除项，scope creep会在问题无法挽回时才显现。所有“顺便做一下”的新增内容最初都源于未书面明确的假设。
  • 至少3项范围外内容——如果无法列出3项该功能不涉及的内容，说明范围尚未明确。这一要求迫使团队真正思考边界，而非走过场。
  • 最多7个用户故事——超过7个意味着功能范围过宽，应先拆分为多个规格说明。这一约束促使团队进行优先级排序：哪些故事是核心需求，哪些是锦上添花的功能？
  • 验收标准必须可测试——不得使用主观表述（如“应感觉快速”、“用户友好”、“直观”）。每条标准都必须有可验证的断言。原因：不可测试的标准会在评审阶段引发意见分歧。
  • 规格说明只讲“做什么”，不讲“怎么做”——不得包含代码、架构、数据库 schema 或实现细节。这些内容属于feature-design阶段。

Default Behaviors (ON unless disabled)

默认行为（启用状态，除非手动关闭）

  • Save output as SPEC.md in project root, or 
    .feature/SPEC.md
    if worktree is active
  • Include all 5 sections in order (stories, criteria, out-of-scope, risks, estimation)
  • Use GIVEN/WHEN/THEN format for acceptance criteria
  • 将输出保存至项目根目录的SPEC.md，若存在工作树则保存至
    .feature/SPEC.md
  • 按顺序包含全部5个章节（用户故事、验收标准、范围外定义、风险、估算）
  • 验收标准采用GIVEN/WHEN/THEN格式

Optional Behaviors (OFF unless enabled)

可选行为（关闭状态，除非手动启用）

  • Skip estimation -- omit Section 5 for exploratory or research-phase work
  • Test stub generation -- render acceptance criteria as pseudocode test stubs
  • 跳过估算——针对探索性或研究阶段的工作，可省略第5章节
  • 生成测试桩——将验收标准转换为伪代码测试桩

Instructions

操作步骤

Step 1: Gather Context

步骤1：收集上下文

  1. Read the repository CLAUDE.md if present
  2. Ask the user what feature or capability they want to specify
  3. Identify the target users/roles (who benefits?)
  4. Identify existing related functionality (what already exists?)
GATE: You have a clear understanding of the feature intent and target users before writing any stories.
  1. 若仓库中存在CLAUDE.md则阅读该文档
  2. 询问用户需要指定的功能或能力
  3. 确定目标用户/角色（谁会从中受益？）
  4. 识别现有相关功能（已存在哪些相关内容？）
检查点：在编写任何用户故事前，必须清晰理解功能意图和目标用户。

Step 2: Write SPEC.md

步骤2：编写SPEC.md

Produce the spec with all 5 sections. Use this structure:
markdown
undefined
生成包含全部5个章节的规格说明，采用以下结构：
markdown
undefined

Spec: [Feature Name]

Spec: [Feature Name]

1. User Stories

1. User Stories

Max 7 stories. Each has single responsibility.
  • US-1: As a [role], I want [action] so that [benefit].
  • US-2: As a [role], I want [action] so that [benefit].
Max 7 stories. Each has single responsibility.
  • US-1: As a [role], I want [action] so that [benefit].
  • US-2: As a [role], I want [action] so that [benefit].

2. Acceptance Criteria

2. Acceptance Criteria

2-5 criteria per story. All must be verifiable.
2-5 criteria per story. All must be verifiable.

US-1: [Story title]

US-1: [Story title]

  • GIVEN [context] WHEN [action] THEN [result]
  • GIVEN [context] WHEN [action] THEN [result]
  • GIVEN [context] WHEN [action] THEN [result]
  • GIVEN [context] WHEN [action] THEN [result]

US-2: [Story title]

US-2: [Story title]

  • GIVEN [context] WHEN [action] THEN [result]
  • GIVEN [context] WHEN [action] THEN [result]

3. Out of Scope

3. Out of Scope

Minimum 3 items. Each states WHY it is excluded.
This feature does NOT:
  • Handle X (deferred to future work because Y)
  • Support Y (explicitly excluded because Z)
  • Replace Z (existing solution remains because W)
Minimum 3 items. Each states WHY it is excluded.
This feature does NOT:
  • Handle X (deferred to future work because Y)
  • Support Y (explicitly excluded because Z)
  • Replace Z (existing solution remains because W)

4. Risks & Assumptions

4. Risks & Assumptions

Risk/AssumptionImpactMitigation
Assumption could be wrongWhat breaksHow to detect/recover
External dependency blocksDelay estimateFallback plan
Risk/AssumptionImpactMitigation
Assumption could be wrongWhat breaksHow to detect/recover
External dependency blocksDelay estimateFallback plan

5. Estimation

5. Estimation

DimensionAssessmentJustification
T-shirt sizeS / M / L / XLWhy this size
Files changed~N filesWhich areas of codebase
Testing complexityLow / Medium / HighWhat makes testing easy or hard

**GATE**: All 5 sections present. Out-of-scope has >= 3 items. Stories <= 7. All criteria use verifiable language.
DimensionAssessmentJustification
T-shirt sizeS / M / L / XLWhy this size
Files changed~N filesWhich areas of codebase
Testing complexityLow / Medium / HighWhat makes testing easy or hard

**检查点**：包含全部5个章节。范围外内容不少于3项。用户故事不超过7个。所有标准均使用可验证表述。

Step 3: Validate and Save

步骤3：验证并保存

  1. Review each acceptance criterion -- flag any that use subjective language
  2. Review out-of-scope -- flag if fewer than 3 items
  3. Review story count -- flag if more than 7
  4. Save the spec:
    • If 
      .feature/
      directory exists: save to 
      .feature/SPEC.md
    • Otherwise: save to 
      SPEC.md
      in project root
  5. Report the artifact location and suggest next step: 
    Spec saved to [path]. Run /feature-design to begin design exploration.
  1. 检查每条验收标准——标记使用主观表述的内容
  2. 检查范围外内容——标记少于3项的情况
  3. 检查用户故事数量——标记超过7个的情况
  4. 保存规格说明：
    • 若存在
      .feature/
      目录：保存至
      .feature/SPEC.md
    • 否则：保存至项目根目录的
      SPEC.md
  5. 报告生成的文档位置并建议下一步操作： 
    Spec saved to [path]. Run /feature-design to begin design exploration.

Error Handling

错误处理

ErrorCauseSolution
Cannot identify target usersVague feature requestAsk user to describe who benefits and how
More than 7 storiesScope too broadDecompose into multiple specs, one per coherent capability
Cannot list 3 out-of-scope itemsScope not yet definedBrainstorm adjacent features, related capabilities, and future enhancements that are NOT part of this work
Acceptance criteria use subjective language"fast", "easy", "intuitive"Replace with measurable assertion: latency threshold, click count, error rate
错误原因解决方案
无法确定目标用户功能请求模糊询问用户描述受益人群及受益方式
用户故事超过7个范围过宽拆分为多个规格说明，每个说明对应一个独立的功能模块
无法列出3项范围外内容范围未明确头脑风暴相关的相邻功能、关联能力及不属于本次工作的未来增强功能
验收标准使用主观表述使用了“快速”、“易用”、“直观”等词汇替换为可衡量的断言：延迟阈值、点击次数、错误率

Anti-Patterns

反模式

Anti-PatternWhy WrongDo Instead
Kitchen sink spec (>7 stories)Scope is too broad to implement or validate coherentlyDecompose into multiple specs, prioritize
Empty out-of-scopeIf nothing is excluded, everything is included -- that is a scope problemForce 3+ exclusions with reasoning
Untestable criteria"Should be user-friendly" becomes an opinion debate during reviewUse measurable assertions: "<3 clicks", "<200ms", "zero data loss"
Spec as implementationSpec says WHAT, not HOW. Code and schemas belong in feature-designRemove implementation details, keep behavioral descriptions
反模式问题所在正确做法
大杂烩式规格说明（超过7个用户故事）范围过宽，无法连贯地实现或验证拆分为多个规格说明并确定优先级
范围外内容为空若没有排除任何内容，意味着所有内容都在范围内——这是范围问题强制列出3项及以上带理由的排除项
不可测试的标准“应具备用户友好性”会在评审阶段引发意见分歧使用可衡量的断言：“点击次数<3次”、“延迟<200ms”、“零数据丢失”
规格说明包含实现细节规格说明只讲“做什么”，不讲“怎么做”。代码和 schema 属于feature-design阶段删除实现细节，保留行为描述

Integration

集成关系

This skill produces the input artifact for the feature lifecycle:
spec-writer (SPEC.md)
  --> feature-design (reads stories + scope boundaries)
    --> feature-plan (reads acceptance criteria for test requirements)
      --> feature-implement
        --> feature-validate (checks acceptance criteria as quality gates)
          --> feature-release
该技能生成的产物是功能生命周期的输入 artifact：
spec-writer (SPEC.md)
  --> feature-design（读取用户故事 + 范围边界）
    --> feature-plan（读取验收标准以确定测试需求）
      --> feature-implement
        --> feature-validate（将验收标准作为质量检查点）
          --> feature-release

References

参考资料

  • Anti-Rationalization
  • Gate Enforcement
  • Anti-Rationalization
  • Gate Enforcement