# PRD 撰写方法论 — Hunt 阶段调研手册 v1

> 训练对象：`prd-methodology-trial`（独立试验节点，训练目标是「工程类方法论」技能，非爬虫抓取技能）
> 产出用途：供 Digester（Phase 2）提炼评分维度、后续 Evolver 打磨技能包
> 调研人：innovator-hunt（Hunter）
> 日期：2026-08-23
> 每条论断的出处见同目录 `sources.json`，本文件里用 `[S-xx]` 引用对应条目

---

## §1 外部业界 PRD 方法论对比（4 流派）

四个流派解决的是同一个上位问题——"怎么把一个模糊的业务想法收敛成工程能执行的东西"——但收敛的**切入点**完全不同：Amazon 从"这东西说给客户听有没有人买单"切入，Google 模板从"结构完整性"切入，Cagan 从"哪类失败风险最贵就先打哪个"切入，Shape Up 从"预算多少钱就只能买多详细的方案"切入。下面逐个展开。

### 1.1 Amazon Working Backwards / PR-FAQ

**核心主张**：先假装产品已经发布，倒着写一份对外新闻稿（Press Release，≤1 页，客户能看懂的大白话，禁止术语和内部黑话）+ 一份 FAQ（分「客户会问的」和「内部高管会问的」两类，2-5 页）。如果这份新闻稿读起来不能让客户兴奋，这个想法在写一行代码之前就该被推翻或重做。`[S-01][S-02]`

**结构**：
- Press Release：标题、副标题、一段解决什么问题、一段产品怎么解决、一句 CEO/负责人引语、一句怎么开始用
- FAQ：外部 FAQ（客户视角的疑问）+ 内部 FAQ（技术可行性、成本、竞对、法务合规等高管视角疑问）

**适用场景**：0-to-1 的新产品/新业务线立项阶段，团队还没有共识"这个东西到底该不该做"。核心价值是**倒逼提前想清楚客户价值**，而不是流程本身。Amazon 内部大量核心产品（Kindle、Prime、AWS）据称经由此流程孵化。`[S-01]`

**和本仓库 DevLoop 场景的差异**：DevLoop 的 BRD→PRD→SDD 链路里，"要不要做"这个判断已经在更上游（人类下任务 / org-planner 拆解）完成了，`brd-planning` 拿到的是已经拍板要做的 task-goal，不是一个待验证的商业假设。PR-FAQ 的"客户会不会买单"这层判断在 DevLoop 里没有对应节点——这是一个明确的空当：`brd-planning` 目前只负责"谁在用/痛点/范围"，没人负责"这东西做出来后，人类下任务的人会不会觉得达到预期"这个价值判断（这恰好是 e2e-demo 反面案例暴露的空当之一，见 §4）。

### 1.2 Google PRD 模板

**核心主张**：不存在单一"Google 官方发布"的 PRD 模板文件（`[S-03]` 检索未找到 Google 官方一手文档，以下是业界对"Google 风格 PRD"的通行归纳，**标注未核实**）。通行结构是问题定义 → 目标（Goals）→ 非目标（Non-goals）→ 用户故事 → 功能需求（区分 functional/non-functional）→ 成功指标 → 里程碑/责任人。`[S-03]`

**结构**：标准四段式——Context/Problem → Goals & Non-goals → User stories / Requirements → Success metrics，外加干系人和时间线附录。

**适用场景**：多团队协作、需要一份"单一事实来源"文档去对齐工程/设计/PM 三方预期的场景，强调**显式排除范围**（Non-goals）防止范围蔓延。

**和本仓库 DevLoop 场景的差异**：这个结构和 `prd-planning` 现有的四类要求（功能清单/行为规则/异常边界/验收线索，见 §3）高度同构——"Non-goals" 对应 `out_of_scope_inherited`，"Goals"对应功能清单。本仓库比通行 Google 模板**多一层**本行业模板没有的硬约束：`traceability`（逐条回扣 BRD in_scope/out_of_scope）和结构化 `contract.json`（供下游程序化消费，而不是人读的文档）。这是因为 DevLoop 的下游读者是 `sdd-planning`/`goal-benchmark` 这些 Agent 而非人类工程师，需要机器可解析的契约，通行 PRD 模板不需要考虑这一层。

