AI 编码代理写前端，过去一年里大家最常吐槽的问题不是“能不能写”，而是“写出来像不像一个人做的”。你给它同一个需求，十次能给你五种间距体系、三种圆角哲学，哪怕你已经在提示词里写清楚“遵循设计系统”，它依然会在细节上自由发挥。这个问题的本质不是模型不够聪明，而是代理缺少一套能约束输出、可验证、可回滚的“确定性框架”。Impeccable 这个开源技能框架，做的就是这件事——把前端设计的确定性重新还给 AI 编码代理。

如果你正在用 Cursor、Claude Code 或者自建的 Agent 流程做前端开发，并且受够了接二连三的“设计漂移”，这篇文章值得你花十分钟读下去。我会从为什么需要这样一个框架、它的核心设计思路、怎么接入现有工程，再到实际跑起来会遇到哪些坑，完整拆一遍。

1. 为什么 AI 编码代理总是缺少“想要的感觉”

先说一个自己踩坑的经历。我之前带一个前端 AI 改造项目，Agent 负责把旧 jQuery 页面改造成 React 组件。功能倒是一次性跑通了，但视觉上惨不忍睹：按钮间距忽大忽小，表单控件高度不统一，卡片阴影在不同页面里长得完全不像亲兄弟。Review 的时候我一条条标注“这里不对”，Agent 修一处、坏一处，来回拉扯了好几轮。

1.1 问题本质：大模型的熵不是 bug，是特征

很多人以为这是 prompt 写得不够详细。其实不是。大模型生成代码时，本质上是在做概率采样，它对“不错的按钮样式”有自己的统计偏好，而这个偏好和你们团队的设计规范之间，存在一条巨大的鸿沟。你可以在 prompt 里写“遵循 Design System”，但模型并不会像一个遵守校规的学生那样逐条执行，它只会把这些话当成一种弱约束。

再加上上下文窗口有限，Agent 往往只记住最近几轮对话里的局部反馈。这导致一个非常经典的现象：单看每一次生成的页面都还说得过去，但把所有页面放在一起，立刻能看出是“AI 写的”——因为没有任何一个人类设计师会同时使用三种不同的主色。

1.2 “技能框架”解决的是约束层，而不是生成层

Impeccable 这类开源技能框架的核心思路，是不去改变模型的生成能力，而是在模型外围套一层“可编程的设计约束层”。

具体拆开讲，它做了三件很实际的事：

第一，把设计规范从自然语言描述，转换成结构化的、可校验的规则数据。比如“主色是 #2F6FED”“卡片圆角一律 12px”“间距必须使用 4px 的倍数”，这些不再靠模型自觉，而是作为一种显式输入注入到生成链路里。

第二，把规范、校验器和修复提示打包成一个一个的“技能”。Agent 在动手改代码之前，先加载对应技能包，就知道这个项目的设计基线是什么，以及改完之后要用什么标准来检查自己。

第三，提供确定性检查通道。生成结果出来以后，不靠人眼判断，而是跑一遍自动化检查：颜色 token 是否合法、排版是否越界、样式变量是否被硬编码值绕过。有检查结果，才有资格谈“确定性”。

1.3 这里的“确定性”到底是什么

一说确定性，很多人会误以为又是要限制模型输出、让结果千篇一律。不是这个意思。

在当前这个场景下，确定性指的是：给定相同的输入上下文和设计规范，AI 生成的前端代码在关键视觉属性上保持一致，并且能通过预设的低层检查，而不是靠运气。

换句话说，设计师的创意自由度依然保留在规则之上，但凡是规则覆盖到的地方，AI 就不能越界。这种确定性和“模板化”完全是两码事，它更像是给 AI 画了一条护栏——车道可以换，但不能开到人行道上去。

2. 一张图看懂 Impeccable 的框架结构

我在实际接入 Impeccable 之前，花了不少时间研究它的目录设计和运行机制。这个框架并不算复杂，但它的分层方式很有代表性，值得拿出来讲讲。

2.1 四个核心层级：规范、技能、校验器、适配器

把 Impeccable 拆开看，它的主体是这么四层：

第一层是规范仓库。这一层存放所有设计变量的定义，包括颜色、字体、间距、圆角、阴影、断点。它的格式通常是 JSON 或者 YAML，设计团队可以直接维护，不需要懂代码。

