spec-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Writer

Transform vague ideas into precise, implementable specifications that Claude Code can execute without ambiguity.

将模糊的想法转化为精准、可落地的技术规格，确保Claude Code能够无歧义地执行。

Purpose

目标

Most AI coding failures happen because specifications are unclear. This skill extracts implicit requirements from conversations and outputs structured specs that eliminate guesswork.

大多数AI编码失败的根源在于规格文档不明确。本技能从对话中提取隐含需求，输出结构化的规格文档，彻底消除模糊性。

Process

流程

Phase 1: Context Extraction

第一阶段：上下文提取

Entry Check

准入检查

IF user provided: problem statement + target users + success criteria
    → Proceed to Phase 2
ELSE
    → Gather missing information below (one question at a time)

IF user provided: problem statement + target users + success criteria
    → Proceed to Phase 2
ELSE
    → Gather missing information below (one question at a time)

Information Needed

需要收集的信息

Item	Question	Why Required
Problem	"What problem are you solving?"	Defines scope boundaries
Users	"Who will use this?"	Shapes UX requirements
Success	"How will you know it works?"	Creates acceptance criteria
Constraints	"Any technical/business constraints?"	Prevents wasted effort

项⽬	问题描述	必要性
待解决问题	"你要解决什么问题？"	定义范围边界
目标用户	"谁会使用这个功能？"	塑造UX需求
成功标准	"你如何判断功能生效？"	制定验收标准
约束条件	"是否有技术或业务层面的约束？"	避免无效工作

Transition Criteria

进入下一阶段的条件

All four items gathered + user confirmed → Phase 2

收集齐所有四项信息并得到用户确认 → 进入第二阶段

Phase 2: Requirement Analysis

第二阶段：需求分析

Entry Check

准入检查

IF Phase 1 complete:
    → Analyze and categorize requirements
ELSE
    → Return to Phase 1

IF Phase 1 complete:
    → Analyze and categorize requirements
ELSE
    → Return to Phase 1

Categorization Framework

需求分类框架

FOR each requirement mentioned:
    Classify as:
    - MUST: Core functionality, non-negotiable
    - SHOULD: Important but has workarounds
    - COULD: Nice to have, time permitting
    - WON'T: Explicitly out of scope (important to document)

FOR each requirement mentioned:
    Classify as:
    - MUST: 核心功能，不可协商
    - SHOULD: 重要但有替代方案
    - COULD: 锦上添花，视时间情况而定
    - WON'T: 明确排除在范围外（需重点记录）

Output: Requirements Table

输出：需求表格

ID	Requirement	Priority	Rationale
R1	[requirement]	MUST/SHOULD/COULD	[why this priority]

编号	需求内容	优先级	理由
R1	[具体需求]	MUST/SHOULD/COULD	[设定此优先级的原因]

Edge Case Discovery

边缘案例挖掘

FOR each MUST requirement:
    Ask: "What happens when [edge case]?"

    Common edge cases to probe:
    - Empty/null inputs
    - Maximum scale (1000x normal)
    - Concurrent access
    - Network failure
    - Permission denied
    - Invalid data format

FOR each MUST requirement:
    Ask: "What happens when [edge case]?"

    Common edge cases to probe:
    - 空值/Null输入
    - 极限规模（正常情况的1000倍）
    - 并发访问
    - 网络故障
    - 权限被拒绝
    - 无效数据格式

Phase 3: User Story Generation

第三阶段：用户故事生成

Entry Check

准入检查

IF requirements table complete + edge cases documented:
    → Generate user stories
ELSE
    → Return to Phase 2

IF requirements table complete + edge cases documented:
    → Generate user stories
ELSE
    → Return to Phase 2

Story Format

故事格式

AS A [user type]
I WANT TO [action]
SO THAT [benefit]

ACCEPTANCE CRITERIA:
- GIVEN [context]
  WHEN [action]
  THEN [expected result]

EDGE CASES:
- [edge case]: [expected behavior]

TECHNICAL NOTES:
- [implementation hints, if relevant]

AS A [用户类型]
I WANT TO [执行操作]
SO THAT [获得收益]

ACCEPTANCE CRITERIA:
- GIVEN [上下文]
  WHEN [执行操作]
  THEN [预期结果]

EDGE CASES:
- [边缘案例]: [预期行为]

TECHNICAL NOTES:
- [相关的实现提示（如有）]

Story Generation Rules

故事生成规则

FOR each MUST requirement:
    → Generate 1 user story
    → Include 2-4 acceptance criteria
    → Include 1-3 edge cases

FOR each SHOULD requirement:
    → Generate 1 user story (simpler format)
    → Include 1-2 acceptance criteria

