prd-authoring

PRD 编写

本技能为编写高质量产品需求文档（PRD）提供全面指导，内容包括：

• 完整的技术规格
• 带优先级、可执行的任务列表
• 相关代码片段和示例
• 清晰的实施阶段
• 可衡量的成功标准

<quality_standards>

优秀 PRD 的标准

优秀的 PRD 必须：

• 可执行：每项需求都能直接实现
• 完整：涵盖功能、非功能和技术需求
• 具体：措辞精准，避免使用“应该”“可能”等含糊词语
• 可衡量：包含可量化的成功指标
• 可实现：提供足够的细节，便于工程团队构建

必需内容

每份 PRD 都必须包含：

1. 问题陈述 - 清楚阐述要解决的问题及原因
2. 目标 - 具体、可衡量的目标
3. 需求 - 功能和非功能需求
4. 架构 - 系统设计、组件、数据流
5. 实施计划 - 包含里程碑的分阶段方案
6. 任务列表 - 可执行的后续步骤（见下方模板）
7. 成功指标 - 可量化的成功衡量标准
8. 代码片段 - 相关示例（见下方指南）

</quality_standards>

<prd_template>

PRD 模板

# [Feature Name] - PRD

## Overview
[2-3 sentence summary]

## Problem Statement
[What problem are we solving? Why now? What's the impact of not solving it?]

## Goals
- [ ] [Primary goal 1 - specific and measurable]
- [ ] [Primary goal 2 - specific and measurable]
- [ ] [Secondary goal 3]

## Non-Goals
[What we explicitly will NOT do in this iteration - sets scope boundaries]

## Requirements

### Functional Requirements
- [FR-1] [User stories/use cases as specific requirements]
- [FR-2] [Acceptance criteria for each requirement]

### Non-Functional Requirements
- [NFR-1] **Performance**: [specific metrics, e.g., "API responds in <200ms at p95"]
- [NFR-2] **Security**: [e.g., "All data encrypted at rest and in transit"]
- [NFR-3] **Scalability**: [e.g., "System handles 10k concurrent users"]
- [NFR-4] **Reliability**: [e.g., "99.9% uptime SLA"]

### Technical Requirements
- [TR-1] [Technology stack constraints]
- [TR-2] [Integration requirements]
- [TR-3] [Data retention/compliance requirements]

## Proposed Architecture

### System Design
[High-level architecture - use text diagrams or mermaid]

[Component A] ←→ [Component B] ←→ [Component C] ↓ ↓ ↓ [Database] [Cache Layer] [External API]

### Component Breakdown
- **Component A**: [Responsibility, technology choice, scaling approach]
- **Component B**: [Responsibility, technology choice, scaling approach]
- **Component C**: [Responsibility, technology choice, scaling approach]

### Data Flow
1. [Step-by-step description of how data moves through the system]
2. [Include error handling, retries, fallbacks]
3. [Describe async/sync boundaries]

### API Design (if applicable)
[Include endpoint specifications, request/response schemas]

## Technical Considerations

### Technology Choices
| Technology | Justification | Alternatives Considered |
|------------|---------------|-------------------------|
| [Tech 1]   | [Why this choice] | [Alternative 1, Alternative 2] |
| [Tech 2]   | [Why this choice] | [Alternative 1, Alternative 2] |

### Trade-offs Analyzed
| Option | Pros | Cons | Decision |
|--------|------|------|----------|
| [Option A] | ... | ... | ✅/❌ |
| [Option B] | ... | ... | ✅/❌ |

### Risks and Mitigations
| Risk | Impact | Probability | Mitigation Strategy |
|------|--------|-------------|---------------------|
| [Risk 1] | High/Med/Low | High/Med/Low | [How to address] |
| [Risk 2] | High/Med/Low | High/Med/Low | [How to address] |

## Implementation Strategy

### Phase 1: Foundation
- [ ] [Task 1.1]
- [ ] [Task 1.2]
- [ ] [Task 1.3]

**Definition of Done**: [Specific criteria for phase completion]

### Phase 2: Core Features
- [ ] [Task 2.1]
- [ ] [Task 2.2]
- [ ] [Task 2.3]

**Definition of Done**: [Specific criteria for phase completion]

### Phase 3: Polish & Launch
- [ ] [Task 3.1]
- [ ] [Task 3.2]
- [ ] [Task 3.3]

**Definition of Done**: [Specific criteria for phase completion]

## Task Breakdown

<task_list_template>
### High Priority (P0) - Blockers for launch
- [ ] **[TASK-1]**: [Actionable task title]
  - Complexity: [Simple/Medium/Complex]
  - Dependencies: [Task IDs or components that must exist first]
  - Parallelizable: [Yes/No - if Yes, specify which tasks can run simultaneously]
  - Testing: [Required/Recommended/None - specify type: unit, integration, e2e]
  - Acceptance criteria: [Specific, testable criteria]

### Medium Priority (P1) - Important but not blocking
- [ ] **[TASK-2]**: [Actionable task title]
  - Complexity: [Simple/Medium/Complex]
  - Dependencies: [Task IDs or components that must exist first]
  - Parallelizable: [Yes/No - if Yes, specify which tasks can run simultaneously]
  - Testing: [Required/Recommended/None - specify type: unit, integration, e2e]
  - Acceptance criteria: [Specific, testable criteria]

### Low Priority (P2) - Nice to have
- [ ] **[TASK-3]**: [Actionable task title]
  - Complexity: [Simple/Medium/Complex]
  - Dependencies: [Task IDs or components that must exist first]
  - Parallelizable: [Yes/No - if Yes, specify which tasks can run simultaneously]
  - Testing: [Required/Recommended/None - specify type: unit, integration, e2e]
  - Acceptance criteria: [Specific, testable criteria]
</task_list_template>

<parallelization_guidance>

### Task Parallelization

Mark tasks as **Parallelizable: Yes** when:
- Task is independent of other in-progress tasks
- Multiple developers/subagents can work on different aspects simultaneously
- Task can be split into independent sub-tasks

**Examples:**

✅ **Parallelizable**
- "Design REST API endpoints" and "Design database schema" - can be done simultaneously with coordination
- "Write frontend user profile component" and "Write frontend settings component" - independent components
- "Set up CI/CD pipeline" and "Set up monitoring infrastructure" - separate infrastructure tasks

❌ **Not Parallelizable**
- "Implement authentication" - blocks on "Design database schema" (dependency)
- "Write API tests" - requires API endpoints to exist first (dependency)

**Format for parallelizable tasks:**
```markdown
- Parallelizable: Yes - Can run concurrently with [TASK-X], [TASK-Y]

</parallelization_guidance>

<complexity_guidance>

任务复杂度级别

简单

• 范围明确
• 没有未知的未知因素
• 遵循既定模式
• 涉及单个系统/组件
• 示例：“为注册表单添加电子邮件验证”

中等

• 需要一定的研究或调查
• 需要集成多个组件
• 需要进行决策
• 存在一些需要解决的模糊之处
• 示例：“实现使用 Google 和 GitHub 登录的 OAuth 2.0”

复杂

• 需要做出重大的架构决策
• 存在跨系统依赖
• 模糊程度高或需要大量研究
• 涉及性能或安全问题
• 需要进行原型设计或探索性验证
• 示例：“设计并实现可扩展的 WebSocket 实时通知系统”

</complexity_guidance>

<testing_guidance>

测试要求

每项任务都必须明确测试需求：

必需 - 对关键功能而言，合并前必须通过测试

• 用户身份验证/授权
• 支付处理
• 数据持久化操作
• 外部 API 集成

建议 - 应进行测试，但不作为阻塞条件

• UI 组件
• 业务逻辑验证
• 边缘情况处理
• 错误场景

无 - 不适用测试

• 配置变更
• 文档更新
• 基础设施设置
• 设计/原型图任务

测试类型：

• unit - 对独立的函数/组件进行测试
• integration - 测试多个组件协同工作
• e2e - 从头到尾测试完整的用户流程
• performance - 负载测试、基准测试
• security - 渗透测试、漏洞扫描

</testing_guidance>

成功指标

• [Metric 1]：[Current value] → [Target value]
• [Metric 2]：[Current value] → [Target value]
• [Metric 3]：[Current value] → [Target value]

未决问题

• [Q1] [需要解决的问题]
  • 选项：[Option A, Option B, Option C]
  • 决策负责人：[Who will decide]

附录

代码片段

[包含相关代码示例 - 参见下方指南]

数据架构

[包含数据库架构、类型定义等]

原型图

[UI 原型图或线框图链接]

</prd_template>

<code_snippet_guidelines>

## When to Include Code Snippets

PRDs SHOULD include code snippets when they clarify technical details. Use for:

### 1. API Design
**Include when**: Defining endpoints, request/response formats

```typescript
// POST /api/users
interface CreateUserRequest {
  email: string;
  password: string; // Hashed with bcrypt
  name: string;
}

interface CreateUserResponse {
  id: string;
  email: string;
  createdAt: Date;
}

2. 数据架构

包含条件：定义数据库模型、类型定义时

// User schema
interface User {
  id: string; // UUID
  email: string; // Unique, indexed
  passwordHash: string; // bcrypt
  createdAt: Date;
  updatedAt: Date;
}

// Indexes
db.users.createIndex({ email: 1 }, { unique: true });

3. 配置示例

包含条件：定义功能标志、环境变量时

# Environment variables
DATABASE_URL=postgresql://...
JWT_SECRET=your-secret-key
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS_PER_MINUTE=100

4. 算法示例

包含条件：解释复杂逻辑时

// Rate limiting algorithm
function rateLimit(userId: string): boolean {
  const requests = redis.get(`ratelimit:${userId}`) || 0;
  if (requests >= LIMIT) {
    return false; // Rate limited
  }
  redis.incr(`ratelimit:${userId}`);
  redis.expire(`ratelimit:${userId}`, 60);
  return true; // Allowed
}

5. 集成示例

包含条件：展示组件交互方式时

// Example: Service A calling Service B
const response = await fetch('http://service-b/api/process', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ data: payload })
});