第二层是技能目录。每一个技能相当于一个“场景化执行包”，里面包含了一组规范切片、一组指令模板、以及对应的校验规则。举个例子，"卡片组件技能"里会包含卡片相关的颜色规范、间距规范、圆角规范，以及检查这些规范的脚本。

第三层是校验引擎。这一层负责在代码生成后，对产物做静态检查。它会解析生成代码里的样式值，和规范仓库中声明的 token 做比对，找出裸值、非法颜色、错误间距这类问题。

第四层是适配器。这是和具体 AI 编码代理对接的一层。Claude Code、Cursor、Continue 各有各的上下文注入方式，适配器负责把技能内容翻译成这些工具能读懂的形式，包括 system prompt 片段、辅助脚本路径，以及校验命令。

2.2 “技能”不是提示词，而是可复用的工序

现在很多项目里都在提“提示词工程”，但 Impeccable 里“技能”的概念比提示词要重得多，也更工程化。

我个人的理解是，一个技能本质上是一条完整的流水线。它要描述清楚这些环节：

• 输入是什么：比如一个组件的描述文本、需求上下文
• 参考规范是什么：比如需要加载哪几组设计 token
• 执行策略是什么：比如哪些布局方案被禁止、哪些模式被推荐
• 验收标准是什么：比如运行哪几条校验命令、阈值是多少
• 失败修复提示是什么：校验不通过时，Agent 应该按什么思路自行修正

这其实就是在把 AI 编码代理当成一个真正的“团队成员”，给它交底、给它标准、给它返工指引。Impeccable 只是把这一套工作方式标准化了，让不同项目能共享同一套执行逻辑。

2.3 最适合它的集成姿势

我自己试下来的经验是，Impeccable 最合适的集成点有两个。

第一，接在 Agent 的系统 prompt 层。启动代理时就把当前项目的技能清单注入为上下文，Agent 在生成代码前就知道要遵守什么。

第二，接在 Agent 的工具调用层。把校验命令暴露成代理可以调用的工具函数，让 Agent 在写完代码以后主动跑一遍检查，然后根据检查结果自我修复。

这两个姿势可以同时用。前者解决“不知道规则”，后者解决“明知有规则也不管”。只做注入不提供校验工具，等于只给学生发校规不发考卷，最终效果大打折扣。

3. 实操指南：把你的工程接入 Impeccable

这段时间大家搜“Impeccable 如何使用”，搜到的多半是项目主页和 README。我这里直接给一份可以落地的接入过程，都是自己亲手跑过的流程，你看完可以照着操作。

3.1 环境准备：其实只需要一个 Node 环境

Impeccable 本身是用 TypeScript 写的，运行时依赖 Node.js 18 以上，以及一个包管理器。它还支持通过 npx 直接调用 CLI，不需要先全局安装。

# 检查 Node 版本 node -v # 在项目根目录初始化 npx impeccable init

init命令会帮你做这几件事：创建.impeccable/目录、生成默认的规范仓库结构、写好一份示例技能、以及在.gitignore里登记需要排除的临时文件。整体体验比较顺，基本不需要手动建目录。

3.2 定义设计规范：先把 token 和裸值分开

规范仓库是全部工作的地基。我建议第一个动手的文件是tokens.json，它定义设计变量。下面是一份我在实际项目里用过的简化版本：

{ "color": { "primary": "#2F6FED", "primary-hover": "#1D5BD8", "surface": "#FFFFFF", "text": "#1A1D21", "text-secondary": "#5B626A", "danger": "#D14343" }, "spacing": { "xs": "4px", "sm": "8px", "md": "16px", "lg": "24px", "xl": "32px" }, "radius": { "sm": "6px", "md": "12px", "lg": "20px" }, "font": { "family": "\"Inter\", \"PingFang SC\", sans-serif", "size-body": "14px", "size-h1": "28px" } }

这份文件的意义，不只是给 AI 看，它同时是校验器的比对基准。后面所有检查，都会拿生成的代码里实际出现的尺寸和颜色值来跟它对比。

3.3 编写一个最小可用的技能

技能文件放在.impeccable/skills/下，每个技能一个目录。拿按钮组件来说，我会建一个button-card技能，里面至少包含三块内容：

name: button-with-card description: 用于生成符合设计规范的按钮和卡片组件 design-tokens: - color.primary - color.surface - color.text - spacing.* - radius.* forbidden-patterns: - "style=\".*color: #[0-9a-fA-F]{6}\"" - "border-radius:\\s*\\d+px" validation: - command: "npm run check:tokens" description: "检查是否存在绕过 token 的硬编码颜色和圆角"

