prd-generator

PRD 生成技能

概述

使用问题优先、假设驱动的方法生成结构化产品需求文档（PRD）。确保问题陈述清晰、决策有证据支撑，实施阶段可追溯。

核心原则： 先验证“为什么”，再确定“怎么做”。问题 → 证据 → 假设 → 解决方案。

适用场景

始终使用：

• 需要定义产品的新功能
• 需要利益相关方达成共识的产品变更
• HIGH/EPIC 复杂度功能的需求收集
• 需要结构化分析的功能请求

特别适用于：

• 需求不明确的功能（渐进式披露）
• 需要跟踪的多阶段实施
• 需要记录决策的功能
• 需要成功指标的产品计划

不适用于：

• 简单的 Bug 修复（无需 PRD）
• 微不足道的配置更改
• 不影响产品的纯代码重构

目的

1. 问题优先：先用证据定义问题，再提出解决方案
2. 假设驱动：提出可衡量、可验证的假设
3. MoSCoW 优先级排序：通过 Must/Should/Could/Won't 防止范围蔓延
4. 实施阶段：通过阶段表（状态、依赖项、计划链接）跟踪进度
5. 决策日志：记录“为何选择 X 而非 Y”，供日后参考
6. 可追溯性：PRD → 规划器 → 开发者，提供完整上下文

工作流

步骤 1：收集需求

交互模式（需求不明确时）：

// Use AskUserQuestion for structured gathering
const problem = await AskUserQuestion({
  question: 'What problem does this solve? (Be specific about user pain points)',
});

const evidence = await AskUserQuestion({
  question: 'What evidence shows this problem exists? (Data, feedback, metrics)',
});

const hypothesis = await AskUserQuestion({
  question: 'What measurable outcome will prove this feature solves the problem?',
});

提示模式（已提供需求时）：

Extract requirements from user prompt or task description

渐进式披露（适用于含糊不清的功能）：

如果需求不明确，请使用 8 阶段提问工作流：

1. 启动：明确功能目标和范围
2. 基础：了解问题背景
3. 调研（市场）：研究类似解决方案
4. 深入探讨：探索功能能力和用户流程
5. 调研（技术）：评估可行性
6. 决策：记录选择和权衡
7. 生成：根据收集的上下文创建 PRD

适用渐进式披露的情况：

• HIGH/EPIC 复杂度功能
• 含糊的用户请求（“让它更好用”）
• 没有现有模式的新产品领域
• 需要利益相关方达成共识的功能

可跳过的情况：

• 需求明确
• 已实现类似功能
• 范围较小的变更

步骤 2：加载模板

// Read PRD template
const template = Read({ file_path: '.claude/templates/prd-template.md' });

模板包含以下必需章节：

• 问题陈述
• 证据
• 核心假设
• 我们不会构建的内容（范围排除项）
• 成功指标表
• 核心能力（MoSCoW）
• 用户与背景
• 解决方案详情（MVP 范围、用户流程）
• 技术方案
• 实施阶段表
• 决策日志表
• 研究摘要
• 风险表
• 待解答问题

步骤 3：填写模板章节

问题陈述（有证据支撑）：

## Problem Statement

[Specific problem description with user impact]

## Evidence

- User feedback: [quotes or summary]
- Data: [metrics showing problem scale]
- Business impact: [why this matters now]

关键假设：

## Key Hypothesis

We believe [capability] will [solve problem] for [users].
We'll know we're right when [measurable outcome].

Example:
We believe adding JWT refresh tokens will reduce user re-authentication friction for mobile users.
We'll know we're right when session timeout complaints drop by 50% and mobile DAU increases by 10%.

成功指标：

指标	目标	衡量方式
会话超时投诉	-50%	支持工单分析
移动端 DAU	+10%	分析仪表板
令牌刷新成功率	>95%	后端日志

核心能力（MoSCoW）：

优先级	能力	理由
必须	JWT 刷新令牌端点	MVP 必需项，可延长会话
必须	刷新时轮换令牌	安全最佳实践
应该	撤销刷新令牌	允许用户从所有设备退出登录
可以	令牌使用情况分析	便于监控，有则更好
不做	生物识别身份验证集成	超出范围，未来再考虑

MoSCoW 定义：

• 必须：MVP 阻塞项——缺少此项，功能就无法正常工作
• 应该：价值很高，时间允许时纳入
• 可以：有则更好，必要时可推迟
• 不做：明确排除在当前范围之外

用户与场景：

## Users & Context

**Primary User**: Mobile app user (iOS/Android) who experiences session expiration mid-workflow

