10. PRD — 在写下第一行代码之前要确定的事

本系列的前 9 篇讲的是 Alice 是什么 — 人格、记忆、skills、hooks、多智能体、验证、令牌经济、会话协议。住在系统内部的那些东西。

接下来三篇讲的是 穿过 Alice 流动的工作本身。代码开始之前意图的形状，判定代码是否完成的关卡，以及在操作者不把手放在键盘上时让这两者运转的循环。

这是三篇中的第一篇。PRD。

我认为 PRD 最容易被误解的地方，在于它不是策划文档，而是意图的耐久表面。以前我们把决策放在聊天记录里；如今放在 PRD 里，由于那个表面是持久的，下一次会话和下一位协作者才能无需重建就直接读到。

0. 出发前提 — 代码是最后才写的

大多数操作者从代码开始。打开编辑器，写一个函数，看看能不能跑。

这种模式在工作量超过一个下午的瞬间就会崩塌。昨天的代码不记得自己为什么存在。明天的会话不知道什么算「完成」。团队负责人批准了某个切片，几周后那个切片不再适配整体。

问题不在代码。问题在于意图从未被写在任何耐久的地方。操作者把它装在脑子里，AI 把碎片装在 context window 里——两个表面都会蒸发。

PRD — Product Requirement Document — 就是答案。不是一份策划交付物。是一个表面，让操作者的意图活在会话之外，让下一次会话和下一位协作者无需再问就能读到。

1. 没有 PRD 时崩塌的是什么

我在自己工作中以及在接手他人工作的过程中观察到的几种模式。

• 决策的腐烂。某个选择在某次聊天会话中做出。三周后，包括操作者在内，没有人记得为什么。代码回退、漂移，或者每次会话都被翻案重审。
• 范围漂移。「既然在做，那就顺便」悄悄爬进来。等切片上线时，已经做了四件事而不是一件，那四件事中没有一件被好好审过。
• 完成定义的崩塌。有人报告「功能进去了」。团队负责人问「在什么意义上？」构建过了？测试过了？上线了？审过了？每个答案都是部分的「是」，对话就开始打转。
• 入职的崩塌。新协作者——另一个智能体、另一位团队成员、在全新上下文里的未来 Alice——找不到入口。他们从代码里反推意图，而那正是操作者花钱想避开的循环。

共同的线索和第 1 篇——为何是 Alice开篇的那一句一样。操作者的心智——代码背后的目的——没有越过会话边界活下来。

2. PRD 是心智被耐久化后的表面

PRD 的职责窄而具体。它不安排任务，不分配负责人，不追踪进度。那些归别处管。

PRD 回答一个问题：我们在造什么，什么算造好了？

注意这个列表里没有的东西。没有任务清单，没有每日日志，没有谁做了什么。那些东西每次会话都在变。PRD 只在意图变化时才变，而意图变得慢得多。

PRD 描述目的地。其他一切描述路线。

3. 放什么进去，留什么在外面

我在写过四十页的 PRD 和一张明信片就能装下的 PRD 之后收敛出的规则：

放进 PRD： 如果修改这一行会改变系统是什么。例子——「i18n 必需，六个 locale」、「下载必须显示 SHA-256」、「操作者真实姓名不得出现在任何地方」。

不放进 PRD： 如果修改这一行只改变系统是怎么被造出来的。例子——「构建用 pnpm」、「UI primitive 用 shadcn」、「commit 加 [devAlice] 前缀」。

第二类住在 CLAUDE.md 或某个 README，或者工具相关文档里。不在 PRD。

这种分离的理由不是审美，是寿命。PRD 的行应该活过一年。构建系统相关的行可能撑不过两个季度。把它们分在不同文档，让各自按自己的节奏腐烂，不至于互相拖累。

4. 累积式关卡模式

我在 PRD 里用过的最有用的模式是累积式 release gate 章节。

形状：

关卡 0: M0 发布 (临时域名)
  - 构建通过
  - 四个分类路由渲染
  - 每个分类一篇种子指南
  - ESLint clean

关卡 1: 合规 (上线前必须)
  - Privacy Policy (ko + en)
  - 内容许可 (CC BY)
  - 代码许可 (MIT)
  - About 页面存在
  - ...

关卡 2: 基础设施
  - 自有域名绑定
  - SSL 启用 (自动)
  - 生产 env 变量设置
  - ...

关卡 3: 安全
  - 无硬编码 secret
  - .env.example 包含所有 key
  - 用户表 RLS 启用
  - ...

... 关卡 10

