product-specs-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Product Specs Writer

产品规格文档撰写工具

Comprehensive product documentation expertise — from strategic PRDs to implementation-ready specifications that engineering teams can actually build from.

全面的产品文档专业能力——从战略性PRD到工程团队可直接据此开发的可落地实现规格。

Philosophy

理念

Great product specs bridge the gap between vision and execution. They're not bureaucratic documents; they're communication tools that align teams and prevent expensive misunderstandings.

The best product specifications:

Start with the why — Context before requirements
Are testable — Every requirement has clear acceptance criteria
Anticipate questions — Edge cases, errors, and constraints documented upfront
Evolve with the product — Living documents, not static artifacts
Respect the reader — Engineers, designers, and stakeholders can all understand them

优秀的产品规格是愿景与执行之间的桥梁。它们不是官僚化的文档，而是沟通工具，能让团队对齐方向，避免代价高昂的误解。

最佳产品规格具备以下特点：

从“为什么”开始 —— 先讲背景，再提需求
可测试 —— 每项需求都有明确的验收标准
预判问题 —— 提前记录边缘案例、错误情况和约束条件
随产品演进 —— 是活文档，而非静态产物
尊重读者 —— 工程师、设计师和利益相关者都能理解

How This Skill Works

该技能的工作方式

When invoked, apply the guidelines in

rules/

organized by:

```
prd-*
```
— Product Requirements Documents, vision, scope
```
stories-*
```
— User stories, personas, jobs-to-be-done
```
criteria-*
```
— Acceptance criteria, definition of done
```
technical-*
```
— Technical specifications, architecture decisions
```
api-*
```
— API specifications, contracts, versioning
```
edge-*
```
— Edge cases, error handling, failure modes
```
design-*
```
— Design handoff, component specs, interactions
```
rollout-*
```
— Feature flags, rollout plans, experiments
```
metrics-*
```
— Success metrics, KPIs, measurement plans
```
maintenance-*
```
— Documentation lifecycle, versioning, deprecation

调用时，应用

rules/

目录下按以下类别组织的指南：

```
prd-*
```
—— 产品需求文档（PRD）、愿景、范围
```
stories-*
```
—— 用户故事、角色、待办任务
```
criteria-*
```
—— 验收标准、完成定义
```
technical-*
```
—— 技术规格、架构决策
```
api-*
```
—— API规格、契约、版本控制
```
edge-*
```
—— 边缘案例、错误处理、故障模式
```
design-*
```
—— 设计交接、组件规格、交互说明
```
rollout-*
```
—— 功能标志、上线计划、实验方案
```
metrics-*
```
—— 成功指标、KPI、测量计划
```
maintenance-*
```
—— 文档生命周期、版本控制、废弃策略

Core Frameworks

核心框架

Specification Hierarchy

规格层级

┌─────────────────────────────────────────┐
│              VISION                     │  ← Why are we building this?
│         (Problem & Opportunity)         │
├─────────────────────────────────────────┤
│               PRD                       │  ← What are we building?
│      (Requirements & Constraints)       │
├─────────────────────────────────────────┤
│          USER STORIES                   │  ← Who benefits and how?
│       (Personas & Journeys)             │
├─────────────────────────────────────────┤
│      ACCEPTANCE CRITERIA                │  ← How do we know it's done?
│      (Testable Conditions)              │
├─────────────────────────────────────────┤
│      TECHNICAL SPECS                    │  ← How do we build it?
│   (Architecture & Implementation)       │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│              VISION                     │  ← 我们为什么要做这个？
│         (Problem & Opportunity)         │
├─────────────────────────────────────────┤
│               PRD                       │  ← 我们要做什么？
│      (Requirements & Constraints)       │
├─────────────────────────────────────────┤
│          USER STORIES                   │  ← 谁能受益，如何受益？
│       (Personas & Journeys)             │
├─────────────────────────────────────────┤
│      ACCEPTANCE CRITERIA                │  ← 我们怎么知道它完成了？
│      (Testable Conditions)              │
├─────────────────────────────────────────┤
│      TECHNICAL SPECS                    │  ← 我们如何实现它？
│   (Architecture & Implementation)       │
└─────────────────────────────────────────┘