### 1.3 Marty Cagan《Inspired》产品发现实践 — 风险前置

**核心主张**：产品失败几乎总能追溯到四类风险中的至少一类，且这四类风险应该在**动工之前**（产品发现阶段）用便宜的方式验证掉，而不是等构建完再发现。`[S-04][S-05]`

**四类风险**：
1. **价值风险（Value）**：用户会不会真的选择用它/买它
2. **可用性风险（Usability）**：用户能不能搞懂怎么用
3. **可行性风险（Feasibility）**：工程团队用现有的时间/技能/技术能不能造出来
4. **商业可行性风险（Business Viability）**：这个方案是否在销售/市场/财务/法务等业务约束下站得住

**适用场景**：产品团队自己决定做什么的场景（互联网产品公司常规迭代），核心价值是**把最贵的错误提前到最便宜的阶段暴露**。

**和本仓库 DevLoop 场景的差异**：DevLoop 里 PRD 一路走到 coder 落地之间**没有一个显式的"发现阶段"去验证这四类风险**——`prd-planning` 直接从 BRD 翻译到行为规格，中间没有"这个方案用户会不会真的觉得达到预期"的验证环节；`planner-validator` 验的是"规划产物内部自洽/可追溯"，不是"这个规划对最终用户有没有价值"。四类风险里，DevLoop 目前覆盖得最好的是**可行性风险**（`sdd-planning` 的职责）和部分**可用性风险**（PRD §3 异常与边界、§4 验收线索里的交互细节），**价值风险几乎空白**——这正是 e2e-demo 案例里"过验收但单薄"能够发生的方法论根因之一：没有一个节点的职责是回答"这个产出对访客来说够不够有吸引力/够不够转化"，验收线索因此天然只能覆盖结构性/行为性维度（见 §4、§5）。

### 1.4 Shape Up 的 Pitch 文档

**核心主张**：不写详尽规格，只写一份紧凑的"下注文档"（Pitch），五要素：**问题（Problem）→ 预算（Appetite，多少时间/精力愿意投入，这个数字反过来约束方案有多详细）→ 方案骨架（Solution，用手绘草图级别的粗粒度呈现，不是像素级设计稿）→ 值得点名的坑（Rabbit Holes）→ 明确不做什么（No-gos）**。`[S-06][S-07]`

**结构**：五段固定结构，Solution 段刻意保持"断线画"（breadboard/fat marker sketch）级别的粗糙度，反对过早收敛到详尽规格，理由是**详尽规格会让执行者失去应对实现细节的判断空间，且过早锁定的细节往往在实现中被推翻，写了也是浪费**。

**适用场景**：6 周一个周期的固定预算开发（Basecamp 自己的方法论），团队信任执行者能在骨架内自主决策。

**和本仓库 DevLoop 场景的差异**：这是四个流派里和本仓库现有 `prd-planning` 哲学**冲突最直接**的一个——`prd-planning` agent.md 明确要求"行为规则：输入→输出的确定映射""可判真假的验收线索：每条功能挂一句『怎么算做到了』"，这是详尽规格路线，与 Shape Up 反对的方向正好相反。但 Shape Up 的 **No-gos（明确排除）** 与本仓库的 `out_of_scope_inherited` 高度一致，**Appetite（预算约束方案详细度）** 这个概念本仓库完全没有对应物——DevLoop 目前没有"这次 PRD 该写多细"的预算概念，`prd-planning` 对所有任务用同一套"四类东西必须写清"的详尽度要求，不区分任务量级。这提示一个可能的评分维度：**PRD 的详尽程度是否和任务本身的复杂度/重要度匹配**（过度规格化小任务 vs 规格不足的大任务，都算写虚，参考 §5）。

---

## §2 本仓库 BRD→PRD→SDD 硬约束摘录

来源：`docs/prd/newfunction/_spec/CONVENTIONS.md`（DevLoop 子系统的跨切约定，coder 写代码前必读；本次调研中确认它主要约束 DevLoop **内部实现**——ID 生成、文件写入原子性、日志分流、命名风格——不是 PRD 写作方法论本身）`[S-08]`

