product-specs-writer

产品规格撰写

全面的产品文档编写能力——从战略性 PRD，到工程团队可以据此实际构建的、可直接实施的规格说明。

理念

优秀的产品规格能够弥合愿景与执行之间的差距。它们不是官僚式文档，而是沟通工具，能够让团队保持协同，并避免代价高昂的误解。

最佳的产品规格：

1. 从原因出发——先交代背景，再提出需求
2. 可测试——每项需求都有明确的验收标准
3. 预先解答疑问——提前记录边界情况、错误和限制
4. 随产品演进——作为持续更新的文档，而非静态产物
5. 尊重读者——工程师、设计师和利益相关者都能看懂

此技能的工作方式

调用时，请应用 rules/ 中按以下类别整理的指南：

• prd-*——产品需求文档、愿景、范围
• stories-*——用户故事、用户画像、待完成的工作
• criteria-*——验收标准、完成定义
• technical-*——技术规格、架构决策
• api-*——API 规格、契约、版本管理
• edge-*——边界情况、错误处理、故障模式
• design-*——设计交接、组件规格、交互
• rollout-*——功能标记、发布计划、实验
• metrics-*——成功指标、KPI、衡量计划
• maintenance-*——文档生命周期、版本管理、弃用

核心框架

规格层级

┌─────────────────────────────────────────┐
│              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)       │
└─────────────────────────────────────────┘

按受众划分的文档类型

文档	主要受众	目的	更新频率
PRD	领导层、产品经理、设计	就做什么和为什么达成一致	每个里程碑
用户故事	工程、QA	明确范围和价值	每个冲刺
验收标准	QA、工程	明确完成标准	每个故事
技术规格	工程	明确如何实现	每项功能
API 规格	前端、外部开发者	明确契约	每个版本
设计交接	工程	明确 UI/UX	每个组件
发布计划	工程、运维	明确部署方式	每次发布
成功指标	领导层、数据团队	明确成功标准	每季度

INVEST 标准（用户故事）

标准	问题	示例
Independent（独立）	能否单独构建？	不依赖未完成的故事
Negotiable（可协商）	范围是否灵活？	可与工程团队一起细化具体内容
Valuable（有价值）	用户是否受益？	明确说明价值主张
Estimable（可估算）	能否估算工作量？	细节足以估算所需工作量
Small（规模小）	能否在一个冲刺内完成？	可在 1-5 天内完成
Testable（可测试）	能否验证？	有明确的验收标准

规格完整性检查清单

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

错误处理分类

错误类型	示例	必需的文档内容
验证	邮箱格式无效	错误消息、字段高亮
授权	用户没有权限	错误状态、升级处理路径
资源	找不到项目	空状态、恢复操作
系统	数据库超时	重试策略、用户反馈
业务逻辑	余额不足	错误说明、后续步骤
外部	第三方 API 停止运行	回退行为、降级模式

规格模板

最简 PRD 结构

# 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

## User Stories
- As a [user], I want [goal] so that [benefit]

## Scope
**In scope:** [List]
**Out of scope:** [List]

## Open Questions
- [ ] Question 1
- [ ] Question 2

用户故事模板

**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]

反模式

• 委员会式编写规范 — 过度协作会产出含糊不清的文档
• 过早优化 — 过早规定实现细节
• 忽略原因 — 提出需求却不说明决策背景
• 大杂烩式范围 — 试图在一次发布中解决所有问题
• 单向文档 — 随着经验积累却不更新的规范
• 忽视假设 — 不记录隐含假设
• 设计师与工程师之间的传话游戏 — 没有直接沟通，只靠文档交流
• 成功表演 — 选择指标只是因为它们容易衡量，而非因为它们有意义
• 把规范当合同 — 将规范视为不可更改的法律文件
• 文档债务 — 过时的规范比没有规范更糟