不要包含的内容

❌ 完整实现代码——PRD 用于描述需求，而非实现 ❌ 业务逻辑细节——留待实际开发时处理 ❌ 样板代码——配置代码除外

✅ 务必包含：接口、架构示例和架构说明 ✅ 务必包含：配置、API 契约和数据模型

</code_snippet_guidelines>

<task_list_guidelines>

创建可执行的任务列表

PRD 中的任务必须满足以下要求：

具体明确

❌ “实现用户身份验证” ✅ “实现 OAuth 2.0 登录，支持 Google 和 GitHub 提供方”

可测试

❌ “让它更快” ✅ “在 1,000 RPS 负载下，API 响应时间的 p95 小于 200ms”

原子化

❌ “构建完整的结账流程” ✅ “构建购物车摘要端点”（众多任务之一）

可测试

每项任务都必须注明测试要求（必需／建议／无）

任务模板（针对 AI Agent 优化）

- [ ] **[TASK-ID]** [Actionable title]
  - **Complexity**: [Simple/Medium/Complex]
  - **Dependencies**: [Task IDs or components that must exist first]
  - **Parallelizable**: [Yes/No - if Yes, specify which tasks]
  - **Testing**: [Required/Recommended/None - specify type: unit, integration, e2e]
  - **Acceptance Criteria**:
    - [ ] [Criterion 1 - must be testable]
    - [ ] [Criterion 2 - must be testable]