Document Types by Audience

按受众划分的文档类型

Document	Primary Audience	Purpose	Update Frequency
PRD	Leadership, PM, Design	Align on what and why	Per milestone
User Stories	Engineering, QA	Define scope and value	Per sprint
Acceptance Criteria	QA, Engineering	Define done	Per story
Technical Spec	Engineering	Define how	Per feature
API Spec	Frontend, External devs	Define contracts	Per version
Design Handoff	Engineering	Define UI/UX	Per component
Rollout Plan	Engineering, Ops	Define deployment	Per release
Success Metrics	Leadership, Data	Define success	Per quarter

文档类型	主要受众	目的	更新频率
PRD	管理层、产品经理、设计师	对齐目标与初衷	每个里程碑更新一次
User Stories	工程师、QA	定义范围与价值	每个迭代更新一次
Acceptance Criteria	QA、工程师	定义完成标准	每个故事更新一次
Technical Spec	工程师	定义实现方式	每个功能更新一次
API Spec	前端开发、外部开发者	定义契约	每个版本更新一次
Design Handoff	工程师	定义UI/UX	每个组件更新一次
Rollout Plan	工程师、运维	定义部署方案	每个版本更新一次
Success Metrics	管理层、数据团队	定义成功标准	每季度更新一次

The INVEST Criteria (User Stories)

INVEST 标准（用户故事）

Criteria	Question	Example
Independent	Can it be built alone?	No dependencies on unfinished stories
Negotiable	Is scope flexible?	Details can be refined with engineering
Valuable	Does user benefit?	Clear value proposition stated
Estimable	Can we size it?	Enough detail to estimate effort
Small	Fits in a sprint?	Can be completed in 1-5 days
Testable	Can we verify it?	Has clear acceptance criteria

标准	问题	示例
Independent（独立）	它可以单独开发吗？	不依赖未完成的故事
Negotiable（可协商）	范围是否灵活？	细节可与工程师一起完善
Valuable（有价值）	用户能从中受益吗？	明确陈述价值主张
Estimable（可估算）	我们能评估工作量吗？	有足够细节来估算 effort
Small（体量小）	能在一个迭代内完成吗？	可在1-5天内完成
Testable（可测试）	我们能验证它吗？	有明确的验收标准

Specification Completeness Checklist

规格完整性检查清单

PRD Completeness:
├── Problem Statement         □ Clearly defined user pain
├── Success Metrics          □ Measurable outcomes defined
├── User Stories             □ All personas covered
├── Scope                    □ In-scope and out-of-scope clear
├── Constraints              □ Technical and business limits stated
├── Dependencies             □ External dependencies identified
├── Risks                    □ Known risks and mitigations
├── Timeline                 □ Milestones and deadlines set
└── Open Questions           □ Unknowns explicitly listed

Technical Spec Completeness:
├── Architecture             □ System design documented
├── Data Model               □ Schema and relationships defined
├── API Contracts            □ Endpoints and payloads specified
├── Edge Cases               □ Failure modes documented
├── Security                 □ Auth, encryption, compliance covered
├── Performance              □ SLAs and benchmarks defined
├── Monitoring               □ Observability strategy clear
└── Rollback Plan            □ Recovery procedures documented

PRD Completeness:
├── Problem Statement         □ 清晰定义用户痛点
├── Success Metrics          □ 定义可衡量的结果
├── User Stories             □ 覆盖所有用户角色
├── Scope                    □ 明确界定范围内与范围外内容
├── Constraints              □ 说明技术与业务限制
├── Dependencies             □ 识别外部依赖
├── Risks                    □ 记录已知风险与缓解措施
├── Timeline                 □ 设置里程碑与截止日期
└── Open Questions           □ 明确列出未知事项

