williamliu.ai
EN中文
← 返回文章

Claude Design 原型变规格，仍漏 20 处

6 篇系列的第 2 篇：设计原型带着品味、样例数据，也自带一套冲突裁决方式。我如何把原型变成智能体可以据此构建的规格文档，以及为何所有关卡通过后，仍有 20 处没有对齐设计。

10 分钟读完
  • Claude Design
  • 编码智能体
  • 规格文档
  • AI 工程

《用智能体重建 williamliu.ai》6 篇系列的第 2 篇。请从总览开始阅读。

要点

  • 🎨 Claude Design 的设计交付包是一份带样例数据、可以运行的样稿；其中有 8 项机制绝不能进入生产环境。
  • ⚖️ 开始构建前，先决定发生冲突时以谁为准；我的项目需要一张包含 13 行的冲突清单。
  • 🔏 用哈希记录设计文件：我的第一轮研究审查了一个过期副本。
  • 🚫 原型虚构了关于我的事实；规格文档（spec）只允许使用我能核实的内容。
  • 🧪 所有构建关卡都通过了，审计仍发现 20 处没有对齐设计；解决这些问题用了 9 轮修复。
  • 📐 一个选择可以完全符合规格文档，却在没人检查过的屏幕宽度上，或面对比读者实际会看到的内容更短的样例时，看起来不对。

设计原型告诉你网站应当给人什么感受；当原型、自带文档和真实内容彼此矛盾时，规格文档告诉智能体究竟要构建什么。 我在 Claude Design 中设计了新版 williamliu.ai。设计交付包很擅长前一件事，对后一件事却要么沉默，要么给出错误答案。本文讲的是从“设计看起来对了”到“智能体无需猜测就能实现”之间的工作。

4 张未经裁剪、按统一比例呈现的 Claude Design 原型截图，均为原型的中文界面：以最新播客为中心的首页、按系列组织的播客索引、带封面占位图的单集页，以及文章页。
fig 01 4 张未经裁剪、按统一比例呈现的 Claude Design 原型截图，均为原型的中文界面：以最新播客为中心的首页、按系列组织的播客索引、带封面占位图的单集页，以及文章页。
fig 02 Claude Design 原型动态演示：90 秒无声录屏，依次展示首页、带动态波形播放器的单集页、项目页和中文页面。

博客当时还不支持内嵌视频，因此网站专门为这段演示构建了就地播放的视频播放器。旧版渲染器仍会把海报显示为链接。

从设计交付包到规格文档：设计压缩包中的 README、设计 token、截图和可运行原型，共同进入一套 4 层优先级顺序——我的决定优先，其次是 README，再次是在 README 未说明处采用 token、截图和原型 CSS；真实内容始终优先于样例数据——最终形成智能体据以构建的规格文档。
fig 03 从设计交付包到规格文档：设计压缩包中的 README、设计 token、截图和可运行原型，共同进入一套 4 层优先级顺序——我的决定优先，其次是 README，再次是在 README 未说明处采用 token、截图和原型 CSS；真实内容始终优先于样例数据——最终形成智能体据以构建的规格文档。

🎨 设计交付包是什么，什么绝不能上线

设计交付包是一份覆盖整个网站、可以运行的样稿，其中大部分机制只是为了让样稿运转，并不应该部署。 Claude Design 导出了一个 ZIP，内含书面 README、一份定义颜色、字体和间距的 tokens.json、10 张参考截图，以及一个可以在浏览器中打开的原型。这个原型用 Babel 在页面中编译 React，内容硬编码在一个数据文件里。

我的网站是由 Python 脚本构建的静态网站，包含 feed、定时发布，以及其他系统依赖的发布流水线。因此，在编写任何代码之前，规格文档先列明了绝不能上线的内容：

  • 在浏览器中编译 React，以及客户端 hash 路由。
  • 硬编码的样例数据文件。
  • 通过原地重写数据来切换语言。
  • 模拟音频播放。
  • 设计微调面板和图片拖放占位框。
  • 手机边框预览工具。

除此以外，外观、布局和交互都必须在现有架构上重新实现。规格文档的第一条规则是：改版只改变呈现方式，不改变文章和单集的存储、日期、定时发布或 feed 生成方式。

⚖️ 开始构建前，先决定以谁为准

设计交付包内部有 13 处自相矛盾，自带说明还要求以原型为准；我在第一行代码出现前推翻了这条规则。 交付包的智能体说明写着："When the README and the prototype disagree, the prototype wins."（README 与原型冲突时，以原型为准。）但 README 承载的是明确决定：断点、无障碍、容器宽度和中文要求。原型编码的则是样稿选择，其中一些与 README 冲突。