这个文件描述了三件事：该技能覆盖哪些 token、哪些写法算违规、以及用什么命令来验证。

3.4 和编码代理做对接：注入与工具调用

接下来是真正和 Cursor 或者 Claude Code 接上的步骤。我这里给出的是一套通用思路，因为 Impeccable 的适配器层已经封装好了大部分细节。

你可以通过适配器生成一份代理规则文件。以 Claude Code 为例，它会生成类似这样的内容：

你正在参与 {project} 的前端开发。 在生成任何组件代码之前，你必须先阅读 .impeccable/skills/{skill-name}/ 目录下的规范说明。 生成代码时，禁止使用规范以外的裸色值，禁止绕过间距 token 直接写像素值。 代码生成完毕后，运行 npm run check:tokens 进行自我检查； 如果检查失败，根据输出信息自行修复再次提交。

把这段规则注入到系统提示词里，然后把check:tokens暴露成 Agent 可以调用的工具。这一步完成后，Agent 的行为会发生肉眼可见的变化——它会在生成前先找规范，生成后主动跑检查，而不是交差了事。

我在实测下来最明显的变化是：按钮的 hover 颜色从“AI 自由发挥”变成了“严格跟随 primary-hover”。这种细节上的收敛，对整个产品观感的统一帮助极大。

4. 核心链路拆解：从规范到检查再到修复

一个框架如果只是把规则贴给 Agent 看，那它和一份写得好的设计文档没区别。Impeccable 真正硬核的地方，是把规则变成了可自动运行的检查链路，并且让 Agent 能消费这个链路的结果。

4.1 检查引擎是怎么抓到问题的

我自己试过几种方式，最终发现这个框架的检查引擎主要做三件事：AST 解析、token 映射、违规定位。

先说 AST 解析。它会把你生成的 JSX/TSX 或者 CSS 文件解析成抽象语法树，然后提取所有和样式相关的节点，再把这些节点里的属性值，比如color、margin、borderRadius，和 token 仓库里的值做映射。

如果发现某个颜色值没有对应的 token，比如你写了个#E5E7EB，但仓库里根本没有这个颜色，它就会记录一条违规。

如果发现某个间距值没有落在 token 序列里，比如padding: 13px这种既不是 12px 也不是 16px 的值，也会被标记。

接下来它还会做模式匹配，专门抓那些容易绕过的写法，比如内联 style 里写裸值、随意使用rounded-full这类类名。

4.2 一个实用的校验命令工作流

我习惯把校验设计成一个可以被本地命令、CI 流程和 Agent 工具共同调用的统一入口。框架默认的check命令，足够覆盖绝大数场景：

# 针对当前变更做校验 npx impeccable check --scope staged # 跑全量校验 npx impeccable check --all # 输出 JSON 结果，方便 Agent 后续解析 npx impeccable check --all --format json

跑出来的结果格式大致是这样：

{ "violations": [ { "file": "src/components/Card.tsx", "line": 42, "type": "hardcoded-color", "actual": "#E5E7EB", "suggestion": "替换为 token: color.surface-muted" }, { "file": "src/components/Button.tsx", "line": 17, "type": "spacing-out-of-scale", "actual": "13px", "suggestion": "使用 spacing 序列中最接近的值: sm(8px) 或 md(16px)" } ] }

这个 JSON 是我觉得整个框架里最有价值的一部分。因为 Agent 可以读它、理解它、然后针对性地修改自己生成的代码。到了这一步，Agent 就拥有了“自我纠错”的能力，不再需要人盯着它一条条改。

4.3 实测稳定下来的参数参考

在接入过程中，有几个参数是决定最终体验的关键，我这里整理一个参考表，方便你根据自己的项目调整：

这个配置组合是我在多个前端项目里试出来的平衡点。太严格的间距校验会导致 Agent 反复返工，太宽松又无法落地。颜色和字体是最影响品牌感的维度，建议从严格模式开始。

5. 常见问题与排查技巧实录

接入新框架，踩坑是难免的。我把这段时间用过 Impeccable 后遇到的典型问题整理了一遍，这些问题在官方文档里不一定能搜到，但实际碰上的概率极高。

5.1 Agent 完全不理会注入的规则怎么办