**Current Behavior**: User logs in → session expires after 1 hour → forced to re-login → loses context

**Trigger**: Session expiration during active use

**Success State**: User stays logged in seamlessly, only re-authenticates when truly needed

**Job to Be Done**: When my session expires, I want to continue my work without re-entering credentials, so I can maintain my workflow momentum.

实施阶段表：

#	阶段	描述	状态	并行	依赖	计划链接
1	设计	设计包含刷新令牌流程的身份验证架构	pending	否	-	-
2	后端 API	实现带令牌轮换的 /refresh 端点	pending	否	1	-
3	移动端客户端	在移动 SDK 中添加刷新逻辑	pending	否	2	-
4	测试	为刷新流程编写端到端测试	pending	是	2,3	-
5	监控	在仪表板中添加刷新指标	pending	是	2	-

阶段列说明：

• #：阶段编号
• 阶段：简短的阶段名称
• 描述：此阶段要构建的内容
• 状态：pending | in_progress | completed | blocked
• 并行：此阶段能否与其他阶段并行进行？
• 依赖：必须先完成哪些阶段？（用逗号分隔的编号）
• 计划链接：指向规划器实施计划的链接（.claude/context/plans/impl-{phase}-{date}.md）

决策日志：

决策	选择	备选方案	理由
令牌存储	安全存储（Keychain/KeyStore）	本地存储、会话存储	安全要求——令牌属于敏感信息
刷新策略	收到 401 时自动刷新	用户手动操作	用户体验更佳，对用户透明
令牌有效期	访问：1 小时，刷新：30 天	访问：5 分钟，刷新：90 天	平衡安全性与用户体验

研究摘要：

## Research Summary

**Market Context:**

- Auth0, Firebase use similar refresh token patterns
- Industry standard: short-lived access + long-lived refresh
- OWASP recommends token rotation on refresh

**Technical Context:**

- Existing JWT library supports refresh
- Mobile SDK has secure storage
- Backend already has session management

风险：

风险	可能性	缓解措施
令牌被盗	中	使用安全存储，并在刷新时轮换
刷新循环（令牌无效）	低	添加指数退避机制和最大重试次数限制
时钟偏差问题	低	验证 exp 时采用 5 分钟宽限期

待解决问题：

## Open Questions

- [ ] What happens to active refresh tokens on password change?
- [ ] How do we handle token refresh during network outage?
- [ ] Should we notify user on refresh token expiration?

第 4 步：验证完整性

必需章节检查清单：

const requiredSections = [
  'Problem Statement',
  'Evidence',
  'Key Hypothesis',
  'Success Metrics',
  'Core Capabilities',
  'Implementation Phases',
  'Decisions Log',
];

// Verify all present
const missingRequiredSections = requiredSections.filter(section => !prdContent.includes(section));

if (missingRequiredSections.length > 0) {
  throw new Error(`Missing required sections: ${missingRequiredSections.join(', ')}`);
}

质量检查：

• 问题陈述具体明确（而非含糊不清）
• 证据包含数据或用户反馈
• 假设可衡量（包含指标）
• MoSCoW 至少包含 1 项“必须有”和 1 项“不会做”
• 实施阶段已梳理依赖关系
• 决策日志说明备选方案“为什么不选 X”

第 5 步：编写 PRD

// Generate filename
const featureName = 'auth-refresh-tokens'; // from problem statement
const date = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
const filename = `${featureName}-prd-${date}.md`;

// Write to specs directory
Write({
  file_path: `.claude/context/artifacts/specs/${filename}`,
  content: prdContent,
});

输出位置： .claude/context/artifacts/specs/{feature-name}-prd-{YYYY-MM-DD}.md

来源信息标题：

# PRD: {Feature Name}

**Version**: 1.0
**Author**: PM Agent
**Date**: {YYYY-MM-DD}
**Status**: Draft

集成点

PRD → Planner → Developer 流程

PM 创建 PRD：

## Implementation Phases

| #   | Phase   | Description       | Status  | Parallel | Depends | Plan Link |
| --- | ------- | ----------------- | ------- | -------- | ------- | --------- |
| 1   | Design  | Auth architecture | pending | No       | -       | -         |
| 2   | Backend | /refresh endpoint | pending | No       | 1       | -         |

Planner 读取 PRD：

1. TaskGet({ taskId: 'X' }) → 获取 PRD 位置
2. 读取 PRD → 了解问题、决策和阶段
3. 选择下一个待处理阶段（依赖项已满足）
4. 创建实施计划
5. 使用计划链接更新 PRD：

| 1 | Design | Auth architecture | completed | No | - | [Plan](.claude/context/plans/impl-phase1-2026-02-09.md) |

