| 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")。
质检清单(交付前自检)
输出
- 一份 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 — 测试矩阵子模板,深化"验收标准"章节时使用。
