prd

PRD 编写技能

编写适用于 RFC 评审、且可供 AI Agent 实现的产品需求文档。

PRD 描述要构建什么以及为什么构建，而不是如何构建或按什么顺序构建。

工作流

1. 收集背景信息

用户描述问题和任何初步想法。探索代码库，了解现有模式、约束和依赖项。

2. 逐项访谈设计决策树

沿着设计决策树逐个分支进行。对于每个决策点：

• 先探索代码库——只有代码无法解答的问题才询问用户
• 每轮只讨论一个主题——不要一次抛出多个问题
• 先解决决策之间的依赖关系，再继续

随着决策树展开，覆盖以下领域：

• 问题与动机（是什么、涉及哪些人、为什么是现在、不采取行动的代价）
• 用户与利益相关方
• 最终状态与成功标准
• 范围与边界（包含什么、明确排除什么、绝不能影响什么）
• 约束（性能、安全性、兼容性、无障碍性）
• 风险与依赖项
• 考虑过的替代方案

如果出现含义模糊或过于宽泛的领域术语，指出这些术语并提出规范术语。

持续讨论，直到达成共同理解。不要人为限制问题数量。

3. 确定模块

概述要构建或修改的主要模块。寻找提取深层模块的机会——接口小巧、隐藏大量实现细节且可独立测试的模块。

与用户确认：

• 这些模块是否符合他们的思维模型？
• 哪些模块值得专门编写测试？

4. 编写 PRD

根据下方模板生成 Markdown 格式的 PRD，并保存到项目根目录下的 prd-<feature-name>.md。只保留与该功能相关的章节。

模板

# PRD: <Feature Name>

**Date:** <YYYY-MM-DD>

---

## Problem Statement

### What problem are we solving?
Clear description of the problem. Include user impact and business impact.

### Why now?
What triggered this work? Cost of inaction?

### Who is affected?
- **Primary users:** Description
- **Secondary users:** Description

---

## Proposed Solution

### Overview
One paragraph describing what this feature does when complete.

### User Experience (if applicable)
How will users interact with this feature? Include user flows for primary scenarios.

### Design Considerations (if applicable)
- Visual/interaction requirements
- Accessibility requirements (WCAG level)
- Platform-specific considerations

---

## End State

When this PRD is complete, the following will be true:

- [ ] Capability 1 exists and works
- [ ] Capability 2 exists and works
- [ ] All acceptance criteria pass
- [ ] Tests cover the new functionality
- [ ] Observability/monitoring is in place

---

## Acceptance Criteria

### Feature: <Name>
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

---

## Durable Architectural Decisions

Decisions unlikely to change regardless of implementation order:

- **Routes/URL patterns:** ...
- **Schema shape:** ...
- **Key data models:** ...
- **Auth/authorisation approach:** ...
- **Third-party service boundaries:** ...

Include only what applies. These anchor the PRD for anyone implementing from it.

---

## Modules

Major modules to build or modify, with interface sketches where helpful.

Do NOT include specific file paths or code snippets — they become outdated quickly. Describe modules by name and responsibility.

- **Module name:** What it owns, what it hides, how callers interact with it
- **Module name:** ...

---

## Testing Strategy

- Which modules are tested and at which tier (unit / integration / component / e2e)
- What makes a good test for this feature (test behaviour through public interfaces, not implementation)
- Prior art — similar test patterns already in the codebase

---

## Technical Context

### Existing Patterns
Patterns in the codebase to follow (describe by name and purpose, not file paths):
- Pattern name — why relevant, how it applies

### System Dependencies
- External services/APIs
- Package requirements
- Infrastructure requirements

### Data Model Changes (if applicable)
- New entities/tables
- Schema migrations required
- Data backfill considerations

---

## Boundary Tiers

### Always (conventions to follow)
- Convention 1
- Convention 2

### Ask First (decisions needing human input)
- Decision area 1
- Decision area 2

### Never (must not be touched)
- Protected area 1 — why
- Protected area 2 — why

---

## Risks & Mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| Risk 1 | High/Med/Low | High/Med/Low | How to mitigate |

---

## Alternatives Considered

### Alternative 1: <Name>
- **Description:** Brief description
- **Pros:** What's good about it
- **Cons:** Why we didn't choose it
- **Decision:** Why rejected

---

## Non-Goals (v1)

Explicitly out of scope:
- Thing we're not building — why deferred
- Future enhancement — why deferred

---

## Interface Specifications (if applicable)

### CLI

command-name [args] [options]

### API

POST /api/endpoint Request: { field: type } Response: { field: type } Errors: 4xx/5xx scenarios

---

## Success Metrics (if applicable)

How we'll know this worked:
- Metric 1: current → target (how measured)
- Metric 2: current → target (how measured)

---

## Open Questions

- Question 1
- Question 2

核心原则

问题优先于解决方案

从问题入手。量化不采取行动的代价。说明此事为何重要。

定义最终状态，而非过程

描述完成后应当存在什么。不要规定实现顺序、优先级或阶段。

不写文件路径

文件路径和代码片段很容易过时。按名称和用途描述模式。根据职责而非位置引用模块。

明确边界，避免偏离

明确划分边界层级（始终允许／需先询问／绝不允许），并说明非目标，避免 Agent 修改稳定代码或构建未被要求的功能。

测试策略即架构

说明各模块在哪个层级接受测试，这能体现架构。深层模块应进行边界测试；纯逻辑应进行单元测试；组合逻辑应进行集成测试。

错误与正确示例

错误（规定实现方式／划分阶段）

## Phase 1: Database
1. Create users table
2. Add indexes

## Phase 2: API
1. Build registration endpoint

错误（缺少 RFC 背景）

## Overview
We need user authentication.

## Acceptance Criteria
- [ ] Users can register
- [ ] Users can log in

缺少：为什么？有什么问题？有哪些风险？考虑过哪些替代方案？测试策略是什么？

正确（可供 RFC 评审）

## Problem Statement
Users can't persist data across sessions. 47% drop off when asked to re-enter
information. ~$50k/month in lost conversions.

## Durable Architectural Decisions
- **Routes:** POST /api/auth/register, POST /api/auth/login
- **Schema:** users table with email (unique), password_hash, created_at
- **Auth:** JWT with 24h expiry, refresh token with 7d expiry

## Modules
- **AuthService:** Owns registration, login, token lifecycle. Callers pass
  credentials, receive tokens. Hides hashing, token signing, refresh logic.

## Testing Strategy
- AuthService: integration tests against real DB (prior art: tests/int/)
- Token validation: unit tests for expiry, malformed tokens, refresh flows

## Boundary Tiers
### Never
- Payment module — unrelated, must not be affected
- User profile schema — separate concern, future PRD

创建 PRD 后

分享之前，请确认：

• 问题陈述清晰且有说服力
• 范围边界明确（边界层级 + 非目标）
• 测试策略覆盖已确定的模块
• 没有可能过时的文件路径或代码片段
• 持久有效的架构决策与实现细节已分开

告知用户：PRD 已保存到 prd-<name>.md。