最近我又遇到一个很典型的场景：一个技术方案我已经知道大方向怎么做，也知道自己基本能 cover 住实现，但流程上还是被要求写 PRD。

老实说，我第一反应是有点抵触。

不是因为我不想写文档，也不是觉得文档没价值。恰恰相反，我很清楚文档在复杂协作里很重要。让我抵触的是那种“为了有文档而写文档”的厚 PRD：背景写很多、价值写很多、用户画像写很多，最后真正能帮我推进工程的内容反而只有几段。

我最近做的一个基础设施模块就是这种情况。技术路线已经比较明确，真正的问题不是“这个需求有没有价值”，而是几个上下游依赖什么时候给到位：上游会提供什么样的数据，下游需要什么样的状态，异常场景怎么兜底。

如果这些东西给到位，我一个人其实能把核心链路推起来。最麻烦的不是写代码，而是等依赖。

所以这时候让我写一个很详细的 PRD，我会觉得不太对。因为它解决不了真正的问题。

举个例子。假如我写十页介绍“为什么需要更智能的调度和规划”，这当然没错：资源要被更好地利用，服务质量要守住，系统也要能根据运行状态做出更合理的判断。但这些话写完，上游数据格式还是不清楚，下游接口边界还是没有定，异常情况下到底该中断、降级还是继续观察，也没有答案。

这种文档写得再漂亮，也不能让我多前进一步。

我真正需要的，其实是一份更小、更硬的文档。我愿意叫它 contract design，或者轻量设计说明。

两种文档，不能混在一起

后来我又想了一下，设计文档其实可以分成两种，不能混在一起。

第一种，是维护在代码库里的“当前事实文档”。它记录的是代码现在已经支持什么、还没支持什么、配置怎么开、接口怎么调用、测试怎么跑。它应该跟着代码一起更新，最好离实现很近。比如一个功能做到一半，就应该能从文档里看出来：哪些路径已经可用，哪些还只是占位，哪些地方需要继续接入。

第二种，是写给人和 Agent 的“方向文档”。它不需要很长，但要把目标、非目标、边界、验收标准讲清楚。尤其是现在很多实现会交给 AI 辅助完成，如果方向文档太模糊，Agent 很容易很快地做出一堆看起来完整、但方向不对的东西。

这两种文档解决的问题不一样。代码库里的文档回答“现在系统是什么样”；轻量 PRD 或设计说明回答“接下来要往哪里走”。前者要贴近事实，后者要约束方向。

             设计文档
                |
      +---------+---------+
      |                   |
  当前事实文档         轻量方向文档
  记录系统现状         说明目标和边界
  跟代码一起更新       给人和 Agent 对齐方向
      |                   |
  降低维护成本         降低跑偏风险
      +---------+---------+
                |
            更稳定地交付

它不用解释太多宏大背景，只要把几件事写清楚：

第一，这个模块负责什么。

比如它只负责根据归一化后的输入，生成一个可以解释的建议结果。它可以说明建议是什么、为什么这么建议、置信度如何、风险在哪里，但在早期阶段不一定要直接改变线上系统。

第二，这个模块不负责什么。

比如上游数据准不准，不应该由核心模块背锅；外部字段最终怎么设计，也不应该渗透进核心逻辑。核心模块只认转换后的内部对象。外部字段变了，应该由适配层和契约测试先暴露问题。

第三，别人必须交付什么。

上游至少要给一份样例输出，字段含义要清楚，缺数据时要有语义。下游至少要给几种典型状态的样例。哪怕真实实现还没完全好，也可以先给模拟数据，让核心逻辑先跑起来。

这才是能推动工程前进的文档。

AI 加速之后，边界比背景更稀缺

我现在越来越觉得，AI 时代写文档的价值也变了。之前读 Cat Wu 关于 Claude Code 和 Cowork 的访谈时，我对里面一个观点印象很深：当 AI 把实现速度拉快之后，真正稀缺的东西会变成产品判断、问题定义和验证能力。

这句话放在文档上也成立。以前文档常常是在回答：“我们要不要投入人力做这个？”因为工程资源很贵，写代码慢，所以前面要做很多论证。但现在很多实现可以被 AI 加速，真正贵的东西变成了判断、边界和契约。

也就是说，文档不应该只是证明“这个需求值得做”，而应该防止我们很快地把一个错误方向做完。

Cat Wu 访谈里还有一个我很认同的点：角色边界会变模糊。工程师会更像产品经理，产品经理也会更像 builder。既然大家都更容易动手做东西，那文档就不能再只是流程材料。它应该像一张地图，告诉人和 Agent：我们现在在哪里，要去哪里，哪些路不能走，走到哪里才算到达。

过去：想法 -> 长文档 -> 排期 -> 实现 -> 验证
现在：想法 -> 轻量方向 -> Agent/人快速实现 -> 及时验证 -> 更新事实文档

这点在基础设施系统里尤其明显。AI 可以帮我很快生成接口、适配层、测试样例，甚至写一个第一版决策逻辑。但如果我没有先定义清楚内部对象，后面就会很乱：今天直接读一个外部接口，明天上游字段一改，后天下游又要另一种格式，核心模块很快就会变成到处粘胶水的地方。

到那时，代码可能很多，进展看起来也很快，但系统会越来越脆。

厚度不是负责，暴露边界才是

所以我不是反对写 PRD。我反对的是在工程问题上写产品型八股 PRD。

如果一个项目真的涉及多人、高风险、权限、计费、数据一致性、线上回滚，那我支持写详细设计，甚至越细越好。因为这种事情错一次代价很高，文档是在保护团队。

但如果一个项目技术路线清楚、owner 明确、主要风险是上下游契约没定，那就应该把文档写成契约，而不是写成故事。

对我来说，比较理想的方式是这样：

先写一页说明目标和非目标。

再写一页内部对象和 adapter 边界。

再写一页依赖方需要交付的字段样例。

最后写清楚早期验证怎么做：能不能用模拟数据跑出建议结果，缺数据时是否有降级逻辑，资源不足时是否解释原因，状态和指标有没有输出。

这四页比二十页 PRD 更有用。

因为它能把模糊的“你等等我这边开发”变成具体的“你先给我这几个样例和字段解释”。它也能让我先把核心逻辑做起来，而不是被动等所有外部系统都完成。

我觉得这也是我最近对工程协作的一个变化认识：文档不是越厚越负责，文档越能暴露边界才越负责。

厚文档有时候会让人产生一种错觉，好像事情已经想清楚了。但真正一接代码，才发现最关键的问题没人回答：字段从哪来？单位是什么？失败怎么处理？谁来保证兼容？出了问题谁看告警？

这些问题不长，但很硬。

我现在更愿意把时间花在这些问题上。

所以如果有人问我：“这个需求还要不要写 PRD？”

我的答案会是：要写，但不要写厚 PRD。写一份能让工程继续往前走的契约设计。它不需要好看，需要有用；不需要把所有背景讲完整，需要把责任边界钉牢。

尤其是在 AI 能把代码写得越来越快的时候，最重要的不是多写几页说明，而是先把“什么才算对”讲清楚。