FOR each MUST requirement:
    → 生成1个用户故事
    → 包含2-4条验收标准
    → 包含1-3个边缘案例

FOR each SHOULD requirement:
    → 生成1个用户故事（简化格式）
    → 包含1-2条验收标准

Phase 4: Technical Specification

第四阶段：技术规格文档生成

Entry Check

准入检查

IF user stories generated:
    → Ask: "Ready for technical spec, or need to adjust stories first?"

IF user confirms:
    → Generate technical specification
ELSE
    → Revise stories based on feedback

IF user stories generated:
    → Ask: "Ready for technical spec, or need to adjust stories first?"

IF user confirms:
    → Generate technical specification
ELSE
    → Revise stories based on feedback

Technical Spec Structure

技术规格文档结构

markdown

undefined

markdown

undefined

Technical Specification: [Feature Name]

Technical Specification: [功能名称]

Overview

概述

[1-2 sentences describing the feature]

[1-2句话描述功能]

Data Models

数据模型

[If new data structures needed]

[如果需要新增数据结构]

API Endpoints

API接口

[If applicable]

Method	Path	Request	Response

[如适用]

请求方法	路径	请求参数	响应内容

State Changes

状态变更

[What changes when this feature runs]

[功能运行时的状态变化]

Dependencies

依赖关系

[External services, libraries, existing code]

[外部服务、库、现有代码]

Security Considerations

安全考量

[Auth, validation, rate limits]

[认证、验证、速率限制]

Testing Strategy

测试策略

Unit: [what to unit test]
Integration: [what to integration test]
E2E: [critical user flows]

---

单元测试: [需单元测试的内容]
集成测试: [需集成测试的内容]
端到端测试: [关键用户流程]

---

Phase 5: Output Delivery

第五阶段：输出交付

Output Format Selection

输出格式选择

IF user's project has existing spec format:
    → Match that format
ELSE IF user specified format preference:
    → Use requested format
ELSE
    → Use default markdown format below

IF user's project has existing spec format:
    → Match that format
ELSE IF user specified format preference:
    → Use requested format
ELSE
    → Use default markdown format below

Default Output Structure

默认输出结构

markdown

undefined

markdown

undefined

[Feature Name] Specification

[功能名称] 规格文档

Summary

摘要

[One paragraph overview]

[一段概述]

Requirements

需求列表

[Requirements table from Phase 2]

[来自第二阶段的需求表格]

User Stories

用户故事

[Stories from Phase 3]

[来自第三阶段的用户故事]

Technical Specification

技术规格

[Spec from Phase 4]

[来自第四阶段的规格文档]

Out of Scope

排除范围

[Explicitly excluded items - prevents scope creep]

[明确排除的内容 - 防止范围蔓延]

Open Questions

待解决问题

[Unresolved items needing decisions]

---

[需要决策的未解决事项]

---

Self-Check (Read before every response)

自我检查（每次回复前阅读）

□ Am I gathering context or assuming? → Missing info = ask, never fill in

□ Am I asking one question at a time? → Multiple questions overwhelm users

□ Are requirements testable? → Vague requirements = implementation arguments later

□ Did I include edge cases? → Happy path only = bugs in production

□ Is the spec implementable by Claude Code? → Read it as if you'll code it: any ambiguity?

□ Did I document what's OUT of scope? → Scope creep starts with undefined boundaries

□ Are acceptance criteria specific? → "Works correctly" is not acceptance criteria → "Returns 200 with user object containing id, email" is

□ 我是在收集上下文还是主观假设？ → 信息缺失时要询问，切勿自行补充

□ 我是否一次只问一个问题？ → 多个问题会使用户不知所措

□ 需求是否可测试？ → 模糊的需求会导致后续实现分歧

□ 我是否包含了边缘案例？ → 只考虑正常流程会导致生产环境出现bug

□ 该规格文档是否能被Claude Code落地实现？ → 以开发者的视角阅读：是否存在歧义？

□ 我是否记录了排除范围？ → 范围蔓延始于未明确的边界

□ 验收标准是否具体？ → "正常工作" 不是合格的验收标准 → "返回200状态码，且响应包含含id、email字段的用户对象" 才是合格的验收标准

Integration with Other Skills

与其他技能的集成

AFTER spec complete:
    Suggest: "Spec ready. Next steps:"
    - "Use /prd to expand into full PRD"
    - "Use architect-planner to design structure"
    - "Start coding with this spec as context"

AFTER spec complete:
    Suggest: "Spec ready. Next steps:"
    - "Use /prd to expand into full PRD"
    - "Use architect-planner to design structure"
    - "Start coding with this spec as context"