每个关卡是一个表。每行是 [条目 | 状态 | 备注]。状态是五选一——✅ 通过 / ⏳ 进行中 / 🔒 等待操作者 / ❌ 未开始 / — 不适用。

让这个模式奏效的有三件事。

累积。 关卡 2 假设关卡 1 已通过。关卡 9 假设 0–8 都通过。路的形状内建于文档中。没有人需要问「按什么顺序？」——文档自己回答。

原子单元的行。 一行要么通过要么不通过。「基本能跑」不是状态。这条纪律强迫操作者把模糊条目（「性能还行」）拆成可勾选的行（「Lighthouse Performance ≥ 90，五个参考页面」）。

行级可见状态。 操作者不必读散文也能知道项目在哪里。扫一眼这一列——数 ✅ 与 🔒 的个数——画面立刻出现。

这是团队负责人每次会话最先读的章节。它也是驱动第 11 篇——Release gates和第 12 篇——Ralph loop的章节。

5. PRD 不是一次性的 plan

操作者经常把 PRD 和会话级的 plan 搞混。它们不是同一回事，活在不同的时间尺度上。

一行意图如果在这些文档间漂移——今天落在 HANDOFF，明天在 PLAN，后天在某次聊天会话——永远不会累积。同一份意图必须能在一个一致的地方表达。PRD 就是那个地方。

会话开始时，Alice 先读 PRD.md，再读 HANDOFF.md，再读 PLAN.md。读出的内容叠加。PRD 定下什么算数；HANDOFF 说操作者停在哪里；PLAN 说这个切片正在发生什么。

6. 让 PRD 活着

一份腐烂的 PRD 比没有 PRD 更糟，因为所有人还在读它、还在按陈旧的意图行动。我保持在轮转中的三个习惯。

就地版本控制。 文件顶部：v1.0 → v1.1 → v1.2。每个版本附一行变更说明。当前版本就是最新的那一行。不另设 changelog 文件。

未决问题章节是必需的。 我写的每份 PRD 都有「未决问题」章节，在活跃开发期间从不为空。如果它变空，要么项目结束了，要么有人把决定藏在脑子里。

每个里程碑做状态复审。 一个里程碑收尾时，把整张关卡表走一遍。在里程碑期间转到 ✅ 的条目晋升；没人碰过的条目迁移到未决问题章节。PRD 是当前意图的快照，不是历史意图的快照。

7. 陷阱

我在实践中看到 PRD 崩塌的几种模式。

7.1 把 PRD 当营销文案

「令人愉悦的 UX」「世界一流的性能」这种行。这些行里没有任何可测试的东西。删掉。如果「性能」很重要，写「Lighthouse Performance ≥ 90，移动端，五个参考页面」。

7.2 把 PRD 当任务清单

每一行都以动词开头。「实现 X。构建 Y。连接 Z。」那是工作板，不是 PRD。PRD 的行描述系统——它是什么、它必须做什么——不是把它做成那样的工作。

7.3 从不更新的 PRD

PRD 顶部还写着 v1.0，而里程碑已经到 M3。要么决策在聊天会话里发生且没有回到这里，要么项目正在陈旧意图上漂流。两个都是警告信号。

7.4 决策落在聊天里，不在 PRD 里

团队负责人在 Slack 消息或会话回复里批准了某件事。两周后没人记得为什么。如果一个决策会改变 PRD，那它在会话结束前就要进 PRD。 这是批准的代价。

7.5 两份 PRD

有人写了一份「真正的 PRD」和一份「摘要 PRD」，或者「中文 PRD」和「英文 PRD」开始漂移。挑一份。多语言表面是给用户的；PRD 是给团队的，活在一种语言、一份文件里。

下载 — PRD 模板

一份可直接复用的 PRD 模板：工作范围、全局约束、验证命令、决策权矩阵，以及每一条的完成标准。本文所描述的结构，打包成一个文件。

shasum -a 256 PRD-code.md
# expected: 1c41c0e61b3dd027fa261e10a8b1f06381e40ee3ce476c24a8df673acb310e7c

8. 一条原则

我使用 PRD 的整个形状收敛为一句话。

「凡是操作者的心智会在会话之间丢失的，写进 PRD。凡是活不过一个季度的，留在 PRD 外。」

这也是通往接下来两篇的桥。PRD 回答目的地在哪里。第 11 篇——Release gates回答我们怎么知道到了。第 12 篇——Ralph loop回答我们怎么让系统在操作者不牵着手的情况下自己走完大部分路。

这三者合起来，把操作者的意图——第 1 篇里的心智——变成系统能跨会话、跨日、跨协作者运送而不丢失的东西。