Developer 读取计划：

1. Planner 的计划链接回 PRD
2. Developer 拥有完整背景信息：问题、决策和依据
3. 在理解“为什么”的基础上进行实现

结果：

• 单一事实来源：查看 PRD 阶段表了解状态
• 可追溯性：PRD → 计划 → 实现
• 保留背景信息：新开发者可阅读 PRD，了解功能

必需章节检查清单

编写 PRD 前，请确认：

• 问题陈述（具体明确，而非含糊不清）
• 证据（数据、反馈、指标）
• 关键假设（可衡量的结果）
• 成功指标表（指标 | 目标 | 衡量方式）
• 核心能力（包含 Must/Should/Could/Won't 的 MoSCoW）
• 实施阶段表（# | 阶段 | 状态 | 依赖项 | 计划链接）
• 决策日志（决策 | 选择 | 备选方案 | 依据）
• 用户与背景（主要用户、待完成任务）
• 技术方案（可行性、依赖项）
• 风险表（风险 | 可能性 | 缓解措施）
• 待解决问题（尚未解决的事项）

常见模式

模式 1：功能请求 → PRD

User: "Add dark mode to the app"

PM:
1. Problem: Users report eye strain in low-light conditions
2. Evidence: 200+ support tickets, 4.2 → 3.8 app rating mentions "too bright"
3. Hypothesis: Dark mode will reduce eye strain complaints by 60%
4. MoSCoW:
   - Must: System-default theme detection
   - Must: Manual toggle in settings
   - Should: Per-screen theme override
   - Won't: Automatic sunset-based switching (future)
5. Phases:
   - Phase 1: Design system color tokens
   - Phase 2: Implement theme provider
   - Phase 3: Update all screens
6. Write PRD → specs/dark-mode-prd-2026-02-09.md

模式 2：含糊不清的请求 → 渐进式披露

User: "Make the app faster"

PM:
1. [Progressive Disclosure: 8-phase questioning]
   - What specific slowness? (App launch? Navigation? Data load?)
   - Where is evidence? (Metrics showing 5s app launch vs 2s competitor)
   - What outcome? (Launch time < 2s for 95th percentile)
2. [After gathering context]
   - Problem: App launch time 5s vs industry 2s
   - Hypothesis: Lazy loading modules will reduce launch to <2s
3. Write PRD → specs/app-launch-performance-prd-2026-02-09.md

模式 3：实施期间更新 PRD

Planner completes Phase 1 design:

Update PRD:
| 1 | Design | Auth architecture | completed | No | - | [Plan](.claude/context/plans/impl-phase1-2026-02-09.md) |
| 2 | Backend | /refresh endpoint | in_progress | No | 1 | [Plan](.claude/context/plans/impl-phase2-2026-02-09.md) |

Add decision to log:
| Token algorithm | RS256 | HS256 | RS256 for key rotation support |

最佳实践

应该做：

• 从问题出发，而非解决方案
• 纳入证据（数据、引述、指标）
• 让假设可衡量
• 明确记录“不会做”的事项（防止范围蔓延）
• 清晰梳理阶段依赖关系
• 记录决策及考虑过的备选方案
• 将阶段链接到实施计划
• 随阶段完成情况更新 PRD

不应该做：

• 尚未陈述问题就直接提出解决方案
• 跳过证据收集
• 使用含糊的成功指标（“做得更好”）
• 忘记确定优先级（所有事项都标为“必须有”）
• 创建阶段却不梳理依赖关系
• 跳过决策依据
• 让 PRD 过时（随阶段进展更新）
• 为琐碎改动编写 PRD

铁律

1. 绝不在基于证据阐明问题之前定义解决方案——先考虑解决方案会产生无人需要的功能，以及无法验证的假设。
2. 始终在 MoSCoW 优先级划分中至少包含一项“不会做”——明确排除事项才能防止范围蔓延和功能无节制增长。
3. 始终使用具体的数值目标，让成功假设可衡量——“改善 UX”或“提升性能”这类含糊结果无法验证或证伪。
4. 始终在开始实施前梳理阶段依赖关系——未发现的依赖项会造成迭代中期阻塞，并导致整个路线图上的延误层层扩散。
5. 绝不让 PRD 在实施期间过时——随着工作推进和新发现的出现，持续更新阶段状态和决策日志。

反模式