与 PRD 直接相关的硬约束摘录：

- **命名风格**（CONVENTIONS.md §11）：PRD/SDD/BRD 相关文档遵循全仓库统一命名——文件名 kebab-case，事件名 dot.snake_case，timeline.kind 用 snake_case（`prd_drafted` 等）。`[S-08]`
- **不变量**（CONVENTIONS.md §12）：跨 unit 只能读 `../{otherUnit}/contract.json`，不能读 `code/`——这条不是 PRD 专属，但揭示了 DevLoop 整体的"契约优先"哲学：下游只信任上游显式导出的契约，不信任隐式实现细节。PRD 的 `contract.json`/`exports` 机制（见 §3）是这条全局哲学在 PRD 节点的具体落地。`[S-08]`

**BRD→PRD→SDD 可追溯性的真正硬约束不在 CONVENTIONS.md，而在 `prd-planning/agent.md` 本身**（见 §3）——CONVENTIONS.md 是 DevLoop 执行层的约定，PRD 撰写方法论层面的约束由各节点 agent.md 自己承载。这是调研中一个需要澄清的认知：任务书里把 CONVENTIONS.md 列为"BRD→PRD→SDD 可追溯性硬约束"来源，实际读下来它更偏工程实现约定；真正定义可追溯性规则的是 §3 摘录的 `prd-planning/agent.md` 正文。

**命名规范补充**（`docs/todo/system-design/27-naming-conventions.md` §二）：`prd-planning` 是本体名，不带前缀；它在 work graph 里的完整链路是 `brd-planning → prd-planning → sdd-planning → goal-benchmark → planner-validator`。`[S-09]`

---

## §3 prd-planning 现成判据摘录（后续 Digester 必须直接复用，不要另起炉灶）

来源：`system/agents/prd-planning/agent.md`，以下为原文摘录（非转述）：

> **判断你写得够不够的唯一标准**：`sdd-planning` 拿着它能直接设计模块，`goal-benchmark` 拿着它能直接写出可度量的验收维度。**做不到就是写虚了。**（第 16-17 行）`[S-10]`

PRD 必须写清的四类东西（第 52-59 行原文表格）：

| # | 类别 | 判自己不合格的信号 |
|---|---|---|
| 1 | 功能清单：每条一句话说清"谁在什么场景下做什么" | 一条功能摊开来能实现成三种不同的东西 |
| 2 | 行为规则：输入→输出的确定映射，含默认值 | 只写了"支持导出"，没写导出什么列、什么顺序、什么编码 |
| 3 | 异常与边界：空/超长/越权/并发/失败重试时**必须**怎么表现 | 只有 happy path。**这一类最常被整块省略** |
| 4 | 可判真假的验收线索：每条功能挂一句"怎么算做到了" | 写"功能正常"。下游 `goal-benchmark` 只能照抄成不可度量的维度（第 59 行原文）`[S-10]` |

其他关键判据（原文）：
- "BRD 的每条 `in_scope` → 至少一条 PRD 功能。**指不到 = 你漏了需求。**"（第 63 行）
- "BRD 的每条 `out_of_scope` → PRD 里**不许**出现对应功能。**出现 = 你扩了范围**"（第 64-65 行）
- "PRD 写技术方案是最常见的越权。『用 Redis 缓存』不是需求，『同一查询 1 分钟内重复请求返回一致结果』才是。"（第 29 行）
- "traceability 那一格是 `planner-validator` 查『覆盖原始需求』时第一个看的东西——**它必须能逐条回扣，不是装饰**。"（第 121-122 行）
- 强制思维隔离清单第 4 条（第 163-164 行）："每条功能挂的 acceptance_hint，`goal-benchmark` 拿着能直接写出可度量的维度吗？还是写成了『功能正常』这种下游只能照抄成废话的东西？" `[S-10]`

**这份判据本身覆盖的是"结构完整性"和"可追溯性"，§4 的反面案例会揭示：即便四类东西全部按字面要求写全、字面上不违反任何一条判据，产出依然可以很单薄**——这是本次调研最重要的发现，直接指向 §5 的候选新维度。

