← ClaudeAtlas

product-doc-standardlisted

按四段式规范撰写产品概述文档(什么是 X / 产品架构 / 功能特性 / 应用场景与用户旅程),含写作语体规则、分层产品架构图画法、自包含 HTML 产出方式与验证清单。当用户要求"写产品文档""写个产品概述""画产品架构图""整理功能特性""把这个产品讲清楚给研发看",或要对已有产品文档做改写、精简、重排结构时,务必使用这个技能。用户提到"参考阿里云那种产品文档""像 IMM/StarRocks 那样的架构图"时同样适用。
skyhahalife-11/pm-skill-pack · ★ 0 · AI & Automation · score 67
Install: claude install-skill skyhahalife-11/pm-skill-pack
# 产品文档规范 这份规范是一次真实迭代打磨出来的结果:一份产品文档改了十几轮,用户几乎每一轮都在纠正同一类问题——啰嗦、重复、术语让研发看不懂、架构图线太乱。下面的规则每一条都对应一次实际返工,照着走能省掉那些来回。 下面「四段式骨架」一节就是最终定稿的结构,直接照它搭章节;语体规则见「写作语体」和「三个高频句式」,那几句关键句式可以直接套。 ## 什么时候用别的东西 如果任务是**先校准读者和深度**(用户还没说清给谁看、要总览还是规格),先处理那一步;这份规范默认的读者是**研发和跨部门同事**,深度是**建立整体理解的产品概述**,不落到交互细节和验收标准。如果用户要的是模块级设计文档或 PRD,这份骨架不适用。 ## 四段式骨架 严格按这个顺序,不要自创章节: ``` 1. 什么是 X - 定义句(一段) - 产品概述(一句话枚举能力) - 前置概念(表格) 2. 产品架构 - 分层结构说明 + 架构图 - 逐层介绍(每层一个三级标题) - 设计原则(放本节最后) 3. 功能特性 - 一张三列表格 4. 应用场景与用户旅程 - 应用场景(若干加粗小标题段落) - 关键旅程(时序图,每条一个三级标题) ``` **架构为什么排在功能特性前面**:读者得先知道系统分几层、每层管什么,才能理解功能表里那几十条分别归谁。反过来先看功能表,会变成一堆记不住的条目。 **设计原则为什么放在架构节最后而不是开头**:它是对前面分层的提炼,放开头会让读者在还不知道系统长什么样的时候先读一堆抽象取舍。 ## 写作语体 **陈述式、书面、精确。** 不打比方、不用口语连接词、不写故事化举例。"对新人友好"从来不等于"语言可以随意"——可及性靠补背景和补边界说明来实现,不靠让语言变松。 **分点作答。** 大段连续文字读者抓不住重点。凡是能枚举的(能力、判断类型、数据分组),一律先用一句话点出"有几块、分别叫什么",再逐条 bullet。 **不用架构行话当功能名。** "创建域""组织域""状态呈现域"这类 DDD 术语,研发看文档时还要在脑子里翻译一遍,而且它不提供任何额外信息。直接叫"文档创建""页面树组织""状态展示"。如果要改名,**六份文档一起改**,不要只改架构图留下不一致。 **括号和补充说明里用文档自己定义过的正式术语,不用口语化描述。** - 反例:`AI 写作(起草、改写、能自己找资料)` - 正例:`AI 写作(生成初稿、选区改写、知识检索)` 后者的每个词都能在前置概念表或功能特性表里查到,这就是"严谨"的具体含义。 **每一节不要重复前一节说过的。** 最高频的浪费是产品概述把定义句里的受众和基座又说一遍。定义句已经交代过"面向谁""建立在什么之上",概述就只留能力枚举。 ## 三个高频句式 直接套用,不要重新发明: **定义句**(第 1 节开头,一段) > [产品] 是 [归属] 的 [品类],面向 [谁],为 [什么对象] 提供从 [起点] 到 [终点] 的一站式能力。它建立在 [基座] 之上,由 [基座] 提供 [什么基础],[产品] 在其上叠加 [什么]。 **概述句**(产品概述,就一句) > [产品] 的能力分 N 块:**A**(术语1、术语2、术语3)、**B**(…)、**C**(…)。 括号里固定三个并列名词,句式整齐。整段不超过三行。 **层 / 模块介绍**(架构节里每一层,功能特性之外的任何"介绍某一