反模式	失败原因	正确做法
未定义问题就直接提出解决方案	会做出错误的东西；没有衡量成功的基准	先用证据定义问题，再提出任何解决方案
成功指标含糊不清（“改善用户体验”“提升速度”）	无法验证假设；不知道功能是否成功	设定具体数值目标：“支持工单减少 50%”“加载时间低于 2 秒”
在 MoSCoW 中把所有事项都标为“必须”	缺乏优先级会导致范围无法实现，并错过截止日期	明确标记“不做”事项；将“可做”和“应该做”视为可协商项
阶段划分未标明依赖关系	依赖关系显现后，并行执行的假设就会被打破	实施前填写“依赖”列；并据此阻止执行
启动后任由 PRD 过时	开发人员会失去上下文；决策变成不为人知的团队隐性知识	在整个实施过程中更新阶段状态和决策日志

示例：完整 PRD

# PRD: JWT Refresh Token Implementation

**Version**: 1.0
**Author**: PM Agent
**Date**: 2026-02-09
**Status**: Draft

---

## Problem Statement

Mobile app users experience session expiration (1 hour timeout) during active use, forcing re-authentication and losing workflow context. This creates friction and frustration, particularly for users performing multi-step tasks.

## Evidence

- **Support Tickets**: 200+ complaints about "forced logout" in past 2 months
- **Analytics**: 35% of mobile sessions end with forced re-auth (vs 5% desktop)
- **User Feedback**: App store reviews mention "annoying login prompts" (4.2 → 3.8 rating)
- **Business Impact**: 15% cart abandonment rate correlates with session timeout

## Key Hypothesis

We believe adding JWT refresh tokens will reduce user re-authentication friction for mobile users.
We'll know we're right when session timeout complaints drop by 50% and mobile DAU increases by 10%.

## What We're NOT Building

- Biometric authentication integration (future Phase 2)
- Social login providers (separate initiative)
- Multi-device session management (v2.0)

## Success Metrics

| Metric                     | Target | How Measured            |
| -------------------------- | ------ | ----------------------- |
| Session timeout complaints | -50%   | Support ticket analysis |
| Mobile DAU                 | +10%   | Analytics dashboard     |
| Token refresh success rate | >95%   | Backend logs            |
| Forced re-auth rate        | <10%   | Analytics events        |

## Core Capabilities (MoSCoW)

| Priority | Capability                               | Rationale                                    |
| -------- | ---------------------------------------- | -------------------------------------------- |
| Must     | JWT refresh token endpoint               | Required for MVP - enables session extension |
| Must     | Token rotation on refresh                | Security best practice (OWASP)               |
| Must     | Secure token storage (Keychain/KeyStore) | Prevent token theft                          |
| Should   | Refresh token revocation                 | Allows user logout from all devices          |
| Should   | Token usage analytics                    | Monitoring and debugging                     |
| Could    | Configurable token lifetimes             | Admin flexibility                            |
| Won't    | Biometric auth integration               | Out of scope - future consideration          |
| Won't    | Push notification on token expiry        | Nice to have, defer to v2                    |

## Users & Context

**Primary User**: Mobile app user (iOS/Android) who experiences session expiration during active use (shopping, form filling, browsing)

**Current Behavior**: User logs in → performs task → session expires after 1 hour → forced to re-login → loses form data/cart context

**Trigger**: Session expiration during active use OR app returning from background after >1 hour

**Success State**: User stays logged in seamlessly for up to 30 days (refresh token lifetime), only re-authenticates when truly needed

**Job to Be Done**: When my session expires, I want to continue my work without re-entering credentials, so I can maintain my workflow momentum and complete my tasks.

## Solution Detail

### MVP Scope

**Phase 1**: Design auth architecture with refresh token flow
**Phase 2**: Implement backend /refresh endpoint with token rotation
**Phase 3**: Add refresh logic to mobile SDK (iOS/Android)
**Phase 4**: E2E tests for refresh flows
**Phase 5**: Add refresh metrics to monitoring dashboard

### User Flow

1. User logs in → receives access token (1 hour) + refresh token (30 days)
2. User makes API call → server validates access token
3. Access token expires → next API call returns 401
4. Mobile SDK detects 401 → calls /refresh with refresh token
5. Server validates refresh token → issues new access + refresh tokens
6. SDK retries original API call with new access token
7. User continues seamlessly (no re-login)

### Edge Cases

- Network failure during refresh → retry with exponential backoff
- Refresh token expired → force re-login with "session expired" message
- Refresh token revoked (password change) → force re-login
- Concurrent API calls during refresh → queue and retry after refresh completes

## Technical Approach

**Feasibility**: HIGH

**Dependencies**:

- Existing JWT library (jsonwebtoken) supports refresh
- Mobile SDK has secure storage (Keychain/KeyStore)
- Backend has session management infrastructure