我遇到过的第一种情况，是系统提示词里已经写明了必须遵循规范，但 Agent 依然我行我素。排查下来发现，原因往往不是它叛逆，而是上下文太长，规则被挤出了有效注意力窗口。

解决办法是这样：把规范文件拆成“核心必读”和“扩展可选”两部分。系统提示词里只放核心约束，比如“禁止硬编码颜色、禁止使用非 token 间距”，细节规范放到生成具体组件前，由 Agent 主动读取对应技能文件。实测下来，这种“先给结论、后给论据”的方式，比一次性灌入几十条规则可靠得多。

5.2 校验器误报严重怎么办

误报大多数出现在已经有了老代码、需要渐进式改造的项目里。旧代码里全是硬编码值，一套严格校验就全员报警，Agent 会因为信息量太大而丧失修复能力。

我的做法是引入“存量豁免名单”机制：对历史文件不做强制修复，只确保新增或者修改的代码符合规范。Impeccable 支持按文件目录配置检查范围，我会把legacy/目录加进豁免名单，只对新组件和重构文件启用严格校验。等团队有精力的时候，再逐步蚕食老代码。

5.3 检查结果不稳定，同一段代码时而过关时而不过

这个问题我排查了很久，最后发现是缓存问题。校验器在解析依赖的时候，偶尔会拿到过期的缓存文件，导致结果漂移。

解决方案很直接：在 CI 流程里增加一次干净的依赖安装步骤，同时清空校验器的临时目录。另外，确保校验命令和代码生成用的是同一个 Node 版本，否则解析行为可能会有细微差异。

5.4 一个值得分享的小技巧

默认技能包里给的模板偏通用，直接用在业务项目上效果会打折。我建议每个团队都建立一个自己的“业务技能库”，把常用组件的行为模式沉淀进去。

比如我们团队把“数据表格”“筛选表单”“详情页布局”都做成了独立技能，每个技能里不仅有设计规范，还包含了固定的组件结构约定。这带来的好处是，Agent 生成的表格不会今天用Table明天用DataGrid，整体一致性上了一个台阶。这个习惯一旦养成，框架的价值会随着时间越滚越大。

6. 一些扩展方向：从组件规范到设计治理

Impeccable 接入项目越久，我就越觉得它的定位不只是“给 AI 用的设计规范”，而是一个设计治理基础设施。顺着这个思路往下走，有几个方向值得关注。

6.1 多主题和品牌变体管理

公司做大之后，难免会有多个品牌、多种主题并存的情况。项目里一个通用模块可能同时服务于 A 品牌和 B 品牌，它们在主色、圆角、字体表现上完全不同。

Impeccable 的规范仓库设计是天然支持多套 token 的。你可以为每个品牌维护一份独立的 token 文件，在技能里按需加载。同一个组件会基于不同的 token 生成不同的风格变体，但每个变体内部完全自洽。

6.2 把校验嵌进 CI 而不是只交给 Agent

我强烈建议别只依赖 Agent 的自我检查。人都会偷懒，Agent 也会。最好的方式是把核实环节放到 CI 流水线里，让不符合规范的分支根本合不进去。

具体操作不复杂：在 CI 的代码检查阶段加一步npx impeccable check --all，失败就阻断合并。这一步加上以后，团队对 AI 生成代码的信任感会有质的提升，因为规范不再是软约束，而是和单测、Lint 一样是硬门槛。

6.3 什么时候建议谨慎引入

最后说点冷水。Impeccable 不是万能药，如果你的项目处于以下状态，我建议先别急着上：设计规范本身还没定稿，团队还在频繁调整视觉风格；前端代码几乎全是历史遗留且无人重构；AI 编码代理的使用频率很低，大部分代码还是人肉写的。

框架的价值建立在“有一套相对稳定的规范”和“AI 产出占比较高”这两个前提之上。前提不成立，硬上只会增加流程负担，变成团队的额外成本。

我在实际落地过程中最深的一点体会是：Impeccable 真正改变的不是 AI 写的代码本身，而是整个交付链路里“设计规范从软建议变成硬约束”的转变。过去我们靠人肉 review 保证一致性，现在只需要把规则交给框架、把检查交给脚本、把修复交给 Agent，人抽身出来做真正重要的判断。

如果你也正在为 AI 编码代理的前端输出漂移头疼，不妨拿一个非核心页面组件试一周，用具体的检查数据对比一下前后的差异。这个框架值不值得留在你的项目里，数据会给你答案。