在 Vercel 内部，我们使用编码代理来设计和构建那些必须在外观和感觉上都像 Vercel 的页面。排版、颜色和构图都必须承载我们对自己已发布页面所投入的同等判断力。
我们最近写过 product-design
，这是我们的技能，用于教会代理在我们的代码库中工作时我们是如何设计的。该技能与它所管理的代码一起存在于每个仓库中，解释代理如何找到并理解我们的设计系统，以及针对他们正在构建的任何内容的产品指南。
当代理在我们的代码库中工作时，这非常有效，因为该技能所需的一切都触手可及。但对于报告、提案以及那些仍然必须看起来像 Vercel、却是在无法读取任何这些文件的工具中制作的一次性页面呢？对我们来说，答案是 design.md，一个任何代理都可以加载的公开文件。
复制标题链接我们如何着手构建 design.md
让 product-design
发挥良好作用的原因在于，设计系统和产品指南就放在仓库中供代理阅读。我们需要一种方式，让该环境之外的代理和工具也能获取同样的知识，这样最终产出的页面仍然看起来像是我们自己设计的东西。这设定了两项要求：
一个公开 URL，任何人都可以让自己的代理指向它，无论它们运行在什么环境中。
涵盖最初让
product-design
有用的所有内容的指南，从品牌、布局和文案写作到设计系统、响应式设计和信息架构。
我们首先尝试的朴素做法是简单地将 product-design
移植成一个公开提示词，把该技能的参考文件压缩成一个任何代理都可以从 URL 读取的文件。我们发现的问题是，虽然这个提示词很好地描述了我们的视觉语言，但每个阅读它的模型都以不同方式解读该描述，从同样的指南中生成出截然不同的页面。
部分原因在于设计语言是主观的。像“保持布局干净”这样的说法实际上可以意味着任何东西。什么是“干净”？除此之外，更大的问题是提示词遗漏的其他一切。在我们的代码库内部，代理阅读 product-design
时，周围是真实组件和它所描述内容的已发布示例。但公开提示词不包含任何这些，让每个模型只能仅凭文字重建我们的风格。
所以我们需要做的，是把那个环境所提供的内容提炼成一个文件，而要知道我们是否越来越接近，唯一的方法就是查看产出的页面。我们把移植放在一边，开始从头编写一个新文件，这一次针对一组可重复的评估提示词测试每一次更改。
我们写了七个提示词，取自真实用例并配上模拟输入：
使用情况和性能报告
续约提案
基准报告
交互式规划页面
自建与购买简报
安全治理简报
演示文稿
提示词保持不变，而文件不断变化，因此输出中的任何差异都可追溯到指南。
复制标题链接第一次比较
这些评估让我们既能衡量文件实际在做什么，也能衡量不同智能体是如何解读它的。在我们的第一个测试中，我们想知道 design.md
是否真的会改变模型产出的内容。我们在同一环境中用同一模型运行了两次续约提案评估，一次不加载 design.md
，一次加载它，两次运行中提示词、数据和视口都保持完全一致。
不加载 design.md
时，模型生成了一个通用的 SaaS 仪表盘。但加载后，页面以续约建议本身开头，把商业证据汇集到一个网格中，将同类数值放在同一尺度上以便真正可以比较，并让支撑性细节保持可获取，同时不让它们与摘要争夺注意力。这让我们得以得出结论：该文件也改变了页面的结构和层级，而不仅仅是我们最初发现的样式，这给了我们足够的信号来继续像这样一条规则一条规则地构建指导。
复制标题链接让系统运转的三个部分
在我们测试并重建 design.md
的过程中，范围演变成了一个由三部分组成的系统，正是它让整件事运转起来：
design.md提供指导，向智能体展示如何框定读者的任务、组织证据并选择构图。一个公开的
样式表，定义了一套有边界、有文档的类和令牌词汇表。一个评估循环，将反复出现的人类反馈转化为更好的指导和确定性检查。
这些层次各自覆盖了打造高质量、符合 Vercel 品牌页面这一工作的不同部分。编码进 design.md
的判断力为智能体提供以下方面的指导：
为快速的高管阅读和详细的审计塑造页面。
用具体的论断和诚实的限定条件撰写文案。
组织层级、排版和颜色，使证据与文字相互支撑。
如何以 Vercel 的身份发布，细到我们字标和三角形标志的资产规则。
design.md
还列出了我们绝不想看到的反复出现的生成式设计模式，通过给这些模式命名，让智能体能够更可靠地识别并避免它们。
我们创建样式表，是因为智能体不断自行发明排版、间距和布局，所以我们干脆把这些决策从模型手中完全拿走。样式表将我们设计系统的原语，如页眉、表格、统计条和图表样式，打包为任何页面都可以通过公开 URL 使用的 CSS。然后 design.md
记录样式表提供的类名和令牌，让智能体可以在 HTML 中使用这些名称来构建页面，而不是重新发明它们。
这带来的另一个好处是，智能体实际上从不读取样式表本身。样式表在你的浏览器中渲染页面时加载，因此没有任何代码进入模型的上下文，从而为设计指导节省出更多空间。
最后，评估循环是帮助另外两个部分发挥作用的关键。确定性检查用于帮助捕捉机械性故障，例如表格忽略了可供其使用的宽度，而由人来判断无法自动化的主观部分，比如层级、构图，以及页面是否真正给读者提供了他们想要的东西。
复制标题链接指导内容如何进入文件
design.md 中的每一行指导
都是通过评估循环赢得其位置的。我们从固定场景生成页面，审查返回的结果，将我们接受的修正编码进去，然后重新运行场景，看看每项更改是否站得住脚，因为一项对某个产物有帮助的更改可能会悄悄损害另一个产物。没有任何内容以其他方式进入。
复制标题链接场景与轮次
七个提示中的每一个都成为一个场景，意味着该提示与其模拟输入和渲染设置一起被冻结。例如，续约提案始终使用相同的假客户数据和相同的视口设置运行，使 design.md
成为各次运行之间唯一变化的东西。一轮意味着针对该文件的当前版本，从每个场景生成一个新页面。完整轮次覆盖 Claude Opus 4.8 和 Codex with GPT-5.5 上的全部七个场景。
如果我们想调查某些具体问题，例如只影响表格的规则更改，我们可以重新运行受影响的场景或单个模型，保持迭代循环紧凑。
将全部七个页面一起生成也使它们易于并排比较，而引人注目的是，design.md
并没有把每个页面都推向同一个模板。交互式规划页面将其控件放在最显眼的位置，因为人们打开规划页面是为了更改数字并看看会发生什么。续约提案则以建议及其背后的商业比较开头，因为它的读者正在决定是否续约。每个页面都使用相同的 Vercel 排版、颜色和间距，但每个页面都围绕其读者前来要做的事情来组织。
复制标题链接审查每一次运行
为了审查每一轮产生的页面，我们构建了一个本地应用，用于显示整页渲染结果并运行盲测 A/B 比较。这个应用最终成为我们的评估工具，运行每个场景并存储结果。每个存储的运行都保留提示、输入、模型配置、它所使用的 design.md
版本、截图，以及审查者留下的任何反馈。审查者针对产生修正的确切运行记录每一项修正。
复制标题链接将修正转化为规则和检查
审查者记录的每一项修正都会被放到能够持续强制执行它的最窄位置。判断性更改以散文形式进入 design.md
，可复用的机制进入样式表，而任何我们可以机械检查的内容都会成为代码中的确定性检查。工具本身的问题留在工具中，当单个模型以其他模型不会出现的方式失败时，我们会将其排除在规则之外，直到它重复出现。
以早期的一份续约提案为例。它的商业条款表格返回时被压缩到与正文相同的宽度，尽管页面有空间让表格宽度翻倍。
在审查过程中，我们标记出证据表格应使用其可用的全宽。但当我们查看之前的输出时，发现同样的失败无处不在。因此，这一修正最终被放到了两个地方：
design.md 中的一条规则，说明预期的行为。代码中的一个确定性检查，用于在下次出现同样的布局失败时捕获它。
一旦这一修正落地，后续的续约提案提示词生成的页面就拥有了正确的全宽表格。为了验证像这样的更改，我们在将受影响的场景编码后重新运行了它们。在里程碑节点，我们更进一步，运行了盲测 A/B 轮次，将更新后的 design.md
与文件的早期版本进行对比，以决定是保留、修改还是回退每一项更改。
复制标题链接衡量它是否有效
构建这个文件用了远超 200 次运行，包括完整轮次、针对性检查、试运行以及所有死胡同。除了人工审查者，还有一个模型评判者为每一轮撰写评语，每一轮的反馈都被用于改进下一轮运行。
在所有这些运行之后，我们想知道我们编码的修正是否真的在防止它们所针对的失败。因此，我们挑选了三个桌面场景，对每一个场景，我们让搭载 GPT-5.5 的 Codex 生成页面两次，一次加载 design.md
，一次不加载。我们保留每次生成的第一次尝试，不重新生成。然后我们对全部六个页面运行确定性检查，并统计每个集合中已知失败（例如表格忽略其可用宽度）出现的次数。使用 design.md
生成的页面有 39 次此类失败。不使用它生成的页面有 91 次，在此测试中减少了 57%。
这些数字有两个注意事项。检查只能捕获我们已经见过并记录下来的失败，因此这个测试无法说明页面整体设计是否良好。六个页面作为样本也远远太小，无法对质量或可靠性做出断言，而且每一个页面，无论是否使用该文件，都至少有一个严重到足以阻止发布的失败。但这个测试做得好的地方在于，它告诉我们，一旦我们命名一个失败并将其编码，那个失败往往会保持消失。
复制标题链接design.md
如何保持最新
评估循环让文件得以发布，但让它保持最新的是实际使用。在我们的 Slack 内部，这种使用通过 @design-agent
进行，这是一个基于 eve 构建的代理，我们用它来处理从设计评论和文案备选方案到图标推荐以及根据粘贴数据构建报告站点等各种事务。无需设置提示词或寻找源文件，你只需在话题中提及该代理。对于网站请求，它会加载当前的 design.md
，根据已发布的样式表构建页面，并将整页截图和部署 URL 回帖到话题中。与我们的固定场景不同，这些话题中的每一个都捕获了真实的请求、真实的输出以及随后的任何反馈或引导，向我们展示了该指南在现实世界中的表现。
每周，我们会将所有反馈汇集到一处：Slack 讨论串，以及来自 GitHub 评审和 Figma 的评论。自动化会把反复出现的评论归为一组，每一条重复的抱怨都会变成一个提议的变更。然后由一个人审查每项提议，检查系统是否已经处理了它，并决定被接受的修复应该放在哪里——是 @design-agent
、product-design
技能、design.md
、样式表，还是确定性检查。如果人们开始要求一种我们从未测试过的页面，这个请求就会成为一个新的评估场景。
要知道这些是否奏效，我们会统计每种抱怨在相似工作中随时间出现的频率。一旦我们编码了一个修复，这个计数就应该开始下降。如果没有下降，说明修复本身有问题。规则可能不够清晰，可能在需要时没有加载，样式表可能没有能表达它的原语，或者它可能需要确定性检查而不是文字描述。
复制标题链接构建你自己的
你可以自己构建同样的循环，从一个反复出现的产物和一次手动比较开始。
1. 选择一个重复出现的产物
使用一个近期任务，要有真实的读者和真实的输入，比如提案、性能报告、基准测试或微型网站。避免像“让它符合品牌调性”这样宽泛的目标。在生成任何内容之前，先写下一个简短的评分标准。一个好的标准会检查：提供的事实是否保留下来，读者的决策是否清晰，以及你一直手动做的修正是否真的得到了解决。
2. 先保存基线
在没有任何新设计上下文的情况下生成一次页面，并保存提示词、输入、配置和截图。即使第一次输出看起来很粗糙，也要保留它，除非测试框架本身失败了。没有“之前”，你就无法判断新的上下文是否有帮助。
3. 从你最近十次修正开始
收集你在设计评审、拉取请求或 Slack 中反复给出的反馈，并把每条修正改写成可观察的内容。这意味着要写 让证据表格使用全部可用宽度
，而不是 让表格感觉不那么拥挤
，因为只有前者可以被检查。
把决策放在一个文件里，分节包括范围、读者与任务、可观察的决策，以及可用的原语。这个文件就是你的第一个 design.md
。
4. 约束可重复的机制
如果你的输出总是自创字体、间距或布局，就发布一个样式表，并记录智能体可以使用的确切类和令牌。把你的判断留在文字描述中，把可重复的机制推入 CSS 或确定性检查。
5. 运行一次匹配比较
用相同的输入、模型和视口再生成一次页面，但这次加载你的文件。把它与基线打乱，并在不知道哪个是哪个的情况下，根据你的评分标准给两者打分。
开始时你不需要运行器或模型评判器，单次试验就能揭示大的、明显的失败。要衡量可靠性，请运行多个独立的首轮试验（Anthropic 的智能体评估指南），并报告结果保持稳定的频率。
6. 编码修正
在查看输出时，连同你必须发送的任何后续提示词一起审查，然后问：
用户不得不重复或手动引导什么？
是否有规则缺失或不清晰？
样式表能否表达这个修正？
这个失败是否足够机械，可以在代码中检查？
这个修正是否能泛化到当前输出之外？
更新指导，而不是手动微调生成的页面。你的下一次对比会告诉你，最初的尝试是否真的有所改进。
在手动循环开始见效之后，再添加工具：
纳入指导应当适用和不应适用的场景。
在编辑时保留一小部分隐藏的留出集。
记录模型和指导的版本。
自动化机械性检查。
使用多位盲审评审者。
无论你把自动化推进到何种程度，最终改动都要经过人工审核。
然后让这个循环持续运转。按固定节奏收集反馈，并观察在你修改指导之后，每一类抱怨是否真的变得不那么常见。如果人们在生产环境中不断纠正同一个错误，那么一次通过的评估就没那么重要了。
如果你想要可运行的示例，我们的示例是公开的。我们每天都把 design.md 加载到 v0、Codex 和 Claude 这类工具中，来制作具有 Vercel 风格的产物，而 eve design agent template 能帮你搭建一个像我们运行的那样的 Slack 设计智能体。