</task_list_guidelines>

<anti_patterns>

常见的 PRD 反模式

表述含糊

❌ “系统应该可扩展” ✅ “系统必须支持 10,000 名并发用户，响应时间小于 500ms”

缺少验收标准

❌ “实现搜索功能” ✅ “实现带筛选条件的全文搜索，结果响应时间小于 100ms，支持 100+ 次并发搜索”

没有成功指标

❌ “提高用户参与度” ✅ “在 90 天内将日活跃用户从 1,000 提升至 2,000”

范围无限

❌ “打造最好的电商平台” ✅ “构建 MVP，包含商品目录、购物车和结账功能（通过 Stripe 支付）”

缺少技术细节

❌ “使用数据库” ✅ “使用 PostgreSQL 存储关系型数据，使用 Redis 缓存，并为 email 和 product_id 建立适当的索引”

没有风险评估

❌ [无风险章节] ✅ [包含带缓解措施的风险表]

</anti_patterns>

PRD 编写工作流

1. 理解问题

   • 如有需要，访谈利益相关者
   • 找出当前解决方案的痛点
   • 量化机会

2. 起草需求

   • 从用户故事入手
   • 将其转化为功能需求（FR-1、FR-2 等）
   • 添加非功能需求（NFR-1、NFR-2 等）

3. 设计架构

   • 创建系统图
   • 定义组件及其职责
   • 梳理组件间的数据流

4. 添加技术细节

   • 选择技术并说明理由
   • 记录权衡取舍
   • 包含相关代码片段

5. 拆分任务

   • 划分阶段
   • 创建具体、可执行的任务
   • 确定依赖关系

6. 定义成功标准

   • 设定可衡量的指标
   • 定义基线和目标

7. 审查并完善

   • 对照质量标准检查
   • 确保不存在反模式
   • 与利益相关者确认

完整的 PRD 示例请参见 references/examples.md。