Product Feature Tech Design

Product Feature Tech Design Skill

将一份 PRD（产品需求文档）转化为一份字段/接口级精度的功能设计文档，作为开发者、reviewer、测试者三方协作的唯一书面契约。

核心理念：这份文档要回答的不是"我们要做什么"（PRD 已经回答了），而是"怎么做才算对、怎么验证它对了"。下游三个角色互相看不到对方的产出——测试者看不到代码，reviewer 不参与开发，三方只能依赖这一份文档对齐。任何一处含糊，都会在三方汇合时变成返工。所以写作时始终假设：读者除了这份文档，什么都没有。

工作流总览

PRD 输入（Markdown/PDF/用户描述）
     ↓
Step 1：解析 PRD，提取功能清单与模块边界
     ↓
Step 2：判断每个模块的"精度档位"（详见 references/precision-rules.md）
     ↓
Step 3：生成跨模块整体架构图（模块依赖/调用关系）
     ↓
Step 4：逐模块编写详细设计（接口契约 + 按需的状态机/数据模型/异常表）
     ↓
Step 5：汇总全局验收检查清单
     ↓
输出到 markdown/ 目录

Step 1：解析 PRD，提取功能清单

读取用户提供的 PRD（可能是 write-prd/write-brd 产出的文件，也可能是用户自己的文档或粘贴的文字）。重点提取：

1. 功能清单：尤其是 Must/Should/Could Have 列表——这些是必须落地到设计文档里的功能点。Won't Have 不需要设计，但可以在文档里简单记一句"本期不做"，避免开发误做。
2. 模块划分：PRD 里的功能通常已经天然分组（比如"订单管理""支付""通知"）。如果 PRD 没有明确分组，按业务实体或用户旅程阶段自己划分，并在文档开头说明划分依据。
3. 已有的验收标准：PRD 里的 Given/When/Then 是设计文档验收标准的起点，不是终点——本 skill 要把它们具体化到字段和错误码层面。
4. 非功能需求：性能、安全、兼容性等，这些会进入每个模块的设计或者文档末尾的全局章节。

如果 PRD 信息不足以支撑字段级设计（比如完全没提数据来源、没提第三方依赖），不要凭空编造看起来精确但其实是瞎猜的字段。按 场景 B：信息不足时的处理 处理（见下文）。

Step 2：判断每个模块的精度档位

这是整个 skill 最容易做错的一步：不是所有模块都需要同样的详细程度，但所有模块都需要同样的"无歧义"程度。差别在于"写多少种文档元素"，而不是"写得清不清楚"。

判断时问自己三个问题（详细判断标准见 references/precision-rules.md）：

1. 这个模块有持久化存储吗？（要建表/存数据）→ 是，则需要独立的数据模型字段表；否（纯计算/纯转发调用），可以省略。
2. 这个模块有明显的状态机吗？（实体有多个状态、状态间有转换规则，比如订单、工单、审批流）→ 是，则需要画状态转换图；否（普通 CRUD），不需要强行画图。
3. 这个模块是核心路径还是辅助功能？（核心路径 = 主流程必经、出错影响面大；辅助 = 边缘功能、出错影响小）→ 核心/高风险模块必须列异常与边界场景表；辅助模块可以略写或合并到验收标准里。

不要因为某个模块"看起来简单"就跳过接口字段级描述——字段级精度是所有模块的底线，三个判断只影响"要不要额外画图/列表"，不影响"接口契约写多细"。

Step 3：生成跨模块整体架构图

在详细设计之前，先画一张图，让三方在看任何模块细节之前，先对"系统长什么样"有共同认知。这张图应该展示：

• 模块清单（每个模块一个节点）
• 模块之间的调用/依赖关系（谁调用谁，是同步调用还是异步消息）
• 关键的外部依赖（数据库、第三方服务、消息队列等），如果 PRD 或上下文中提到了

用 Mermaid 画（graph TD 或 flowchart TD 即可，不强制要求 SVG——这张图的目的是让人一眼看清模块关系，Mermaid 在 Markdown 里能直接渲染,足够清楚)。如果模块数量只有一个（PRD 本身就是单模块的小功能），这张图可以简化成"该模块与外部系统的交互图"，不需要强行画一个只有一个节点的"架构图"。

Step 4：逐模块详细设计