---

## §4 e2e-demo 反面案例深度分析（核心案例）

### 4.1 案例定位

- BRD：`data/companies/e2e-demo/runs/run_c7d233619784/nodes/rn_36f1845d1b53/brd.md`
- PRD：`data/companies/e2e-demo/runs/run_c7d233619784/nodes/rn_42eed93342c5/prd.md`（+ 同目录 `contract.json`、`attempt-0.json`）
- 产出：`data/companies/e2e-demo/projects/p-pyjha7/{index.html,styles.css,script.js}`
- 任务：「lemonboss 产品官网首页」，`attempt-0.json` 显示 `verdict: "produced"`，**一轮过验收，没有 remediation 回合**。`[S-11][S-12][S-13]`

### 4.2 先澄清一个误判：这份 PRD 不是全面写虚的

精读原文后需要纠正任务书里的预设——这份 PRD **不是**"只写了三个卖点区块各一句话说明"这么单薄。实际上它在**结构性/行为性维度**写得相当扎实：
- 明确了区块数量顺序（有且仅 3 个，顺序固定）
- 明确了导航滚动方式（`scrollIntoView` 等效、不写 hash）、URL 不变的验收方法（读 `document.location.href` 前后对比）
- 响应式断点覆盖 6 个具体宽度值，给了数学化判据 `document.documentElement.scrollWidth <= window.innerWidth`
- §3 异常与边界写了 6 种边界场景（断点边界值、超长文字换行、连续快速点击、连续切换点击目标、JS 禁用容错、极端窄屏）
- §5 traceability 逐条回扣 BRD 的 5 条 in_scope，且明确列出 BRD 的 7 条 out_of_scope 均未涉及

这几乎是教科书式地满足了 §3 摘录的"四类东西"要求的第 1/2/3/4 类中的**结构性**部分。`[S-12]`

### 4.3 真正写虚的地方：内容深度、视觉丰富度、CTA——三者都不在"四类东西"的检查范围内

**逐句对应表**（PRD 原文 → 产出实际内容 → 单薄在哪）：

| PRD 原文（§2 行为规则） | 产出实际内容（index.html / styles.css） | 单薄证据 |
|---|---|---|
| "区块内容结构：每个卖点区块必须同时包含一个标题...和一段简要说明文字...**标题和说明都不能为空**" | 三个 `<h2 class="feature-title">` 标题均为 4-6 个汉字（"多智能体协作"等），三段 `<p class="feature-desc">` 均为单句话，约 40-70 字 | PRD 唯一的硬约束是"非空"，没有最低字数/信息密度/是否需要支撑数据或例子的要求，coder 严格满足"非空"即可交付，产出正好卡在"非空"这条线上，不多写一个字 |
| "视觉风格：整体页面采用**大字体、大图**/大留白排版...不使用密集小字或拥挤布局" | `styles.css` 只有 `font-size: clamp(...)` 字号放大和留白（`padding: clamp(3rem,10vw,6rem)`），**全站 0 个 `<img>` 标签，0 个 icon，0 个插画/背景图** | PRD 把"大图"写进了正文，但 §4 验收线索表对应行只写了"主标题字号明显大于正文字号...区块间有可见的垂直间距"——**完全没有把"图"变成任何可核验的验收条目**。一个在正文里出现但没有对应验收线索的要求，等于没有强制力；coder 只对着 §4 的验收线索表交付，"大图"字面被写了但从未被验收，于是被自然丢弃 |
| §1 功能清单 F-1~F-4（全部功能项） | 无 CTA 相关内容——全站没有任何按钮/链接引导访客"体验/了解更多/联系我们" | **功能清单里从未出现 CTA 这一项**，甚至 BRD 本身的 in_scope 里也没有 CTA。这不是 PRD 单独的失职——但揭示了方法论层面的空当：BRD §3"做到什么算解决"写的业务成功度量是"访客在几十秒内判断这是不是我要找的产品"，这是一个**转化类目标**，但 BRD/PRD 全程没有把"转化"翻译成任何一条可执行的功能（比如"页面提供一个可点击的下一步入口"）。`prd-planning` 的职责边界（"逐条回扣 BRD，不许漏也不许多"）决定了它不能替 BRD 补这个洞——但也没有任何节点的职责是"检查 BRD 的业务成功度量是否被功能清单真正承接"，这个检查点在当前 DevLoop 链路里是空的 |