所以我在第一天批准了一套优先级顺序。我的明确决定排第一，其次是 README；README 没有说明时，再参考 token、截图和原型样式。真实生产内容永远优先于样例数据。规格文档随后用冲突清单解决每个已知矛盾，每项一行：

13 项冲突中的 5 项：首页标题字号，README 的 52 px 对原型的 74 px；三栏布局断点，640 px 对 900 px；长文正文字体，README 的衬线字体对原型的无衬线字体；容器宽度，README 的 1180 px 对原型的 980 px；语言切换，服务端渲染中文页面对仅客户端切换。每一项都采用 README 的选择。
fig 04 13 项冲突中的 5 项：首页标题字号，README 的 52 px 对原型的 74 px；三栏布局断点，640 px 对 900 px；长文正文字体，README 的衬线字体对原型的无衬线字体；容器宽度，README 的 1180 px 对原型的 980 px；语言切换，服务端渲染中文页面对仅客户端切换。每一项都采用 README 的选择。

这张清单做了两件事。它避免每个智能体重复争论同一个问题，也给审查者提供了检查依据。审查者看到 52 像素的标题时，可以查到 52 已经是明确决定，然后继续往下审查。

这套优先级顺序，也在这里具体回答了《谁拥有智能体这个难题》（Hard Question of Who Owns the Agent）提出的问题：谁设定顺序，谁就决定智能体执行谁的默认规则。

🔏 先给设计文件留指纹

第一轮研究分析了错误的设计文件，那个 "sound"（可靠）结论只能作废。 我的机器上有两份设计交付包：主目录里有一份 96 KB 的压缩包，网站仓库里有一份 394 KB 的压缩包。研究从过期的那份开始。另一次独立审查在规格文档草稿中发现 3 个严重缺口，最主要的是缺少中文行为。过期压缩包根本没有中文文件，当前版本则有。

修复的是流程。规格文档现在会用文件大小和 SHA-256 哈希指定唯一权威压缩包，并声明另一份已经过期。研究记录也得到修订，明确此前的结论无效。规格文档从 394 行增至 500 多行才通过审查。记录哈希很简单；没有记录它，却浪费了一整轮研究和审查。

🚫 原型虚构了关于我的事实

样稿里的样例数据看起来像我的网站，却包含虚假陈述，所以规格文档只允许采用已经存在且经我批准的内容。 原型的项目页把 fidx 写成一个拥有 "1.2k" star 的 Rust 项目。fidx 实际用 Python 编写，star 数则完全是虚构的。“关于”页这样描述我的职业经历："Earlier work spans applied ML research, large-scale training, and inference systems."（我早期的工作横跨应用机器学习研究、大规模训练和推理系统。）这句话不是我写的。页面还列出第 4 个项目 kvprobe，它不在我经过核实的项目之列。

原型样例数据与最终上线内容的对比：写成 Rust 并拥有 1.2k star 的 fidx，改为真实的一行简介；虚构的职业经历段落，改成我批准的两句“关于”页开场；不在我核实项目之列的第 4 个项目被删除。
fig 05 原型样例数据与最终上线内容的对比：写成 Rust 并拥有 1.2k star 的 fidx，改为真实的一行简介；虚构的职业经历段落，改成我批准的两句“关于”页开场；不在我核实项目之列的第 4 个项目被删除。

规格文档的规则很直接：没有来源，就不能使用样例数量、日期、角色或技术栈，也不能采用我没写过的个人简介。第一版“关于”页提案因重复导航内容而被拒绝，最终上线的是通过品牌文案审查的两句开场。中文部分遵循同一条规则：只使用设计自带或经我批准的译文。后来仍然需要继续执行这条规则。修复期间，未经批准的文案两次被删除：一行项目页介绍在第 1 轮修复中删除；Codex 添加的 4 条中文字符串由 Claude Code 在审查中删除。对齐视觉不等于获得编写文案的许可。

🧪 所有关卡通过，页面仍没对齐设计

所有里程碑都通过测试和对抗性审查后，设计审计仍发现 20 处与设计不符，其中 6 处严重。 这些里程碑经过了全面测试：单元测试、4 种屏幕尺寸上的浏览器测试、无障碍扫描和视觉快照。但这些测试验证的是智能体写进规格文档的行为，快照对比的也是网站自身的旧版本。没有一项检查在问：网站看起来是否与设计一致？