**Integration Points**:

- Mobile SDK (iOS/Android) needs refresh interceptor
- Backend needs /refresh endpoint
- Database needs refresh token storage (w/ expiry)

**Architecture Notes**:

- Access token: 1 hour lifetime, stateless (JWT)
- Refresh token: 30 days lifetime, stateful (stored in DB)
- Token rotation: each refresh invalidates old token, issues new one
- Secure storage: Keychain (iOS), KeyStore (Android)

## Implementation Phases

| #   | Phase       | Description                                      | Status  | Parallel | Depends | Plan Link |
| --- | ----------- | ------------------------------------------------ | ------- | -------- | ------- | --------- |
| 1   | Design      | Auth architecture design with refresh token flow | pending | No       | -       | -         |
| 2   | Backend API | Implement /refresh endpoint with token rotation  | pending | No       | 1       | -         |
| 3   | Mobile SDK  | Add refresh logic to iOS/Android SDK             | pending | No       | 2       | -         |
| 4   | Testing     | E2E tests for refresh flows                      | pending | Yes      | 2,3     | -         |
| 5   | Monitoring  | Add refresh metrics to dashboard                 | pending | Yes      | 2       | -         |

## Decisions Log

| Decision         | Choice                             | Alternatives                           | Rationale                                               |
| ---------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------- |
| Token storage    | Secure storage (Keychain/KeyStore) | Local storage, Session storage         | Security requirement - tokens are sensitive credentials |
| Refresh strategy | Automatic on 401                   | Manual user action, Proactive refresh  | Better UX - transparent to user, no extra UI            |
| Token lifetime   | Access: 1hr, Refresh: 30 days      | Access: 5min/90min, Refresh: 7/90 days | Balance security (short access) and UX (long refresh)   |
| Token algorithm  | RS256 (asymmetric)                 | HS256 (symmetric)                      | Enables key rotation, better for distributed systems    |
| Refresh rotation | Always rotate                      | Rotate on suspicious activity          | OWASP best practice, prevents token replay              |
| Storage location | Database                           | Redis, In-memory                       | Need persistent storage, DB already available           |

## Research Summary

**Market Context**:

- Auth0, Firebase, Okta all use refresh token pattern
- Industry standard: short-lived access + long-lived refresh
- OWASP recommends token rotation on every refresh
- JWT RFC 7519 and OAuth 2.0 RFC 6749 define patterns

**Technical Context**:

- Existing backend uses jsonwebtoken library (supports refresh)
- Mobile SDK has secure storage capabilities
- Backend has session management and database for token storage
- Average API latency: 100ms (refresh won't impact UX significantly)

**Feasibility Assessment**: HIGH

- All dependencies available
- No new infrastructure required
- Clear implementation path
- Low risk of scope creep

## Risks

| Risk                           | Likelihood | Mitigation                                                |
| ------------------------------ | ---------- | --------------------------------------------------------- |
| Token theft (XSS/MITM)         | Medium     | Use secure storage, HTTPS only, rotate on refresh         |
| Refresh loop (invalid token)   | Low        | Add exponential backoff, max 3 retries, fallback to login |
| Clock skew issues              | Low        | Use 5min grace period for exp validation                  |
| DB performance (token lookups) | Low        | Index refresh tokens, implement token cleanup job         |
| Concurrent refresh attempts    | Low        | Use mutex/lock during refresh, queue pending requests     |

## Open Questions

- [ ] What happens to active refresh tokens on password change? (Decision: revoke all)
- [ ] How do we handle token refresh during network outage? (Decision: retry with backoff)
- [ ] Should we notify user on refresh token expiration? (Decision: yes, with "session expired" message)
- [ ] Do we need per-device refresh tokens? (Decision: yes, for "logout all devices" feature)

---

_Generated: 2026-02-09_
_Status: Draft_

相关技能

• context-compressor - 对不明确的需求进行渐进式披露
• plan-generator - 将 PRD 阶段拆分为实施任务
• research-synthesis - 为问题陈述收集证据

指派的 Agent

此技能由以下角色调用：

• pm（产品经理）- 此技能的主要用户

记忆协议（强制）

开始前： 阅读 .claude/context/memory/learnings.md

检查以下内容：

• 之前创建的 PRD
• 此代码库中的功能模式
• 常见决策及其依据

完成后：

• 新的 PRD 模式 → .claude/context/memory/learnings.md
• 重复出现的决策 → .claude/context/memory/decisions.md
• PRD 创建阻碍 → .claude/context/memory/issues.md

假设任务可能中断：如果记忆中没有记录，就代表它没有发生。