### 4.4 根因结论：验收线索表决定了"什么会被验收"，验收线索表覆盖的维度决定了产出的天花板

`prd-planning` agent.md 自己讲得很清楚："`goal-benchmark` 拿着它能直接写出可度量的验收维度"——这句话反过来也成立：**`goal-benchmark`/`planner-validator` 不会验收 PRD §4 验收线索表里没写的东西**。这份 PRD 的 §4 表格五行分别对应：区块完整性（DOM 结构）、平滑滚动（行为）、URL 无 hash（行为）、无横向溢出（响应式）、视觉风格（仅字号+留白，量化到"一眼可辨"这种主观判据）。**这五行清一色是结构性/技术性可断言的维度，没有一行覆盖"内容有没有说服力""视觉是否真的丰富""有没有转化路径"这类内容/体验维度**。

这不是这份 PRD 在"四类东西"检查表上失分——它在字面上四类都写了。真正的问题是：**"四类东西"检查表本身对"内容深度/视觉丰富度/转化路径"这三类维度没有覆盖，导致即便逐条打钩也无法排除单薄产出**。这是本次调研对训练目标（评分维度设计）最重要的发现，直接构成 §5 候选清单的核心依据。

---

## §5 初步质量维度候选清单（供 Digester 设计评分维度参考，非最终定稿）

基于 §1-4 的调研，候选维度分两组：

**A. 本仓库现有判据已覆盖（Digester 应直接复用 §3 原文，不要重新发明）**：
1. 功能清单完整性（谁/场景/做什么，不可摊开成多种实现）
2. 行为规则确定性（输入→输出映射含默认值）
3. 异常边界覆盖度（空/超长/越权/并发/失败重试）
4. 验收线索可判真假性（不是"功能正常"这种废话）
5. BRD 回扣完整性（in_scope 不漏、out_of_scope 不扩）
6. 技术中立性（不越权写实现方案）

**B. e2e-demo 案例揭示的空当，现有判据未覆盖，建议纳入新维度候选（需 Digester 进一步验证是否具备可操作性）**：
7. **内容深度是否有下限**：PRD 对文案类需求是否只要求"非空"，还是要求信息密度/最小长度/是否需要具体化的支撑内容（数据、例子、场景化描述）
8. **正文提及但未挂验收线索的要求是否等于没写**：PRD 正文出现的形容词性要求（"大图""丰富""有吸引力"）若在 §4 验收线索表里没有对应的可核验条目，应被视为无强制力——这条本身可以变成 PRD 自检项："正文每一句形容词性要求，是否都能在验收线索表里指到对应行"
9. **BRD 业务成功度量与功能清单的映射完整性**：BRD 的"做到什么算解决"（尤其涉及转化/体验类度量）是否被功能清单真正翻译成了可执行功能，而不是被结构性功能"顺带"覆盖
10. **PRD 详尽度与任务量级是否匹配**（借鉴 Shape Up 的 Appetite 概念）：本仓库目前对所有任务用同一套详尽度要求，没有"这次该写多细"的预算感——过度规格化和规格不足可能同样导致下游产出质量问题，只是表现形式相反

以上 B 组是候选，不是定案；Digester 设计具体评分维度和权重时，应结合更多正面案例（目前只有 1 个反面案例）做交叉验证，避免单一案例过拟合。

---

## 附：调研范围内已确认存在但本轮未展开的信息缺口

- e2e-demo 目录下只找到这一个完整的 BRD→PRD→产出链路案例（`p-pyjha7`），没有可对比的"写得好的 PRD"正面案例——建议 Digester 阶段如果需要正面对照，向 org-innovator 申请是否有其它已知的高质量 PRD 产出可供交叉验证。
- Google PRD 模板缺乏官方一手来源，本文档 §1.2 的结构描述来自多个二手聚合站点的交叉印证，**标注未核实**。