Technical Spec Completeness:
├── Architecture             □ 记录系统设计
├── Data Model               □ 定义Schema与关系
├── API Contracts            □ 指定端点与负载
├── Edge Cases               □ 记录故障模式
├── Security                 □ 涵盖认证、加密、合规
├── Performance              □ 定义SLA与基准
├── Monitoring               □ 明确可观测性策略
└── Rollback Plan            □ 记录恢复流程

Error Handling Taxonomy

错误处理分类

Error Type	Example	Documentation Required
Validation	Invalid email format	Error message, field highlighting
Authorization	User lacks permission	Error state, escalation path
Resource	Item not found	Empty state, recovery action
System	Database timeout	Retry strategy, user feedback
Business Logic	Insufficient balance	Error explanation, next steps
External	Third-party API down	Fallback behavior, degraded mode

错误类型	示例	所需文档内容
Validation（验证错误）	无效邮箱格式	错误提示、字段高亮
Authorization（授权错误）	用户无权限	错误状态、升级路径
Resource（资源错误）	项目未找到	空状态、恢复操作
System（系统错误）	数据库超时	重试策略、用户反馈
Business Logic（业务逻辑错误）	余额不足	错误说明、后续步骤
External（外部错误）	第三方API故障	降级策略、退化模式

Specification Templates

规格模板

Minimal PRD Structure

极简PRD结构

markdown

undefined

markdown

undefined

Feature: [Name]

Problem

What user problem are we solving?

Solution

High-level approach (1-2 paragraphs)

Success Metrics

Primary: [Metric] from X to Y
Secondary: [Metric] from X to Y

Primary: [Metric] from X to Y
Secondary: [Metric] from X to Y

User Stories

As a [user], I want [goal] so that [benefit]

As a [user], I want [goal] so that [benefit]

Scope

In scope: [List] Out of scope: [List]

Open Questions

Question 1
Question 2

undefined

Question 1
Question 2

undefined

User Story Template

用户故事模板

markdown

**As a** [persona/user type]
**I want** [capability/action]
**So that** [benefit/value]

**Acceptance Criteria:**
- Given [context], when [action], then [result]
- Given [context], when [action], then [result]

**Edge Cases:**
- What if [edge case]? Then [behavior]

**Out of Scope:**
- [Explicit exclusion]

markdown

**As a** [persona/user type]
**I want** [capability/action]
**So that** [benefit/value]

**Acceptance Criteria:**
- Given [context], when [action], then [result]
- Given [context], when [action], then [result]

**Edge Cases:**
- What if [edge case]? Then [behavior]

**Out of Scope:**
- [Explicit exclusion]

Anti-Patterns

反模式

Spec by committee — Over-collaboration produces vague documents
Premature optimization — Specifying implementation details too early
Missing the why — Requirements without context for decisions
Kitchen sink scope — Trying to solve everything in one release
One-way documentation — Specs that don't get updated as learnings emerge
Assumption blindness — Not documenting implicit assumptions
Designer/Engineer telephone — No direct communication, only docs
Success theater — Metrics chosen because they're easy, not meaningful
Spec as contract — Treating specs as unchangeable legal documents
Documentation debt — Outdated specs worse than no specs

委员会式撰写 —— 过度协作导致文档模糊不清
过早优化 —— 过早指定实现细节
缺失“为什么” —— 需求没有决策背景
大而全的范围 —— 试图在一个版本中解决所有问题
单向文档 —— 文档不会随着新认知更新
假设盲区 —— 不记录隐含假设
设计师/工程师传话 —— 没有直接沟通，仅依赖文档
成功假象 —— 选择容易衡量而非有意义的指标
文档即契约 —— 将规格视为不可更改的法律文件
文档债务 —— 过时的文档比没有文档更糟