PRD Feature Decision 的关系

背景

很多项目后期维护困难，不是因为代码完全看不懂，而是因为缺少上下文。

代码通常只能告诉我们：

• 当前系统是怎么写的

• 当前接口是怎么调用的

• 当前表结构是什么样的

• 当前逻辑最终执行了什么

但代码很难告诉我们：

• 当时为什么要做这个功能

• 为什么选择这个实现方案

• 为什么不使用另一个方案

• 为什么这个字段不能删除

• 为什么这个表要单独建

• 为什么这个接口设计得比较特殊

• 原始需求和最终实现之间有没有差异

因此，项目文档不能只停留在 README、接口说明、部署说明上，还需要补充功能历史和设计决策。

三类文档的定位

一句话定义：

产品需求文档 PRD：说明“用户要什么”
Feature 功能档案：说明“系统最终怎么实现这个功能”
Decision 决策文档：说明“为什么这样设计”

它们不是重复关系，而是承接关系。

PRD       -> 定义需求
Feature   -> 记录实现
Decision  -> 解释取舍

PRD：说明“用户要什么”

PRD 是产品需求文档，主要从用户、业务和产品视角描述需求。

它重点回答：

• 用户是谁

• 用户要解决什么问题

• 业务流程是什么

• 页面需要展示什么

• 用户如何操作

• 业务规则是什么

• 验收标准是什么

• 哪些场景需要支持

• 哪些场景不需要支持

PRD 更关注：

• 产品目标

• 用户体验

• 业务规则

• 页面交互

• 验收口径

示例：

用户进入 ETF 资金异动榜页面后，默认展示最近交易日的数据。
用户可以选择交易日查看历史榜单。
用户可以查看 ETF 代码、名称、份额变化、排名等信息。

PRD 不应该重点描述具体代码怎么写、数据库怎么设计、定时任务怎么实现。

Feature：说明“系统最终怎么实现这个功能”

Feature 是功能档案，主要从研发、系统和维护视角记录功能最终落地情况。

它重点回答：

• 这个功能最终做成了什么样

• 后端新增了哪些接口

• 前端新增了哪些页面或组件

• 数据从哪里来

• 涉及哪些表或核心字段

• 是否有定时任务

• 如何上线

• 如何测试

• 有哪些风险点

• 和原始需求是否有差异

• 后续可以怎么扩展

Feature 更关注：

• 研发实现

• 系统边界

• 数据流转

• 上线步骤

• 测试点

• 维护信息

• 功能历史

示例：

ETF 资金异动榜初期基于 ETF 份额变化实现。
前端进入页面时，先查询最近一个有榜单数据的交易日，再查询该交易日的榜单数据。
后端通过每日任务生成榜单快照。
榜单数据按交易日保存，不写入 ETF 基础信息表。

Feature 可以包含部分产品内容，但只保留对研发实现和后续维护有影响的内容，不复制完整 PRD。

Decision：说明“为什么这样设计”

Decision 是设计决策文档，主要记录关键技术或业务取舍。

它重点回答：

• 当时遇到了什么问题

• 有哪些备选方案

• 最终选择了哪个方案

• 为什么选择这个方案

• 为什么不选择其他方案

• 这个决策带来了什么影响

• 这个决策有什么代价

• 未来什么情况下可以重新评估

Decision 更关注：

• 设计原因

• 方案取舍

• 长期影响

• 约束条件

• 可推翻条件

示例：

ETF 资金异动榜不写入 ETF 基础信息表，而是使用独立表保存。

原因是 ETF 基础信息表表示当前状态，而资金异动榜表示某个交易日的历史快照。
两者语义不同、生命周期不同、更新频率不同，因此不应混在同一张表中。

Decision 的价值在于：未来维护者不只是知道“现在是这样”，还知道“当时为什么要这样”。

三类文档的区别

它们之间的关系

完整链路应该是：

业务问题
  ↓
PRD：定义用户需要什么
  ↓
Feature：记录系统最终做成什么样
  ↓
Decision：记录关键设计为什么这么做
  ↓
Changelog：记录什么时候完成了什么

也可以理解为：

PRD 是需求入口
Feature 是研发落地档案
Decision 是关键取舍记录
Changelog 是完成摘要

Feature 和 PRD 的边界

Feature 中可以写产品相关内容，但只写对研发有影响的部分。

适合写入 Feature 的产品内容：

• 默认展示规则

• 查询条件

• 列表字段

• 排序规则

• 空数据处理

• 异常场景

• 核心业务规则

• 验收口径

• 与原始需求的差异

不建议写入 Feature 的内容：

• 大量竞品分析

• 用户访谈过程

• 运营文案细节

• 页面视觉细节

• 原型截图全集

• 与实现无关的产品讨论过程

推荐增加“与需求差异”章节

实际项目中，经常会出现：

• PRD 原来要求 A

• 开发过程中因为数据、成本、风险等原因改成 B

• 产品最终接受了 B

• 但半年后没人知道为什么不是 A

因此 Feature 文档中建议保留一个章节：

与需求文档的差异

示例：

这个章节能避免后续维护时反复猜测历史原因。

文档维护原则

1. 不要求所有改动都写文档

小修小改可以只写 commit。

例如：

• 修复文案

• 简单样式调整

• 小 bug 修复

• 非核心字段调整

2. 较完整的功能必须写 Feature

例如：

• 新增页面

• 新增核心接口

• 新增定时任务

• 新增表

• 修改核心业务流程

3. 有明显取舍时必须写 Decision

例如：

• 新增表还是复用旧表

• 同步还是异步

• 拆表还是宽表

• 是否兼容历史数据

• 是否引入新组件

• 是否改变接口模型

4. 文档不要维护过细的实现细节

Feature 和 Decision 不应该维护完整数据库 DDL。

建议只写：

• 表名

• 核心字段

• 字段业务含义

• 关键唯一约束

• 数据来源

• 计算逻辑

真实表结构以以下内容为准：

• migration SQL

• 实体类

• Mapper / Repository

• 线上数据库

文档解释业务含义，SQL 定义真实结构，代码表达当前实现。

最终结论

PRD、Feature、Decision 各自解决的问题不同。

产品需求文档 PRD：说明“用户要什么”
Feature 功能档案：说明“系统最终怎么实现这个功能”
Decision 决策文档：说明“为什么这样设计”

三者配合后，项目中不仅有代码结果，也有业务背景、实现过程和设计原因。

这样后续维护时，开发者不需要完全靠猜。