147 lines
13 KiB
Markdown
147 lines
13 KiB
Markdown
# PRD 草案文档规范
|
||
|
||
## 适用范围
|
||
|
||
- 创建、修改或检查任意项目的 PRD、需求草案、产品需求、业务规则文档时遵守本文件。
|
||
- 本文件是通用兜底规范；如果项目已有更具体的需求模板、命名规则或文档结构，优先沿用项目规范。
|
||
- 本文件只约束需求草案阶段，不替代数据模型、API 设计、技术方案、任务拆解或代码实现规范。
|
||
- 需求草案只整理业务目标、规则、数据、边界和闭环，不设计下游实现。
|
||
|
||
## 阶段
|
||
|
||
- `需求草案阶段`：收集和归并已确认需求；未确认项显式标注 `需补` 或 `待确认`；不要求同步修改代码和下游文档。
|
||
- `可进入下一阶段`：需求草案已稳定，阻塞问题已消除，可作为后续数据、API、设计或实现工作的输入。
|
||
- `归档阶段`：需求已经确认并沉淀；新增需求或未确认变更应回到需求草案阶段处理。
|
||
- 如果项目使用不同阶段名称，保留项目名称，但仍遵守本文件的阶段边界。
|
||
|
||
## 文档结构
|
||
|
||
- 文档路径和文件名优先沿用项目既有约定；没有约定时，由用户确认目标路径。
|
||
- 一个需求文档应描述一个清晰业务主题；主题过宽时先建议拆分。
|
||
- 标题、元信息、章节结构优先沿用项目模板；没有模板时，按文档类型使用 `prd-draft-format-template.md` 的整篇文档模板或通用骨架。
|
||
- 不为了套模板创建空章节、空表格、伪造对象或重复内容。
|
||
- 不把同一批数据项、规则或流程在多个章节中重复抄写。
|
||
- 未确认事项必须保留在相关需求语境中，标记为 `需补` 或 `待确认`。
|
||
|
||
## 草案包结构
|
||
|
||
- 当项目使用 `.ai-transition/prd-draft` 作为需求草案过渡区，且用户未指定具体文件时，复杂需求默认按业务能力域和需求主题组织为草案包：
|
||
|
||
```text
|
||
.ai-transition/prd-draft/<capability-domain>/<slug>/
|
||
<topic-slug>-prd.md
|
||
decisions.md
|
||
acceptance.md
|
||
references/
|
||
```
|
||
|
||
- `<capability-domain>` 表示业务能力域或协议域，例如 `order`、`workflow`、`integration`、`notification`；不得用来源项目名、语言、框架、技术层或具体技术组件命名。
|
||
- `<slug>` 表示需求主题，使用小写英文、数字和短横线；不得使用 `new-feature`、`misc`、`test` 等泛名。
|
||
- `<topic-slug>-prd.md` 是唯一主需求草案；文件名必须包含业务主题，目录名过宽时使用更具体的业务短横线名，例如 `erp-integration-prd.md`。如果用户明确提供单个文件路径，则该文件继续作为锚点，不强制迁移为草案包。
|
||
- `references/` 用于存放外部协议、客户材料、历史说明、性能建议、接口草稿、来源摘录等强依赖参考材料；材料必须脱敏、裁剪或摘要化，不得只保留本机绝对路径。性能或优化建议可摘要为 `./references/performance-notes.md`。
|
||
- `decisions.md` 用于记录确认结论、冲突、取舍、待确认事项和覆盖记录；不得扩写成技术设计、实现计划或任务拆解。
|
||
- `acceptance.md` 用于记录验收补充和边界补充；简单需求可以保持为“以主草案为准”，不得重复扩写主需求。
|
||
- 默认不创建 `flows/`、`rules/` 等额外目录；只有主草案明显过长、辅助文档能减少重复或用户明确要求拆分时，才在同一草案包内新增辅助文档。
|
||
- 主草案内的关联材料必须使用相对主草案的路径，例如 `./references/external-protocol.md`；不得在正文中写用户机器绝对路径。
|
||
|
||
## 文档类型
|
||
|
||
- 需求以触发、步骤、链路、状态流转、分支异常为核心时，优先写成流程文档。
|
||
- 需求以适用对象、执行约束、交付约束、验收约束、禁止事项为核心时，优先写成要求文档。
|
||
- 流程文档必须能看出从触发到结果的完整链路；要求文档必须能看出每条规则是否可执行、可判断、可验收。
|
||
- 选择模板时只使用抽象占位和用户已确认信息，不带入具体业务、具体页面、具体模块或未经确认的示例。
|
||
- 项目已有同类文档风格时，优先沿用项目风格，不强行改成通用骨架。
|
||
|
||
## 文档引用
|
||
|
||
- 用户提供的本机路径或项目内路径只用于定位文件；写入 PRD 正文时必须转成可迁移引用。
|
||
- `关联协议`、`关联主流程`、`关联文档`、`参考文档` 等引用优先使用相对当前文档的路径；同目录写成 `./xxx.md`，上级或兄弟目录写成 `../xxx/yyy.md`。
|
||
- Markdown 正文路径使用 `/` 分隔，不使用 Windows `\` 分隔。
|
||
- 不把 `C:\...`、`D:\...`、`/Users/...`、`/home/...` 等用户机器绝对路径写入 PRD 正文。
|
||
- 除非项目规范明确要求，不从项目根目录写路径；需要脱离项目目录共享时，优先写“同目录《文档标题》”或相对当前文档的短路径。
|
||
- 检查或更新既有文档时，发现不可迁移引用路径，应作为 `建议修正` 给出相对当前文档的替代写法。
|
||
|
||
## 需求表达
|
||
|
||
- 用业务语言描述需求：目标、参与方、触发条件、输入、处理规则、输出、状态、边界、异常、权限和生命周期。
|
||
- 用户用实现语言表达时，转译为业务需求：
|
||
- 表、字段、列、属性、model、struct 转为业务数据对象和数据项。
|
||
- API、Service、任务、队列、缓存、页面组件 转为业务能力、流程、交互、集成或展示需求。
|
||
- 索引、唯一约束、字段类型、请求响应结构 转为业务唯一性、校验规则、数据含义或交互约束。
|
||
- 外部非业务方案应转译为业务约束或参考材料：例如“用 Redis 解决性能问题”只可在 `references/` 或 `decisions.md` 中作为来源背景，在主草案中应表达为响应时限、高峰期可用性、一致性、重复提交处理等可验收业务要求。
|
||
- 业务逻辑方案不等同于技术方案。凡是在定义业务判定口径、触发和结束边界、状态有效性、分支结果、异常归类或验收标准的内容，必须写入主草案，不能下放给下游技术方案自由定义。
|
||
- 技术实现方案必须从业务规则中剥离。具体中间件、缓存、队列、索引、部署形态、服务内存状态、任务调度、代码结构等，只能作为参考来源、决策背景或待下游设计处理。
|
||
- 如果同一段方案同时包含业务逻辑和实现建议，应拆分记录：主草案保留业务判定和结果约束，`decisions.md` 记录已确认取舍，`references/` 保存实现建议或性能建议摘要。
|
||
- 如果某个技术名词本身就是项目通用业务术语，可以保留术语，但不要扩展成实现设计。
|
||
- 备选方案只能写成备选或待确认，不写成已确认结论。
|
||
- 同一轮编辑、同一次未提交 diff 或同一轮对话推演中，临时方案被提出后又被否定时，不写入正文作为“不要”“不支持”“取消”等否定事实；正文只保留最终确认需求。只有该方案已经出现在已提交、已确认、已评审或已对外同步的基线版本中，或确实需要声明范围边界以防需求外溢时，才写入变更说明、范围外或决策记录。
|
||
|
||
## 数据表达
|
||
|
||
- 涉及保存、维护、读取、展示、统计或传递的数据时，必须说明数据的业务含义、来源、生成方式、更新时机和使用场景。
|
||
- 数据项统一表达为业务数据项，不写数据库字段类型、ORM 类型、索引、迁移脚本或存储结构。
|
||
- 多值、多对多、明细记录、操作记录、绑定关系等独立存在的数据，应识别为独立业务对象或独立业务记录，不塞进主对象的单个数据项里。
|
||
- “唯一”只能表达为业务唯一性要求，不写索引、约束或数据库实现方式。
|
||
- 值域、状态、类型、来源、等级等要说明业务含义、可见范围、是否参与流程分支和状态流转。
|
||
|
||
## 既有资产
|
||
|
||
- 需求涉及既有业务对象、数据、页面、权限、状态、集成、模块复用或“新增 xxx 功能”时，必须先检查项目已有文档和事实来源。
|
||
- 如果复用既有承载，在需求中写明 `复用既有 <业务对象/流程/页面/模块/集成>`。
|
||
- 如果无法确认是否复用，写明 `待确认：是否复用 <候选承载>`。
|
||
- 只有确认没有合理既有承载，或用户明确确认不存在可复用承载时，才写成创建新的业务对象、流程、页面或集成能力。
|
||
- 与既有文档、实现、术语、权限或业务规则冲突的需求，必须先提示冲突，不得写成确定结论。
|
||
|
||
## 检查口径
|
||
|
||
检查 PRD draft 时至少覆盖：
|
||
|
||
- 完整性：目标、范围、参与方、触发、输入、处理、输出、权限、边界、异常、状态和生命周期是否齐全。
|
||
- 闭环：用户或系统从触发到结果是否能走通；成功、失败、取消、重复、历史数据和异常中断是否有合理结果。
|
||
- 数据：业务数据对象、数据项、来源、生成规则、使用场景、值域和状态是否完整。
|
||
- 文档类型：流程文档是否突出完整链路，要求文档是否突出可执行约束，是否错误套用了不适合的通用骨架。
|
||
- 草案包：复杂需求是否把主需求、参考材料、决策和验收补充分清；`<topic-slug>-prd.md` 是否仍是唯一主草案。
|
||
- 分层：业务逻辑方案是否进入主草案，技术实现方案是否已转译为业务约束或放入参考材料和决策背景。
|
||
- 合理性：是否符合主流产品习惯、正规业务流程、行业常识、权限常识和最小必要复杂度。
|
||
- 复用：是否已检查既有资产，是否误写成新增表、新增接口、新增页面或新增模块。
|
||
- 引用：关联协议、关联主流程、关联文档或参考文档是否使用可迁移引用，是否避免用户机器绝对路径和项目根目录绑定路径。
|
||
- 边界：是否遗漏空数据、重复提交、并发、撤销、回退、历史兼容、不可见、无权限和生命周期结束场景。
|
||
- 未确认项：是否还存在阻塞进入下一阶段的 `需补`、`待确认`、事实冲突或未闭环事项。
|
||
- 越界项：是否混入 API 路径、请求响应结构、SQL、字段类型、类名、文件结构、任务拆解或代码实现。
|
||
|
||
## 问题分级
|
||
|
||
- `阻塞问题`：不解决就无法进入下一阶段，例如核心目标不清、关键流程断裂、权限或数据规则冲突、事实来源冲突。
|
||
- `建议修正`：不一定阻塞，但会导致误解、返工或不符合主流做法，例如命名不清、边界缺失、重复表达、复杂度过高。
|
||
- `可后续确认`：不影响当前主链路，但后续设计或实现前需要补齐，例如提示文案、排序细节、默认展示数量。
|
||
|
||
## 检查输出格式
|
||
|
||
- 检查中一旦识别出真实问题、闭环缺口、业务 bug 风险、事实冲突或明显不合理点，不只指出问题，还要同步给出修正路径。
|
||
- 对 `阻塞问题` 和 `建议修正` 中的每一个问题，必须提供恰好 3 个可执行方案，不能只给 1 个，也不能只说“可进一步讨论”。
|
||
- 每个问题的输出至少包含：
|
||
- 问题描述：当前问题是什么。
|
||
- 影响说明：为什么它会阻塞、返工或产生业务风险。
|
||
- 方案 A / 方案 B / 方案 C：三个彼此可区分的处理方案。
|
||
- AI 推荐最优方案：明确只选一个最优方案。
|
||
- 推荐理由：说明为什么这个方案在当前上下文下最优，以及主要前提和取舍。
|
||
- `可后续确认` 如果本身已经形成明确决策分叉，也按同样格式提供 3 个方案和 AI 推荐；如果只是信息待补，不强制展开 3 个方案，但要说明影响和最晚确认时点。
|
||
- 除非用户明确要求“只列问题不要给方案”，否则检查输出不得只报问题不报方案。
|
||
|
||
## 禁止事项
|
||
|
||
- 禁止修改代码、测试、配置、数据库迁移、构建脚本、部署文件或生成物。
|
||
- 禁止在需求草案阶段写数据模型、API 文档、技术设计、实现计划或任务拆解，除非用户明确切换阶段。
|
||
- 禁止写 API path、HTTP method、鉴权实现、request/response schema。
|
||
- 禁止写 SQL DDL、字段类型、索引、唯一约束、迁移脚本。
|
||
- 禁止写类名、struct、component、router、service、job、queue、cache 或文件结构设计。
|
||
- 禁止为了套模板编造业务对象、数据项、字段清单、状态值、字典值或空章节。
|
||
- 禁止把未确认事项写成确定结论。
|
||
- 禁止把用户的功能需求在未检查既有资产前直接推导为新建表、新增接口、新建页面或新模块。
|
||
- 禁止把用户机器绝对路径或不必要的项目根目录绑定路径写成 PRD 正文中的关联文档引用。
|
||
- 禁止把 Redis、MQ、缓存、索引、分库分表、异步任务、服务部署等实现或性能方案写成 PRD 的确定实现要求；需求草案只能保留其业务目标、约束、验收口径或参考来源。
|
||
|
||
## 模板
|
||
|
||
创建新文档、重建正文结构或需要参考需求项写法时，读取 `prd-draft-format-template.md`。
|