因此，改版出现在预发布 URL 后，我让 Claude Code 直接对照设计进行审计。Codex 审计并排阅读原型和代码；视觉检查则以参考截图的尺寸和手机宽度分别渲染两者。审计结论是不符合，发现计划未涵盖的 20 处偏差：6 处高、12 处中、2 处低。视觉检查还发现了更多问题。导航里出现了设计没有的下划线；设计中的订阅链接是带边框的按钮，实现中却是纯文本；单集侧栏没有样式，一条很长的来源链接还溢出了侧栏。我从预发布网站截的图又增加了 4 个问题。

每轮审计发现的未跟踪设计偏差：构建完成后有 20 处（6 高、12 中、2 低）；前 6 轮修复后剩 6 处；第 7 轮后剩 2 处；第 8 轮后剩 1 个低严重级别问题；第 9 轮修复了最后一项。
fig 06 每轮审计发现的未跟踪设计偏差：构建完成后有 20 处（6 高、12 中、2 低）；前 6 轮修复后剩 6 处；第 7 轮后剩 2 处；第 8 轮后剩 1 个低严重级别问题；第 9 轮修复了最后一项。

3 次复审把数量从 20 降到 6，再到 2，最后只剩 1 个低严重级别问题，并由第 9 轮修复关闭。有 1 处偏差被有意接受：设计的页脚链接指向一个并不存在的合并播客 feed。审计还发现了一个生产环境早已存在的 bug：单集文字稿会把文件头 "Generated: …" 当作对话内容渲染出来。

补记，2026 年 9 月 14 日： 9 轮修复全部结束、所有关卡都变绿后，我在预发布环境为这个系列的真实文章截图，又发现 5 处实现没有对齐设计交付包：博客索引行的网格布局、一行式导语、文章首字下沉、元信息分隔符，以及图注标签。截图基线此前用的是较短的夹具文章，因此固定下来的是一种只在短内容下看起来正常的排版。我们修复了这 5 处，并加入长内容夹具。下一节的教训现在需要再加半句：在读者实际使用的宽度下，用读者实际阅读的内容检查设计。

📐 符合规格文档，看起来仍然不对

一个选择可以完全符合规格文档，却在审查从未覆盖的屏幕宽度上看起来不对。 写这个系列时，我在 1280 像素宽度重新截了图。首页内容起点比上方 logo 向左偏 124 像素。原因就在冲突清单里。README 要求宽版页面使用 1180 像素容器，原型自身的样式则全程使用 980 像素，清单选择了 README。导航栏仍保持 980 像素。在参考截图的 909 像素宽度下，两个容器都比屏幕宽，都会收缩适配，因此可以对齐。此前每一次设计视觉对比，都只在 909 像素或手机宽度下进行。

宽 1280 像素时的改版首页：导航栏的网站名称从距左边缘 174 像素处开始，下方大标题则从 50 像素处开始。
fig 07 宽 1280 像素时的改版首页：导航栏的网站名称从距左边缘 174 像素处开始，下方大标题则从 50 像素处开始。

我看过后决定保留：宽版首页正是 README 要求的效果。这里的教训在方法上。应该在读者实际使用的宽度下，用读者实际阅读的内容检查设计，不能只检查参考截图碰巧采用的宽度，也不能只用夹具中的短内容。

🧭 设计交付包检查清单

把原型当作设计简报，把规格文档当作合同；最终结果要对照设计审计，不能只对照自己的测试。

  • 对输入取哈希。 任何人开始审查前，先用大小和哈希指定唯一权威设计文件。
  • 写明优先级顺序。 决定发生冲突时，以你的决定、书面说明、token 还是原型为准，并记录已知冲突。
  • 列出绝不能上线的内容。 包括原型机制、样例数据和演示控件。
  • 只允许真实内容。 每个数字、日期、角色和译文都需要来源或你的批准。
  • 通过关卡后再审计。 在多个宽度下对比运行中的网站与设计，其中必须包括读者实际使用的宽度。
  • 用真实篇幅的内容测试。 用真实文章或长内容夹具生成截图基线，不能只用短小样例。

第 3 篇会介绍实际由谁构建：一个拥有 333 个智能体的 Codex 目标会话，然后由 Claude Code 指挥 Codex 逐项修复。

当样稿与书面说明冲突时，你的设计交付包规定以谁为准？

本文写作方式：由 Claude Code 根据我本人的会话日志起草，另一个 Codex 智能体对照同一批日志核对事实，最后由我修改定稿。封面插图由 AI 生成；图表依据文中数字绘制。