第一次写 PRD，写出来的不该是文档

你在构思一个新产品、要写第一份 PRD 的时候，用这个 skill。 产出不是一份文档，是一份交互式 PRD，三样缺一不可：

能点的交互: 桌面 1440 + H5 375 并排、场景可切、状态穷举、批注可回传
旁边带解释: 每个界面区块配一段「为什么这样设计」（.why）
产品逻辑: 场景怎么串、状态怎么变、数据从哪来 —— 写在稿子里，不在别处

标准形态是 design/mockups/wb-redesign/——十三轮迭代、六轮复审的实例。一份合格的交互式 PRD：打开就能点，点到哪儿都看得到「为什么」。

事实层已验证出处 = skill 自身 29 个文件 7868 行 + 本轮命令输出，逐条可查

需求层来自你的原话「产品第一次写 PRD 时输出交互式 PRD，交互之外要有解释和产品逻辑」——2026-09-08 定位重写的原文

设计层就是这一页单栏阅读稿（--kind explainer），零缩放、无设备框

验收层见文末做不到的事单列；闸门查不到的部分明写

定位

什么时候用，产出长什么样

一个场景：构思新产品，第一次写 PRD。 别的用法（给现成 HTML 加批注、核对批注改完没）是附带能力，不是主线。

产出是一个 HTML 目录，五个页签 原型（主体：逐场景可点界面 + 内联 .why）· 图鉴（状态穷举样张）· 层间对照（需求↔设计↔事实逐条对得上吗）· 待澄清（说不准的列这里，不编）· 事实基线（每个界面数字的真实字段出处）。

侧栏只有三样：标题、五页签、场景列表 工具自己的状态只允许出现在顶部声明条一处。这条是付过学费的：曾往侧栏塞过 128px 的四层彩色指示器，被用户点名「垃圾信息」—— 参照物 wb-redesign 的侧栏 85% 高度给内容，工具的元信息不许抢产品的位置。现在 e2e 反向断言它不存在。

灵魂

.why：解释长在界面旁边

交互式 PRD 和「一堆截图」的区别就在这里。 每个界面区块旁边一段 .why，写为什么这样设计——取舍、口径、诚实降级，不是复述界面长什么样。

⏳ 运行中 · 已记录 6 步 · 本回合 2m14s

这就是 .why 该有的样子（取自 wb-redesign 原文）： 「不写『6 步』而写『已记录 6 步』——那是已经收到的活动条数，不是这轮的总步数，总步数系统给不出来。」它在为一个口径决定辩护，不是在描述上面那行字。

算 .why

「转圈不上语义色——在途既不是好也不是坏，只有未读点有颜色」
「答案写结论不写日志——过程叙述属于过程块，不占对话主体」
「通知不是对话，所以不进气泡——一条横条，读完即走」

不算 .why

「这里有一个状态图标」（描述界面）
「点击按钮后弹出面板」（复述交互）
「采用卡片式布局，简洁美观」（形容词，没有取舍）

判据一句话：把 .why 念出来。在描述界面 → 删掉重写；在为一个决定辩护（为什么不是 X 而是 Y）→ 对了。机器兜底：prototype-verify 数正文里的 .why，少于场景数报红—— 有界面没解释不是 PRD，是一堆截图。

流程

怎么做：从产品 idea 到交互式 PRD

先聊清楚，再切场景，然后逐屏「界面 + why」一起写。 默认不扫描任何目录——要扫，范围由用户划。

这张图回答：产品逻辑从哪一步开始进稿子。 文字流程读起来像「先画完界面最后补解释」，图上看得清 .why 和界面是同一步的两个出口——解释不是补出来的，是画的时候一起写的；「说不准的」走虚线岔路进待澄清，不许编。

主干步骤 .why 与闸门账本 / 图鉴说不准 → 待澄清

# 起骨架（--kind 必选，交互式 PRD 用 prototype）
node .claude/skills/prototype-review/bin/prototype-init.mjs design/mockups/<name> --kind prototype --title "标题"
# 交付前必跑：静态闸门 + 真浏览器行为闸门
node .claude/skills/prototype-review/bin/prototype-verify.mjs design/mockups/<name>
node .claude/skills/prototype-review/bin/prototype-e2e.mjs design/mockups/<name>

起手

先选形态，再谈别的

形态选错，后面所有样式问题都是它的连带。 写 PRD 用 prototype；解释一套说法（比如本页）才用 explainer。

这张图回答：从「要做一份稿子」到「闸门查什么」，中间有几个岔路。 三个判断点串在一起——选形态、认档位、认自产/外来。文字里它们分散在三节，图上是一条链，而且能看出 虚线出口都是「不拦」或「跳过」。

判断点有程序在查直接报错不拦 / 跳过

--kind 没有默认值，不给就报错并打印判据。刻意的：之前只有 prototype 一种，谁跑 init 都拿到它，用它写解释稿出来是「双设备框 + 62% 缩放 + 一堆灰底卡片」。给默认值等于让下一个人继续踩。