对每个模块，使用 references/module-template.md 中的模板展开。模板里每个章节都标注了"必选"还是"按 Step 2 判断条件选填"，照着填即可，不要自己再发明新的章节结构——三份不同模块的文档如果结构不一致，reviewer 和测试者要重新适应格式,这本身就是一种隐性成本。

如果模块在 Step 2 判断里需要状态转换图,写完图之后要立刻反过来检查：图里每一条转换箭头,触发它的机制是什么,这个机制是否已经在文档别处写清楚了? 状态图本身只表达"状态A会变成状态B",不表达"是什么动作让它变成的"——这一步很容易漏,而且漏的方式不止一种：

• 用户主动操作触发的转换(比如"扫码取件成功"),需要对应一个接口契约,不能只在图里画一条线就当作设计完成。
• 外部系统回调触发的转换(比如"支付成功"由支付网关回调驱动),需要写一个接收回调的接口,不能只在异常场景表里写"回调丢失怎么办"而忘了写"回调本身怎么接收"。
• 系统定时任务/超时触发的转换(比如"超时未支付自动取消"),需要在异常场景表或文字里写清楚检测机制(多久扫描一次、谁来触发),并且同一份文档里所有定时触发的转换,详细程度要彼此一致——如果"待取件超时"写了扫描频率,"待支付超时"却什么都没写,这种不一致比完全没写更容易让测试者误以为"没写的那个就是不需要测的"。

简单说：状态图回答"会发生什么",文档其余部分要回答"是什么让它发生的"，这两半合起来才是完整设计，少了任何一半,测试者都没法设计出对应的测试用例。

写接口契约时心里要绷住一根弦：测试者要靠这一段直接写出测试用例，不能再来问你"这个参数必填吗""失败了返回什么"。所以每个接口最低限度要写清楚：

• 请求方式与路径（如果 PRD/上下文有技术栈线索就用真实路径风格，没有就用语义化占位路径并注明"待开发阶段确认实际路由"）
• 请求参数表：参数名、类型、是否必填、默认值、约束规则（长度/格式/取值范围）
• 响应结构：成功时的字段、字段类型、字段含义
• 错误码表：至少覆盖参数校验失败、权限不足、资源不存在、业务规则冲突这几类常见错误,每类给出错误码和错误信息示例
• 幂等性/并发说明：如果这个接口存在重复提交或并发修改的风险，要写清楚处理策略；如果不存在这个风险也可以一句话说明"无并发冲突风险，因为xxx"，避免测试者花时间纠结一个其实不存在的场景

写到任何具体数值（超时时长、重试次数、限流阈值、字符长度上限等）时，先问自己这个数字是从 PRD 原文来的，还是自己为了让文档显得完整而现场编的。 如果是编的——这是写设计文档时最容易不知不觉犯的错误，因为一个写了具体数字的句子读起来就是比一个写"[待确认]"的句子更像"专业文档"，但这种专业感是假的，会让测试者以为这是经过确认的业务规则去设计用例——必须显式标注 [待确认]，并汇总进文档末尾的待确认事项表，不能让它看起来和 PRD 明确给出的数字一样确定。

但不要因此变得过度保守、把所有没在 PRD 里逐字出现的数字都标成 [待确认]——那样整份文档会布满标注,反而失去重点。区分标准是：这个数字改变的是"业务规则"还是"工程实现细节"。"订单超过多久算用户放弃不付款了"是业务规则,数字错了会让产品行为本身不对,必须标注;"取件码用几位数字""错误信息的具体文案""重试间隔用几秒"这类纯工程实现选择,只要给出合理默认值并保持内部一致即可，不需要标注，这正是 PRD 场景 B 里"能推断的字段直接写清楚"对应的那一类——架构师的工作本身就包含做这类工程默认值决策，不是每一个都要退回去问产品经理。判断标准很简单：能不能在 PRD 原文里指出这个数字的出处，且这个数字一旦改变会不会让"系统该做什么"本身发生变化；两者都满足，就是业务规则,必须标注;否则是实现细节,正常写,不需要标注。

Step 5：汇总全局验收检查清单

文档最后要有一份独立的验收检查清单章节,把前面分散在各模块里的验收规则汇总成可以逐项打钩的列表，分两层：

• 按模块汇总：每个模块的关键验收项罗列出来，方便 reviewer 按模块过一遍
• 跨模块的全局项：性能、安全、兼容性等非功能需求的验收项,这些往往不属于任何单一模块,容易被遗漏

