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,不要凭空白生成功能设计文档。 工作流 通读 PRD 并提取产物 目标用户、核心场景、成功指标、范围切片。 所有功能模块、用户故事、边界条件、权限点。 显式列出 PRD 中 没说清 的地方,作为"待确认项"记入文档,不擅自补全。 按 references/feature-design-template.md 起骨架 不要跳过任何章节。允许"本章不适用"标注,但不能整章删除。 每章用 PRD 中的事实填充,缺数据时标"待确认",不要瞎编。 深化关键章节(优先级从高到低) 接口规格 → 读 references/api-spec-template.md ,每个端点都给出:请求/响应字段表、错误码表、幂等性、限流、鉴权点。 状态机 → 读 references/state-machine-template.md ,每个实体都要画出状态转移图,包括非法转移。 测试矩阵 → 读 references/test-matrix-template.md ,用维度(角色 × 操作 × 数据状态 × 环境)穷举测试面,测试者直接按矩阵写用例。 验收标准必须可执行 全部用 Given/When/Then 写,每条只测一个点。 包含:正常路径、异常路径、权限路径、数据边界、并发/超时、跨模块交互。 性能/可用性指标给出 具体数值 (p99 ≤ 200ms、错误率 < 0.1%),不给"较快"。 自检 (见下方质检清单) 如果任一项不过,补完后再交付。 保存 路径: 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 — 测试矩阵子模板,深化"验收标准"章节时使用。