背后的账

四层账本：防虚构，不抢戏

每屏背后记一笔账：这个数字来自哪个真实字段、这条需求是给的还是猜的。 账本自动汇成顶部一条声明条——四层齐备时只是一根细线，缺层时才醒目。

这张图回答：为什么缺一层不是错，不声明才是错。 四层位置固定、走法自由；只走一层时其余三层是空的，产物可信度完全不同，所以缺哪层必须在稿子顶部明写。

事实层需求层设计层验收层入场姿势

这套账是付过学费的：首版稿子含 14 类虚构字段 （排队位置、单步耗时、上传百分比…全是编的），判 RETURN，前后 13 轮才收干净。 当时顶部要是写着「事实层未验证」，它根本不会被当成能开发的东西交出去。 逆推出来的需求一律标 provenance: "reverse"——那是猜测，天然待确认。

闸门

机器闸门 + 一道只能靠人

静态闸门（填满的完整档实测约 107 条）+ 行为闸门（43 条断言）+ 人眼。 第三道没有任何程序——这不是缺陷说明，是使用说明。

prototype-verify · 静态 四层账本查账 · .why 少于场景数报红 · 颜色必须出自项目 token （凭空配色 / 给基色自配透明度，分别点名）· 引用了没人定义的变量 · token 真被引用 · CSS 分段纪律。查不到行为——属性写对了但点了没反应，它不知道。

prototype-e2e · 行为（真浏览器） 点了真的变了没 · 零 pageerror · 三档视口无溢出 · grid 行归属 · 内容未被压窄（<120px 的文字块报红——溢出和行数都测不出的那类坏）· 并排两框同比例同一行 · 侧栏没有四层指示器（反向断言，别加回来）。 查不到内容对不对——它不知道你的字段是不是编的。

人眼 · 零程序 形态选对没 · 内容是不是编的 · .why 写的是取舍还是废话。 多次「断言全绿但东西是坏的」都是截图看出来的—— 所以交付两步：① 贴断言输出 ② 自己看一眼图，第二步不能省。

已固化

踩过并且现在由机器盯着的坑

每条都不报错——代码看着对、控制台干净、东西就是坏的。

颜色是「取一个差不多的」出来的 三份稿子三种怪色（一片绿、乱橙），根因不是审美，是没有唯一出处。现在闸门只认识项目 token 里的颜色；图表的 hex 由脚本从 token 算出（目测取的六个值里四个弱底全错）。

内容被压窄，而溢出是 0px 会话区被压到 77px、中文逐字竖排，两套闸门 147 项全过—— min-width:0 让子项无限压缩，压窄不产生溢出。根因是 @container 不增加特异性：断点条件命中了，声明被桌面规则压住。

token 文件「存在」≠「被加载」 一份从未被 index.html 引用的 token 文件一路绿灯，整份稿子跑的是自建的平行体系。现在查三层：文件在 → 被引用 → 在 app.css 之前。

注释里提到 ≠ 实例存在 同类错犯过四次：按字样切分命中说明文字、按选择器名切分切在注释上（暗色块整个变成浅色值，不崩不报）、数 .why 把注释里的写法示例数进去。现在所有解析先剥注释。

写死一个键，导致线上串台 旧数据迁移写死成某一份稿子的键，而 localStorage 按域名共享，一份稿子上显示了另一份的批注。

computed style 说有 ≠ 渲染出来了 SVG 元素上 getComputedStyle(el,"::after").content 照样返回 "1"，但 SVG 不生成伪元素盒，图上什么都没有。只有截图才定论。

验收层

做不到的，单列出来

把做不了的划掉，比把能做的说满更有用。

判断 .why 写的是取舍还是废话（只数数量）判断内容是不是编的（人眼 + 账本交叉）判断形态选对没（人眼）抓 flex 换行造成的错位（只覆盖 grid）跨 project root 被别的目录调用（分发方案另案在做）保证稿子不出错（只保证错误能被精确指出）

最后一条是这套东西的定位：它不保证不出错。首版照这套模式产出，评价仍然是「全错的离谱」——但正因为有状态穷举和批注定位，用户能在两小时内给出 24 条带精确坐标的意见，而不是只能说「感觉不对」。它把「模糊的不满」变成「可逐条执行的修改单」。

skill 体量: 29 个文件 · 7868 行
命令: 6 个（init / verify / e2e / shot / sync-tokens / gen-diagram-palette）
细则: 6 份 references（含入口三个被否版本的留档）
骨架: 2 种（prototype = 交互式 PRD / explainer = 说明稿）
静态闸门: 空骨架实跑 40 条 · 填满的完整档约 107 条
行为断言: 43 条（本稿骨架实测 42/43，唯一失败是空骨架仅 1 场景）
定位重写: 2026-09-08：「四层工作台」→「交互式 PRD」（SKILL.md 370→140 行）

右下角可以点「批注」，指着任意一段提意见——导出的 Markdown 带精确定位，配 prototype-shot 还能复原当时状态截图。