这份清单不是重复前文,而是前文的"可执行索引"——reviewer 不需要重新读一遍长文档找验收点,扫一眼清单就知道该测什么、该 review 什么。

文档结构与输出

完整模板见 references/module-template.md（文档头部、整体架构图、每个模块章节的详细结构、全局验收清单,一份文件包含全部骨架,按顺序填充即可）。

文件命名：[product-name-en]-tech-design.md（英文小写,连字符分隔,与同源 PRD 文件名保持可关联,比如 PRD 是 smart-order-assistant-prd.md，设计文档就是 smart-order-assistant-tech-design.md）。

输出到当前项目的 markdown/ 目录,与 write-prd/write-brd 等同源 skill 保持一致的输出位置约定,方便用户在同一个目录里管理一整套产品文档。

特殊场景处理

场景 A：用户没有现成 PRD，只描述了功能需求

可以直接基于描述展开,但要在文档开头注明"本设计文档基于用户口头描述生成,未经过正式 PRD 评审,部分边界条件为推断,标注 [待确认]"。不要因为没有正式 PRD 就降低精度要求——精度要求始终成立,只是来源不同。

场景 B：PRD 信息不足以支撑字段级设计

不要编造看起来精确但其实是瞎猜的字段值(比如凭空编一个"用户等级 1-5"的枚举,而 PRD 根本没提过等级体系)。正确做法：

1. 先基于 PRD 里明确给出的业务规则,把能推断的字段写清楚
2. 对于推断不出来、又必须有值才能让接口契约完整的字段,用 [待确认：原因] 标注,并在文档末尾汇总一份"开发前需确认事项清单"
3. 不要为了让文档看起来完整就跳过标注、直接编一个合理但无依据的值——这种"看起来精确"比"明确说不知道"更危险,会让测试者基于错误前提设计用例

场景 C：PRD 涉及多个完全独立、几乎无交互的模块

如果模块之间确实没有调用/依赖关系(比如一个 PRD 里包含"用户反馈"和"系统公告"两个互不相关的功能),Step 3 的架构图可以简化为并列展示,不用强行画出虚构的依赖箭头。如实反映"无依赖"也是一种有效信息——能让 reviewer 知道这两个模块可以完全独立并行开发和测试。

场景 D：PRD 本身就是单一小功能,只有一个模块

跳过"模块划分"的讨论,Step 3 的架构图改为"该功能与外部系统/已有功能的交互图"。其余步骤照常,字段级精度不因为模块少就降低。

场景 E：用户要求"先出个简版,细节后面再补"

可以先交付架构图 + 各模块的接口契约骨架(请求/响应字段名和类型,暂不展开每个错误码),但要在文档里用 [待补充] 标注哪些部分是简化的,并在交付时明确告知用户"这是简版,XX部分需要进一步细化才能交付测试"——不要让简版看起来像是完整版,否则测试者会基于不完整的契约开始工作。

写作质量自检

写完后过一遍,这些是最容易漏的地方：

• 每个 Must/Should Have 功能点是否都能在文档里找到对应的接口契约或行为描述？(漏掉一个,开发就会漏做一个)
• 状态转换图里的每一条转换箭头,触发它的机制是否都能在文档别处找到?(用户操作触发的要有对应接口;外部回调触发的要有接收回调的接口;定时/超时触发的要写清楚检测机制。最容易漏的不是"完全没写",而是"写了一部分"——比如只写了"待取件超时"的扫描机制,却忘了同样需要写"待支付超时"的扫描机制,这种厚此薄彼比完全没写更容易误导测试者)
• 每个接口的错误码是否覆盖了"用户能想到的失败方式",而不只是"开发顺手写的那几种"？
• 状态机模块是否把所有状态之间的合法/非法转换都说清楚了？(测试者最容易拿"非法转换"做反例用例)
• 核心模块的异常场景表是否包含了空值、超限、并发、权限不足这几类通用风险,而不只是业务逻辑本身的分支？
• 全局验收清单里的每一项,是否都能在前文找到对应的详细规则?(清单不能凌空出现没有依据的验收项)
• 是否有"看起来精确但其实是编出来的"业务规则数值?(超时时长、限额这类改变系统行为本身的数字,如果 PRD 没给依据,必须改成 [待确认] 标注;但取件码位数、错误文案这类工程实现细节,不必每个都标注,正常给出合理默认值即可)