演示审核流程 是做什么的?
测试和代码审查只能证明机制的正确性。它们无法告诉你菜单位置不对、关闭按钮有闪烁、或者图标偏了2像素——只有用户能发现这些问题。因此,任何“看起来或操作起来”的变更,其设计方式是:在编写任何产品代码之前,先构建一个用户按功能批准的可工作演示(Demo),并且只有当用户在实际应用中接受后,该变更才算完成。一个审核板(Review Board,一个带有共享数据库的Artifact页面)会追踪每个功能,状态分为六个阶段。
项目配置: .claude/demo-board.md(审核板URL、各区域参考应用、需要检查的宽度、实时应用以及该应用是否包含真实数据、工作区副本端口、门命令、规范文件)。如果缺失→首先创建审核板:references/board-setup.md。
选择路径
- 改变外观、位置或操作方式 → 使用此流程。无论变更大小或期限如何,均无例外。
- 恢复规范或已批准的演示中已定义的行为(如崩溃、错误数据、溢出、回归) → 直接通过TDD修复,无需演示。告知用户你判断其属于哪个路径。
- 已发布(shipped)的审核板项目上报告的错误 → 返回
porting状态,修复,在实时环境中检查,然后设置为shipped。修复若改变了外观 → 重新进行一轮演示。
流程
- 参考优先。 针对该区域,查找用户已知的应用(配置中列出了它们)。记录控件的位置、每个按键功能、包括退出在内的动效。只有在给出明确理由时才能偏离。在选项之间取舍时,需要对模拟用户进行调查,但这绝不能取代参考应用。
- 测量真实UI。 以只读方式,在用户指定的宽度下截图截取变更所涉及的已发布界面,并测量间距、尺寸、对齐方式。在测量结果的基础上进行设计。
- 构建演示 作为
feat()条目,使其真正可用:支持点击、按键、包括退出在内的动效、浅色+深色主题、窄宽度。→references/add-feature.md - 记录它: 添加一个
changes行和features/<id>→ 状态设为review。 - 移交并停止。 提供链接 + 需要检查的内容。在该条目被
approved(批准)之前,不得编写任何产品代码。“除非你反对,否则我就继续”不是批准。如果无法在截止日期前获得批准,向用户提供当前已发布的功能——切勿提前开发。 - 每次UI会话开始时以及用户表示已审查时,获取决策: 读取
features。approved→ 第7步。changes→note是请求 → 第3步。用户说已批准但数据库显示不符 → 点击未保存:告知用户并为其设置。 - 立即移植(Port) — 用户不审查计划;他们的验收标准是第9步。设置状态为
porting;根据references/port-brief.md提供简要说明。每个文件区域只有一个移植代理。迁移在工作区副本上运行;只有在获得明确批准并有备份时,才能在实时数据上运行。 - 发布(Ship) 仅在拥有实时证据(测量数据、每帧动效、双主题、用户指定的宽度)时进行:状态设为
shipped+ 添加一个changes行 + 需要检查的内容。 - 已验证(Verified)是由用户决定的 — 用户点击“接受”,或者用户在聊天中确认该特定项目已被接受(然后你设置状态)。模糊的“看起来不错”→ 询问具体是哪些项目。切勿凭自己的判断。
关于状态、由谁设置、数据库模式、写入操作 → references/lifecycle.md。关于与头脑风暴、编写计划、子代理驱动开发、验证和分支完成的交接 → references/superpowers-integration.md。
实时环境检查安全
在包含真实数据的实时应用上:以只读方式浏览,仅点击完全匹配的标签,切勿在该环境中进行删除/移除/编辑操作——任何会更改数据的检查都应在工作区副本上进行。
合理化借口
| 想法 | 现实 |
|---|---|
| “这个改动很小 / 很容易撤销” | 大小不是标准;是否影响“看”或“操作”才是。小的UI改动正是位置容易出错的地方。 |
| “明天就截止了” | 一轮演示只需几分钟;一个错误的位置被发布到演示中会付出更大代价。保持流程,说明时间线。 |
| “我会给你看截图,如果你不反对我就继续” | 沉默不代表批准,且截图的已完成构建并非用户可操作的演示。 |
| “从第一性原理看,正确位置是显而易见的” | 请明确指出参考应用。“用户在哪里看”正是那些难以找到的开关被发布出去的原因。 |
| “测试、审查和构建都通过了,所以完成了” | 那只是 porting 完成。shipped 需要实时证据;verified 需要用户确认。 |
| “'我猜还行'意味着接受了” | 接受是按项目来的。请询问具体是哪些。 |
| “他们反正会批准的;我提前开发算了,好赶截止日期” | 未经批准的代码就是白费功夫。向用户展示今天能发布哪些功能;一旦他们批准,立即移植。 |
| “我要发明一个更清晰的状态” | 只有六个状态;页面和用户都能识别这些。 |
| “为了省时间,把移植和演示一起做” | 只有 approved 的项目才能编写产品代码。 |
红旗警告——立即停止
- 在演示未展示设计之前,就打开产品组件。
- 设计没有命名参考应用,或没有测量真实UI。
- 未提供实时证据就设置为
shipped;未经用户对该项目的明确确认就设置为verified。 - 在包含真实数据的应用中点击“删除/移除/保存”。
- 两个移植代理操作同一组文件;在实时数据上运行迁移。