| name | prd-authoring |
| description | Use when writing a PRD, starting a new feature that needs requirements, or when user says 写PRD, 产品需求, feature requirements, 需求文档. Defines the 13-section PRD structure with mandatory observability requirements. |
| version | 1.0.0 |
| author | human owner Agent Workflow |
| license | MIT |
| metadata | {"hermes":{"tags":["prd","requirements","product","documentation","workflow"],"related_skills":["global-launch-review","product-positioning","spec-authoring"]}} |
PRD 撰写（Product Requirements Document）
概述
这是 Stage 01。它把 Stage 00 的 Positioning Memo（"为谁 / 为什么"）翻译成可执行的产品范围（"做什么 / 何时做"）。
PRD 跟 Positioning 故意有重叠，但层次不同：Positioning 决定值不值得做，PRD 决定这一期具体做哪些。一个 PRD 一定指向一个已通过有效 Gate 的 Positioning Memo；Gate 可以是人工签字，也可以是 Authority Envelope 内由 orchestrate-delivery-graph 验证的独立 artifact-review PASS。
强制 13 个章节，顺序固定。章节可以为空（写"无"+ 理由），但不能缺失。其中 §12 可观测性需求是绝对强制——即使项目本身不产生可查询数据（§7 为"无"），§12 依然必填。可观测性不容妥协：盲发的项目上线第一天就是黑盒，事件没埋进去就永远丢了。
何时使用
启动本 skill 的典型场景：
- 用户说"写 PRD"、"产品需求"、"需求文档" —— 立即启动
- 一个新 feature 的 Positioning Memo 已通过有效 Gate，需要变成可执行需求
- 用户拿一份草稿 PRD 让你审 —— 用本 skill 的 13 章节结构对照
- 团队对一个 feature 的"这一期做什么"意见不一致
- 写 spec 时发现上游 PRD 残缺 —— 退回来重过 PRD 门
不要使用的场景：
- Positioning Memo 还没通过有效 Gate —— 退回 Stage 00
- bug 修复、配置变更、文案调整 —— 直接做
- 纯技术 spike —— 在
docs/plans/ 记录目标即可
前置条件：Positioning 必须先通过有效 Gate
PRD 不是凭空写的。Stage 0 checklist 全部勾完，并有人工签字或有效的独立 artifact-review PASS，才能进入 Stage 1。没有 Positioning 的 PRD 只是 feature 列表，缺少上游的"为谁/为什么"。
规则：Positioning 已经说过的别重写，引用即可。
| Positioning 里 | PRD 里 |
|---|
| WHO —— 一个具体的人 | §2 目标用户 —— 引用 Positioning 的 WHO，可加细节（现有用户 vs 未来用户） |
| WHY —— 痛点 | §1 产品背景 —— 引用 Positioning 的 WHY，加产品上下文 |
| WHY NOW —— 变化 | §5 或 §1 —— 直接引用原文 |
| ANTI-POSITIONING —— 不是什么 | §10 非目标 —— 用 PRD 语言重述 |
13 个章节（强制，按顺序）
§1 产品背景
一段话讲清楚为什么做这件事。引用 Positioning 的 WHY（link，别重写）。引用现有问题（commit / spec / 用户反馈）。不要写"行业趋势" —— 只写用户/产品相关的上下文。
为什么这么严？行业趋势是公共信息，谁都能写，没有决策价值。PRD 的背景必须能溯源到本仓库、本团队、本用户的具体证据。
§2 目标用户
表格：角色 | 描述。区分现有用户和未来用户。引用 Positioning 的 WHO（link）。
现有 vs 未来的区分是产品决策的核心 —— 给现有用户加便利和给新用户做获客，是完全不同的两件事，验收标准也不同。
§3 用户故事
格式：US-N: <一句话>，每个 US 用"作为 X，我想要 Y，以便 Z"结构。每个 US 必须有 checkbox 格式的验收标准。至少 1 个 US 端到端可测。
验收标准必须可测 —— "用户能保存草稿"是可测的，"用户体验好"不是。
§4 功能需求
格式：FR-N: <一句话>。描述实现级细节，但不写代码。FR 与 US 应能交叉追溯。
实现级细节的意思：另一个工程师读完应该知道行为是什么，不需要回来问你。但不需要选库、写函数签名 —— 那是 spec 的工作。
§5 非功能需求
表格：维度 | 要求。6 个维度：性能 / 安全 / 隐私 / 可扩展 / 可观测 / 可回滚。允许写"无"，但必须给理由。
引用 Positioning 的 WHY NOW（link）—— 如果时间窗口变了，非功能需求往往跟着变。
§6 数据迁移
改 schema 的话强制。不适用则写"无"+ 理由。
必写：备份策略 / 转换公式 / 干跑模式 / 验证。少了任何一个，迁移上线就是赌博。
§7 数据可观测性
项目产生事件 / 日志 / 指标并会被后续查询（admin dashboard、监控）的话强制。每个主要数据流至少 1 个示例查询。不适用则写"无"+ 理由。
注意 §7 跟 §12 的差别：§7 是产品产生的数据流（被外部消费），§12 是项目本身的可观测性（被内部团队消费）。两者可以重叠，但不可以混为一谈。
§8 前端改动
改 API 或加 UI 的话强制。写：组件 / UX 文案 / 时区处理。不适用则写"无"+ 理由。
UX 文案必须写确切文案，不是"显示一个提示"。i18n 考量在这一步就要列出。时区处理如果相关，要写明如何捕获和显示用户时区 —— 这是 PRD 阶段的决策，不是 spec 阶段的细节。
§9 风险
表格：风险 | 等级（高 / 中 / 低）| 缓解。至少 1 个风险。
每个风险都必须有缓解措施。没有缓解的风险不是风险，是接受的事实 —— 那应该写到 §10 非目标里。
§10 非目标
列本期不做的事。至少 3 个。镜像 Positioning 的 ANTI-POSITIONING。
这一节比看起来重要。它是 scope creep 的唯一防护。每一条非目标都给理由（不做 X，因为 Y），让未来想加 X 的人能直接看到决策依据，而不是重新讨论一遍。
§11 验收标准
checkbox list。覆盖：功能 / 性能 / 测试 / 数据迁移 / 回滚。
注意 §11 跟 §3 的 US 验收标准的关系：§3 是单个用户故事的细粒度验收，§11 是项目整体上线门槛。两者都要存在。
§12 可观测性需求（强制章节）
即使 §7 不适用，本章节也强制 —— 可观测性不容妥协。
为什么这么严？因为可观测性是上线前埋的事件，不是上线后补的。一旦发布第一天没埋事件，那段时间的数据永远丢了，无法回溯。代价不可逆。
列出本 PRD 涉及的所有可观测面（新增 + 复用）。包含 5 个子节：
§12.1 新增事件
表格：事件名 | 触发时机 | 关键字段（metadata）| 用途 | 优先级（P0 / P1 / P2）。
§12.2 复用现有事件
如果现有事件能复用，优先扩展 metadata 而非新建事件。例如 user_registered 已经记录注册 —— 加 timezone 字段比新建 user_registered_with_tz 好。
§12.3 事件 schema
如果 events 表要加列，说明：列名 / 类型 / 默认值 / 索引。如果只用现有 metadata JSON，写："events 表不需要 schema 改动"。
§12.4 验收标准
100% 覆盖率目标不是建议 —— 漏一个触发路径就丢一段数据。
§12.5 隐私考量
列出哪些字段是 PII / 准 PII。写明保留期 / 是否脱敏 / 是否给 admin 看。不适用则写"无"+ 理由。
§13 关联
- Kanban 卡 ID（强制，或显式豁免理由）
- 前序 PRD / spec 链接
- 相关 commit SHA
- 大框架（M5 / M6 等）
关联不是装饰。Kanban 卡缺失通常意味着这个 PRD 没在团队计划里 —— 写完没人做，等于没写。
§12 设计原则（附录）
何时观测
- 用户行为边界：注册 / 登录 / 退出 / 关键操作
- 业务关键路径：支付 / 数据导入 / 反馈
- 异常路径：失败 / fallback / 降级
- 性能敏感：慢查询 / 大数据量
何时不观测
- 内部状态变更（如 pipeline 进度 → 用专门的
_pipeline_status.json）
- 高频但低价值事件（心跳、轮询）
- 已经是 PII 的字段（密码哈希、手机号、IP）
metadata 字段命名约定
- 蛇形命名：
tz_input 不是 tzInput
- 简短：
user_id 不是 user_identifier_uuid
- 类型明示：如果可能多类型，文档说清楚（
str | null）
常见陷阱
PRD 没有 §1 背景，直接跳到功能
症状：开篇就是 §3 用户故事。
真实原因：跳过了 Positioning，没上游。回 Stage 0 写 Memo。
§2 "给所有用户用"
症状：目标用户写"所有想做 X 的人"或"中小企业主"。
真实原因：Positioning 的 WHO 不具体。回上游收紧 —— 选一个具体的人。
§12 是 "TBD" 或空白
症状：§12 章节存在但内容是 "TBD" 或占位符。
真实原因：你还没决定观测什么。可观测性不是装饰，是上线前的决策 —— TBD 意味着没决定，会卡下游 spec。把每个 P0 事件先列出来，触发时机写清楚。
§10 非目标缺失或不足 3 条
症状：§10 写"本期不做移动端"就一条。
真实原因：scope creep 必然发生。每条非目标都是未来"我们能加这个吗"的预答辩 —— 现在不写，未来会反复讨论。至少 3 条，每条带理由。
§13 关联空白（无 Kanban、无前序 PRD）
症状：§13 写"无"。
真实原因：你从中间开始 —— 没上 Kanban 注册，没接前序工作。先在 Kanban 系统开卡，再回来写 PRD。否则这个 PRD 写完没人接，等于白写。
§3 / §4 / §12 交叉引用不一致
症状：某个 US 没对应 FR，某个 FR 没对应可观测事件。
真实原因：写的时候没追溯。每条用户故事应该能追到 FR，每条 FR 应该能追到至少一个可观测事件 —— 否则这条功能上线后你怎么知道它 work？
§6 / §7 / §12 出现 "TBD"
症状：强制章节写"TBD"。
真实原因：你还没决定。"TBD" 在强制章节里是红旗 —— Spec 阶段会卡死。要么现在决定，要么显式声明"无"+ 理由。
验证清单
进入 Stage 2（Spec）前，逐项过：
前置门（强制）
结构门（强制）
内容门（强制）
质量门（强烈推荐）
自检问题
- 从没看过这个 codebase 的聪明工程师能实现这个 PRD 吗？ 如果不能，缺什么上下文？
- §10 非目标列出的是团队想要做的事吗？ 如果不是，scope creep 即将发生。
- §12 可观测性够完整吗，admin dashboard 上线第一天就有数据？ 如果你盲发，你忘了埋事件。
Gate 记录
- 所有前置门已勾。
- 所有结构门已勾。
- 所有内容门已勾。
- 所有质量门已处理（或显式豁免 + 理由）。
- 自检问题有书面答案。
- 审阅者已读 PRD，并通过人工签字或结构化独立 review record 作出决定。
Gate 类型：人工签字 / independent artifact-review
Review record 或签字：___________________
日期：___________________
Gate PASS 后进入 Stage 2（Spec）。在 delivery graph 中由 reducer 自动推进；否则使用 spec-authoring skill。
