PRD 详细指南
当前入口是
spec-prd。Claude Code/spec:prd与 Codex$spec-prd是兼容别名；契约见spec-prd。
spec-prd 的职责是在 已有系统 上写清楚一次增量需求：当前是什么、要变成什么、变化的边界在哪里。它产出 PRD 级需求文档，让后续 plan 不用猜 WHAT，也不会把 HOW、数据库表、API 字段和 task breakdown 提前写进需求层。
它解决的问题
普通 brainstorm 适合把模糊想法收敛成 requirements brief；spec-prd 适合已有系统上的增量：你已经知道要改哪个产品、页面、后台流程、App 能力或服务能力，但原始描述还不足以直接进入实施计划。
spec-prd 会明确四件事：
- Current System Snapshot：现有行为是什么，哪些来自源码、测试、文档或用户确认。
- Change Delta：本轮是 keep、extend、replace、remove，还是仍需确认。
- PRD-grade WHAT：requirements、acceptance examples、scope boundaries、assumptions 和 outstanding questions。
- Planning Readiness：交给 plan 前，是否还有会迫使 plan 发明 WHAT 的缺口。
什么时候运行
适合：
- 已有后台、App、CLI、服务流程、审批流、交易流或内容流程，要做一次增量。
- 有粗糙 PRD、会议纪要、产品笔记或一段口头需求，需要整理成 plan 可消费的文档。
- 需求里有领域术语、历史行为、权限、合规、异常状态或跨端边界，不能让实现阶段临场猜。
- 需要代码/文档现状证据来校准“当前已经有什么”和“这次要改什么”。
不适合：
- 0-1 全新方向、产品形态还没定：先跑 Ideate 或 Brainstorm。
- 已经有清晰 plan 或 task pack：进入 Work，不要为了仪式感补 PRD。
- 运行时 QA 前的 PRD/Figma/source/路由一致性审查：用 App 一致性审查。
- bug 已有复现和期望行为：通常直接 Debug 或 Work。
输入模式
| 输入 | 处理方式 |
|---|---|
| 一句话增量请求 | 先找存量系统锚点，再问最小阻塞问题，必要时写新 PRD |
artifact_kind: prd-requirements 草稿 | 原地完善，保留 spec_id 和已有 R/AE/BR/NFR 编号 |
| 普通 Markdown、会议纪要、粗糙 PRD | 当参考材料读取，抽取 claims、缺口、假设和 owner 决策 |
| plan/design/task 文档 | 不伪装成 PRD；按内容 handoff 到 plan/work/task 流程，或询问是否要从中重建 PRD |
| 超大初始 PRD | 先给 split-decision 建议；只有 owner 确认模块边界、优先级和发布顺序后才写 child PRDs |
典型流程
用户输入增量 / PRD 草稿
|
v
Phase 0: classify create / refine / validate
|
v
Phase 1: gather current-state evidence
|
v
Phase 2: confirm Change Delta and domain language
|
v
Phase 3: draft / refine / split
|
v
Phase 4: readiness lens and handoff关键边界：
- Provider evidence、源码、测试和文档只提供证据；产品边界由 workflow 汇总并在必要时问 owner。
- stale 或 dirty provider evidence 只能作为 pointer，不能写成 confirmed current-state claim。
- 每次只问当前最影响范围、行为或验收的一小组问题；能从 source 回答的术语和现状，先读 source。
输出文档
默认写入：
docs/brainstorms/YYYY-MM-DD-NNN-<slug>-requirements.mdfrontmatter：
---
spec_id: YYYY-MM-DD-NNN-<slug>
artifact_kind: prd-requirements
target_surface: generic
status: draft
evidence_grade: mixed
created: YYYY-MM-DD
---核心 sections：
SummaryChange DeltaRequirementsAcceptance ExamplesScope BoundariesEvidence And Assumptions
按需加入：
Current System SnapshotGlossaryDecision NotesActorsUse CasesInteraction RequirementsException HandlingData / Compliance BoundariesRelease / Operation ReadinessOutstanding Questions
领域语言、Context 与 ADR
spec-prd 会优先读取项目内已有领域语言和长期决策上下文。普通 PRD 模式的原则是 PRD 内闭环、外部拓扑按需作为证据：缺少 context、glossary 或 ADR 不会阻塞 PRD，也不会触发 silent write。
若仓库存在：
CONTEXT.md
CONTEXT-MAP.md
docs/contracts/domain-glossary.md
docs/adr/**它会把相关文件作为 source-first evidence：已有术语、context 路由或 ADR 决策应复用；新术语与 canonical 定义冲突时要显式提出，而不是静默漂移。术语仍先写入 PRD-local Glossary，决策先写入 Decision Notes / Evidence And Assumptions / Scope Boundaries，确保后续 plan 不必读取外部拓扑也能理解 WHAT。
晋升规则是 preview-first：普通 PRD 模式可以建议把稳定跨 PRD 术语晋升到 docs/contracts/domain-glossary.md，或建议为 hard-to-reverse、surprising without context、real tradeoff 的决策创建 ADR；真正写入需要 owner 确认。只有显式触发 grill-with-docs 深度模式时，已解决的项目专属术语才会 inline 更新相关 CONTEXT.md，ADR-worthy 决策才会 inline 创建或更新 ADR。
这个机制仍是 light contract：不会强制每个项目创建 glossary、CONTEXT.md、CONTEXT-MAP.md、docs/adr/** 或 docs/prds/。需求文档仍写入 docs/brainstorms/*-requirements.md，外部 context/ADR 只是辅助证据，不是 PRD 的第二真源。
模板与 surface
运行时会随 skill 分发通用 PRD 模板，不依赖 spec-first 源码仓库的 docs/ 目录：
| 模板 | 适合 |
|---|---|
00-通用增量需求模板.md | 默认增量需求 |
10-App客户端需求模板.md | App / 客户端 |
20-Admin中后台需求模板.md | 后台 / 运营 / 管理端 |
30-Backend中台服务需求模板.md | 后端服务 / Java / 中台能力 |
项目本地的行业、团队或合规 overlay 可以作为参考叠加；缺失时通用模板仍可工作。
Ready for plan 的判断
交给 Plan 前，PRD 至少要让 plan 不再发明 WHAT：
- 每个核心 requirement 有可追踪 ID。
- 关键需求有 acceptance example。
- 当前系统行为有证据标签或明确 assumption。
- Change Delta 不混淆 keep / extend / replace / remove。
- Scope boundaries 写清楚哪些不做。
- blocker、assumption、outstanding question 分开记录。
- 需求层不提前写实现方案。
如果缺口窄，spec-prd 会问最小阻塞问题或带 assumption 更新文档；如果缺口大，交给 Doc Review 或回到 brainstorm。
常用调用
spec-prd "基于现有订单后台，补齐批量退款审批 PRD"
spec-prd docs/brainstorms/2026-06-01-001-rough-requirements.md
spec-prd "validate docs/brainstorms/2026-06-01-001-refund-requirements.md for planning"