product-feature-tech-design

name	product-feature-tech-design
description	将 PRD 翻译成「可独立测试」的功能设计文档。文档的下游使用者包括开发者、评审者、测试者,且三方互相隔离(测试者看不到开发者写的代码),所以必须把行为、状态、接口、数据、权限、异常、验收标准全部显式化,让测试者能独立从文档推导用例。输入是一份已写好的 PRD 文档,输出是一份完整的 Markdown 功能设计文档,保存到当前项目的 `markdown/` 目录。适用于:写功能设计文档、技术设计文档、Tech Design、详细设计说明书、FDD、Functional Design Doc、Detailed Design、模块设计文档、把 PRD 翻译成开发设计、把需求拆成可开发/可测试/可评审的规格。

Product Feature Tech Design

核心约束(决定一切)

测试者看不到开发者的代码。功能设计文档是三方的唯一共同依据:

角色	从文档里读什么	看不到
开发者	接口契约、数据模型、行为规则、边界条件	— (有文档)
评审者	设计原则、权衡取舍、验收标准	— (有文档)
测试者	用例推导的完整基础	开发者的源代码

→ 文档必须把行为写死,不留给实现者自由发挥的空间;同时不规定实现细节(避免越界成架构图)。这条边界是这份文档的灵魂。

输入

• 一份 PRD 文档(本项目 markdown/ 下,或用户提供的路径)。
• 用户的额外约束(若有):技术栈、性能指标、合规要求等。

如果输入没有 PRD,先停下来问用户要 PRD,不要凭空白生成功能设计文档。

工作流

1. 通读 PRD 并提取产物

   • 目标用户、核心场景、成功指标、范围切片。
   • 所有功能模块、用户故事、边界条件、权限点。
   • 显式列出 PRD 中没说清的地方,作为"待确认项"记入文档,不擅自补全。

2. 按 references/feature-design-template.md 起骨架

   • 不要跳过任何章节。允许"本章不适用"标注,但不能整章删除。
   • 每章用 PRD 中的事实填充,缺数据时标"待确认",不要瞎编。

3. 深化关键章节(优先级从高到低)

   • 接口规格 → 读 references/api-spec-template.md,每个端点都给出:请求/响应字段表、错误码表、幂等性、限流、鉴权点。
   • 状态机 → 读 references/state-machine-template.md,每个实体都要画出状态转移图,包括非法转移。
   • 测试矩阵 → 读 references/test-matrix-template.md,用维度(角色 × 操作 × 数据状态 × 环境)穷举测试面,测试者直接按矩阵写用例。

4. 验收标准必须可执行

   • 全部用 Given/When/Then 写,每条只测一个点。
   • 包含:正常路径、异常路径、权限路径、数据边界、并发/超时、跨模块交互。
   • 性能/可用性指标给出具体数值(p99 ≤ 200ms、错误率 < 0.1%),不给"较快"。

5. 自检(见下方质检清单)

   • 如果任一项不过,补完后再交付。

6. 保存

   • 路径:markdown/<topic>-feature-design-<YYYYMMDD>.md
   • 如果生成了 SVG 图,保存为 markdown/<topic>-<diagram-name>-<YYYYMMDD>.svg,在文档中用相对路径引用。

文档与下游的契约

给开发者(可实现)

• 完整的数据模型:实体、字段、类型、约束、生命周期、索引建议。
• 完整的接口契约:路径、方法、入参/出参/错误码、幂等、限流、鉴权。
• 业务规则用自然语言 + 决策表 / 伪代码,不规定框架、不规定语言、不规定文件结构。
• 状态机:所有合法/非法状态转移。
• 依赖关系:对外部模块/服务的契约要求。

给评审者(可检查)

• 设计决策与备选方案(为什么选 A 不选 B)。
• 非功能性指标(性能、可用性、安全、可观测性)的具体数值。
• 与 PRD 的对齐情况(每条 PRD 需求都有对应设计章节)。
• 风险点与缓解措施。

给测试者(可独立写用例,最关键的读者)

• 每个功能的前置条件、操作步骤、期望结果(逐字段,不要"返回成功"这种模糊描述)。
• 输入数据矩阵:合法、非法、边界值(0、最大值、Unicode、SQL 注入字符、超长字符串等)。
• 状态前置:基于哪一状态才能触发此操作。
• 并发与时序:重入、双击、过期、跨时钟。
• 错误码表:每种错误码对应的触发条件 + 用户可见提示。
• 不变量:无论什么操作,系统都应保持的性质(如"用户余额永远 ≥ 0")。

质检清单(交付前自检)

• 每个 PRD 中的功能点都能在文档中找到对应章节。
• 每个对外接口都有完整的请求/响应/错误码表。
• 每个有状态的实体都有状态机图,且包含非法状态。
• 每条业务规则都用 Given/When/Then 或决策表表达,无歧义。
• 测试矩阵覆盖:角色 × 操作 × 数据状态 × 环境,且每个单元格都有预期结果。
• 性能/可用性指标都有具体数值,不是"较快/较稳定"。
• 权限矩阵明确:每个角色对每个资源的可见/可操作/不可操作。
• 至少 1 张图(系统上下文、流程、状态机、时序均可,优先 Mermaid)。
• "待确认项"清单存在,每项都标明对哪条设计有影响。
• 文档不规定具体语言/框架/库/目录结构(只规定行为和契约)。

输出

• 一份 Markdown 文件,保存到当前项目 markdown/ 目录(不存在则创建)。
• 文件名:<topic>-feature-design-<YYYYMMDD>.md,其中 <topic> 用 PRD 的主题拼音/英文 slug。
• 文档用中文(除非用户要求其他语言)。
• 文档长度没有硬性上限,但应详尽到让测试者能独立写用例为准;不要为简洁而省略边界。

参考资料

• references/feature-design-template.md — 完整模板(16 章节),骨架必读。
• references/api-spec-template.md — 接口契约子模板,深化"对外接口"章节时使用。
• references/state-machine-template.md — 状态机子模板,深化"状态机"章节时使用。
• references/test-matrix-template.md — 测试矩阵子模板,深化"验收标准"章节时使用。