给 Agent 加一条验收规则:新属性同步进 Storybook
文章建议把 Storybook 的参数、控件和属性文档更新纳入新增公开组件属性的同一个 PR。枚举属性的每个取值都应能通过控件或独立示例查看,并清楚标出默认状态。
AI 深度解读
AI 编程助手给 Notice 加了 tone,组件能渲染,测试也覆盖了两种色调,但设计师打开 Storybook,还是只能看到默认状态,文档表里也找不到这个属性。作者把这种 PR 视为没做完:如果团队在 Storybook 里做设计评审和 QA,新增的公开属性就该在同一个 PR 里让人看得见、试得到。
这个做法可以直接写进任务提示词,也可以用来验收 PR。评审时打开 Storybook,切一遍公开选项,比只看组件代码和测试 diff 更容易发现这种遗漏。
为什么组件改完了,Storybook 还是旧的
「加一个 tone 属性」很容易被理解成只改类型和 JSX。故事文件在另一处,里面的 args 可能是最初生成后就没动过的。作者的观察是,提示词没点名时,助手往往会把这些文件当成任务范围之外的内容。
Notice 的 tone 有 info、warning、danger 三个值。测试覆盖其中两种,说明团队验证了部分组件行为。设计评审还要能切换这三个状态、看出默认值,QA 也得有入口复现某个状态。只渲染默认值的 story 满足不了这些需求。
同一个 PR 要把哪些内容补齐
作者的规则是,新增或修改公开组件属性时,同步更新 story 的 args、控件和简短说明,并检查文档生成(docgen)的结果。每个枚举值至少有一个可见入口,可以用控件、命名 story,或沿用目录里两者并用的写法。默认值要容易识别,内部 flag 则留在组件内部。
下面这段提示词把改动范围和验收要求一并交给助手。
If you add or change a public component prop, update the Storybook story in the same PR:
add the arg, the control, and a short description.
Show each enum value at least once.
Follow the existing CSF pattern in this folder. Do not invent a new story format.
第三行要求逐个展示枚举值。原文举了一个反例:控件已经加上,但四个枚举值只露出两个。最后一行约束落地方式。如果现有目录用的是 CSF3、autodocs 或独立的 argTypes 文件,就明确告诉助手沿用哪套写法,避免引入风格不一致的 .stories.tsx。发任务时可以把当前 story 和组件的 props 类型一起贴上,评审时再打开 story 确认实际效果。
视觉属性和回调属性怎么验收
tone、size、density 这类视觉属性,适合用矩阵或一组命名 story 做并排比较。评审者可以直接看到各状态的差异,省去在默认 story 里逐个切换单选控件。按目录已有的方式选一种即可,单个 prop 没必要同时加矩阵和新的 MDX 页面。
onDismiss、onChange 这类回调需要一个能触发的交互。可以在 args 里提供 action(),也可以用一个小型包装 story 记录调用。作者特别提醒,新增必填回调后,如果 story 漏传,组件触发它时可能报错,影响目录里的预览和操作。
我的判断
我认同把 Storybook 更新写进公开属性的验收条件,前提是设计师和 QA 确实用它评审组件。作者给的是工作经验,没有提供加规则前后的遗漏率、评审耗时,或不同提示词的对照数据。能直接检查的是这个 PR 有没有把公开状态和交互交付完整。
控件适合临时试组合,命名 story 更方便复查某个固定状态。autodocs 如果已经能生成类型和说明,可以直接核对生成的表格,省去手写一份文档。至于评审者能否切到所有状态、触发必填回调,仍然得打开 story 看。
能拿来做什么
- 让 AI 修改组件的公开 props 时,把 props 类型和现有 story 一起交给它,要求在同一个 PR 里更新
args、控件和说明。 - 评审
Notice一类组件时,打开 Storybook 逐项确认每个枚举值可达、默认值清楚,再检查autodocs里的类型和描述。 - 给组件新增必填回调时,在 story 里接好
action()或记录调用的包装组件,并实际操作一次,确认能触发回调。