1. 项目缘起与核心定位

1.1 一个被名字耽误的宝藏工具

第一次看到 "impeccable" 这个词，很多人会愣一下——这到底是个什么项目？名字本身是英文里"无可挑剔、完美无瑕"的意思，听起来像是个设计规范文档或者某个高端设计系统的代号。但如果你最近在 AI coding agents 的圈子里混，就会发现这个词出现的频率越来越高，而且往往和 frontend design、CLI、browser extension 这几个关键词绑在一起。

我最初接触它是在一个前端项目的重构过程中。当时团队在用 AI 辅助编码工具生成页面组件，生成出来的东西功能上没问题，但视觉上总差那么一口气——间距不统一、颜色搭配别扭、响应式断点处理得粗糙。后来有人推荐了 impeccable 这个思路，我才意识到它解决的正是"AI 生成的前端代码如何达到可交付的设计水准"这个痛点。

简单来说，impeccable 不是一个具体的软件包，而是一套围绕 AI coding agents 构建的前端设计质量保障方法论和工具链组合。它的核心主张是：让 AI 代理在生成前端代码时，不只是"能跑"，而是"跑得漂亮"。这背后涉及 CLI 工具的编排、browser extension 的实时校验、以及一套可复用的设计约束规则。

适合谁来参考？如果你符合以下任意一条，这篇内容就值得你花时间：

• 正在用 AI coding agents（比如各类 CLI 编码助手）做前端开发，但被生成质量不稳定困扰
• 想建立一套团队内部的前端设计质量基线，让 AI 和人都遵守同一套规则
• 对 CLI 工具链和 browser extension 的配合使用感兴趣，想看看别人是怎么把这两者串起来的
• 单纯好奇"impeccable"这个词背后到底藏着什么工程实践

1.2 为什么前端设计质量需要专门"管"

前端开发有个尴尬的现实：功能测试能过、单元测试能过、甚至端到端测试也能过，但页面看起来就是"不对劲"。这种"不对劲"很难用自动化测试捕捉，因为它涉及的是视觉一致性、空间节奏、色彩和谐这些偏主观的维度。

传统做法是靠设计系统 + 代码审查来兜底。设计系统提供组件库和 token，代码审查靠人眼盯着。但 AI coding agents 的介入打破了这个平衡——AI 生成代码的速度太快了，快到人工审查根本跟不上。一个下午 AI 能给你生成二十个页面组件，你不可能逐个去检查 padding 是不是 16px、圆角是不是统一用了一个变量。

impeccable 的思路是把"设计审查"这件事也自动化掉。它通过 CLI 工具在代码生成阶段就注入设计约束，再通过 browser extension 在预览阶段做实时校验，形成一个闭环。这个闭环的关键在于：约束不是写在文档里给人看的，而是写成机器可执行的规则，AI 和人都绕不过去。

注意：这里说的"约束"不是限制创造力，而是把那些重复性的、有明确对错的设计决策固化下来，让 AI 把精力花在真正需要判断的地方。

2. 核心工具链拆解与选型逻辑

2.1 CLI 工具在 AI 编码流程中的角色

CLI 是 impeccable 这套方法论的骨架。为什么是 CLI 而不是 IDE 插件或者 Web 服务？原因很实际：AI coding agents 绝大多数时候是在终端环境里工作的。你给 agent 一个任务，它在命令行里执行、生成文件、运行测试。如果设计校验工具不是 CLI 形态，就很难嵌入到这个流程里。

具体来说，impeccable 涉及的 CLI 工具大致分三类：

第一类是代码生成与编排类，比如各类 codex cli、zcode cli 这样的编码代理工具。它们负责理解需求、生成代码、执行命令。这类工具的关键能力是"可被脚本调用"——你得能通过配置文件或者命令行参数告诉它"生成完代码后跑一下设计校验"。

第二类是设计规则校验类，这是 impeccable 的核心。它可能是一个独立的 CLI 工具，读取你的设计 token 配置文件（比如 JSON 或 YAML 格式的间距、颜色、字体定义），然后扫描生成的代码，找出不符合规则的地方。这类工具的输出通常是结构化的，方便后续处理。

第三类是流程串联类，比如用 Makefile、npm scripts 或者更现代的 task runner 把前两类工具串起来。这一步看起来简单，但实际做的时候坑很多——比如校验失败后是阻断流程还是只警告，这个策略选择直接影响开发体验。

我自己的做法是在项目根目录放一个design-rules.json，里面定义好间距阶梯、颜色变量、断点值这些基础约束。然后在 package.json 的 scripts 里加一条design:check，指向校验 CLI。最后在 AI agent 的配置里，把"生成代码后自动运行 design:check"写进它的工作流。这样每次 AI 生成完组件，校验就自动跑了。

2.2 Browser Extension 的实时反馈价值

CLI 校验有个天然短板：它只能检查代码层面的东西，检查不了渲染后的实际效果。比如两个元素在代码里间距都是 16px，但一个用了 margin 一个用了 padding，渲染出来可能因为盒模型差异导致视觉间距不一致。这种问题 CLI 抓不到，但 browser extension 可以。

impeccable 体系里的 browser extension 通常做这几件事：

• 实时标注设计违规：在页面上直接高亮出不符合设计规则的区域，比如间距不在阶梯上的元素、使用了非 token 颜色的元素
• 提供修复建议：不只是告诉你"这里错了"，还告诉你"应该改成什么"，甚至能一键复制修复后的代码
• 记录设计决策：把当前页面的设计参数导出成结构化数据，方便和 CLI 校验结果做交叉比对

这里有个实操细节值得展开。Browser extension 的校验规则和 CLI 的校验规则必须来自同一个源头，否则会出现"CLI 说没问题但 extension 报错"的尴尬情况。我的做法是把设计规则定义在一个共享的 JSON 文件里，CLI 工具和 extension 都读取这个文件。Extension 那边可以通过配置文件指定规则文件的路径，或者通过一个本地 HTTP 服务动态获取。

提示：如果你用的 browser extension 不支持自定义规则源，可以考虑写一个简单的本地服务，把规则文件暴露成 HTTP 接口，然后让 extension 定期拉取。这个服务用 Python 的 http.server 或者 Node 的 express 几行代码就能搞定。

2.3 为什么是"CLI + Extension"而不是单一方案

有人可能会问：为什么不干脆做一个全能的 IDE 插件，既能校验代码又能预览效果？答案是"场景不匹配"。

AI coding agents 的工作场景是终端，不是 IDE。你在终端里让 agent 生成代码，agent 不会打开 IDE 给你看预览。所以校验必须能在终端环境里跑，这就是 CLI 的不可替代性。而 browser extension 的价值在于它能在你人工检查页面时提供实时反馈，这个场景又不在终端里。两者覆盖的是不同阶段、不同场景的需求，不是替代关系。

另一个原因是可组合性。CLI 工具天然容易被其他工具调用，你可以把它嵌进 CI/CD 流水线、嵌进 git hooks、嵌进 AI agent 的工作流。Browser extension 则更偏向交互式使用。把两者分开，各自做好自己的事，通过共享规则文件来同步，比做一个大而全的工具要灵活得多。

3. 从零搭建一套 Impeccable 工作流

3.1 设计规则的提取与结构化

一切从规则开始。你得先把团队或项目里"什么是好的设计"这件事变成机器能读的格式。这个过程我称之为"设计规则的提取"，听起来很正式，做起来其实很接地气。

拿间距举例。大多数设计系统用的是 4px 或 8px 的倍数阶梯。你可以先统计现有代码里用到的所有间距值，然后归纳出一个阶梯。比如你发现代码里出现了 4、8、12、16、24、32、48、64 这些值，那阶梯就是 4 的倍数（部分）。把这个阶梯写成 JSON：

{ "spacing": { "scale": [4, 8, 12, 16, 24, 32, 48, 64], "unit": "px", "allowNegative": false }, "colors": { "tokens": { "primary": "#1a73e8", "surface": "#ffffff", "text-primary": "#202124", "text-secondary": "#5f6368" }, "allowArbitrary": false }, "radius": { "scale": [0, 4, 8, 16, 9999], "unit": "px" }, "breakpoints": { "sm": 640, "md": 768, "lg": 1024, "xl": 1280 } }

这个文件就是后续所有校验的依据。allowArbitrary设为 false 意味着不允许在代码里写死颜色值，必须用 token。这个约束在 AI 生成代码时特别有用，因为 AI 很容易随手写一个#333而不是用你定义的text-secondary。

提取规则时有个经验：不要追求一步到位。先把你最在意的三到五个维度定义清楚，跑起来，再逐步加规则。一上来就定义几十条规则，结果就是 AI 生成的代码天天报错，团队很快就烦了，最后把校验关掉。我见过太多这样的案例。

3.2 CLI 校验工具的选择与配置

规则有了，接下来是选一个能读这些规则并校验代码的 CLI 工具。市面上没有完全现成的"impeccable CLI"，你需要组合使用。常见的选择有：

• Stylelint：如果你做的是 CSS/SCSS/Less，Stylelint 是首选。它支持自定义插件，你可以写一个插件来校验间距是否在阶梯上、颜色是否用了 token。
• ESLint + 自定义规则：如果设计决策体现在 JSX/TSX 里（比如内联样式或 styled-components），用 ESLint 更合适。
• 自研脚本：如果规则比较特殊，或者你想同时校验多种文件类型，写一个 Node 或 Python 脚本反而更直接。

我个人的选择是 Stylelint + 一个自定义插件。Stylelint 的生态成熟，配置方式灵活，而且它的--fix能力可以自动修复一部分问题（比如把padding: 15px改成padding: 16px）。这个自动修复能力在和 AI agent 配合时特别有价值——AI 生成完代码，跑一下stylelint --fix，很多小问题就自动解决了。

配置 Stylelint 的关键是写自定义规则。下面是一个校验间距是否在阶梯上的规则示例（简化版）：

// stylelint-plugin-design-rules/spacing-scale.js const stylelint = require('stylelint'); const ruleName = 'design-rules/spacing-scale'; const messages = stylelint.utils.ruleMessages(ruleName, { rejected: (value, scale) => `间距值 ${value} 不在设计阶梯 [${scale.join(', ')}] 上`, }); module.exports = stylelint.createPlugin(ruleName, (enabled, options) => { return (root, result) => { if (!enabled) return; const scale = options.scale || []; root.walkDecls(/^(margin|padding)/, (decl) => { const value = parseFloat(decl.value); if (!isNaN(value) && !scale.includes(value)) { stylelint.utils.report({ message: messages.rejected(value, scale), node: decl, result, ruleName, }); } }); }; });

然后在.stylelintrc.json里启用这个规则，并把阶梯值传进去。这样每次跑 Stylelint，所有不在阶梯上的间距都会被标记出来。

注意：这个规则只处理了单值情况，实际项目中你会遇到margin: 8px 16px这样的简写，需要额外解析。建议先用一个成熟的 CSS 解析库（比如 postcss-value-parser）来处理值，不要自己写正则。

3.3 Browser Extension 的安装与规则同步

Browser extension 这边，我目前用的是自己改的一个开源扩展，核心功能是读取一个本地 JSON 规则文件，然后在页面上标注违规元素。安装过程不复杂，但规则同步需要一点配置。

具体做法是：在项目根目录起一个静态文件服务，把design-rules.json暴露在http://localhost:3001/design-rules.json。Extension 的设置里填这个 URL，它就会定期拉取最新规则。这样你改规则文件后，extension 不用重新安装就能生效。

Extension 的校验逻辑和 CLI 不同，它是在渲染后的 DOM 上操作的。比如检查间距，它会读取元素的getComputedStyle，拿到实际的 margin 和 padding 值，然后和规则里的阶梯比对。这种方式能捕捉到 CSS 层叠、继承、盒模型带来的实际偏差，是 CLI 校验的有力补充。

有个细节值得注意：Extension 标注违规时，最好用非侵入式的方式。我见过一些扩展直接在页面上画红框，结果把原本的布局搞乱了。正确的做法是用outline或者box-shadow来标注，这两种属性不影响布局流。或者用绝对定位的覆盖层，但要注意 z-index 和 pointer-events 的处理。

3.4 把校验嵌入 AI Agent 工作流

前面三步做完，你有了规则、有了 CLI 校验、有了 extension 校验。最后一步是把它们串进 AI agent 的工作流，让校验自动发生。

不同的 AI coding agent 配置方式不同，但核心思路一致：在 agent 完成代码生成后，自动触发校验命令。以常见的 CLI 编码助手为例，你可以在它的配置文件里定义一个"后置钩子"（post-hook），内容就是运行npm run design:check。

如果 agent 不支持钩子机制，退而求其次的做法是：在给 agent 的指令里明确要求"生成代码后运行 design:check 并修复所有报错"。这依赖 agent 的指令遵循能力，实测下来大多数现代 agent 都能做到，但稳定性不如钩子。

还有一个更彻底的方案：把校验做成 git pre-commit hook。这样无论代码是 AI 生成的还是人写的，提交前都会过一遍设计校验。这个方案的优点是覆盖面广，缺点是反馈延迟——你得等到提交时才知道有问题。我的建议是两者都做：agent 钩子提供即时反馈，git hook 做最后兜底。

4. 实操中踩过的坑与排查技巧

4.1 规则冲突与优先级处理

实际项目里最常见的坑是规则冲突。比如你的间距阶梯是 4 的倍数，但某个第三方组件的样式用了 5px 的间距，Stylelint 一跑就报错。这时候你有几个选择：

• 把第三方组件的目录加入忽略列表
• 在规则里加例外，允许特定文件或特定选择器使用非阶梯值
• 调整阶梯，把 5px 也纳入进去

我的经验是优先用忽略列表，不要轻易改阶梯。阶梯一旦为了兼容某个第三方组件而妥协，就会失去约束力。忽略列表的配置在 Stylelint 里很简单，用ignoreFiles字段就行。

另一个冲突场景是响应式设计。你在移动端用 12px 间距，桌面端用 16px，两个值都在阶梯上，没问题。但如果你用了clamp()或者calc()做流体间距，Stylelint 的简单解析就抓瞎了。这时候要么把这类声明排除在规则外，要么升级规则让它能处理函数表达式。我倾向于前者，因为流体间距的校验用 browser extension 在渲染后做更准确。

4.2 误报与漏报的平衡

任何静态校验工具都有误报和漏报。误报多了，团队会失去信任；漏报多了，规则形同虚设。平衡这两者的关键是分级处理。

我把规则分成三个级别：

这个分级不是拍脑袋定的，而是根据"这条规则违反后对用户体验的影响程度"来定。颜色和间距直接影响视觉一致性，所以设为 error。圆角和字体大小有一定灵活性，设为 warn。断点和阴影更多是设计偏好，设为 info。

分级之后，CLI 校验的输出也要对应分级。Stylelint 支持severity配置，你可以给每条规则单独设级别。Browser extension 那边则用不同颜色的标注来区分级别，比如红色 error、黄色 warn、蓝色 info。

4.3 AI 生成代码的特殊处理

AI 生成的代码和人类写的代码在"犯错模式"上有明显差异。人类容易犯的错是拼写错误、忘记加单位、复制粘贴导致的值不一致。AI 容易犯的错则是：

• 过度使用魔法数字：AI 倾向于直接写padding: 13px而不是用变量，因为它觉得这样"更直接"
• 忽略设计 token：AI 可能不知道你的 token 体系，随手写颜色值
• 响应式断点随意：AI 可能用@media (max-width: 767px)而不是你定义的md断点

针对这些特点，校验规则要有所侧重。比如对于颜色，我加了一条规则：禁止在 CSS 中出现十六进制颜色值，必须用 var(--color-xxx)。这条规则对人类来说可能有点烦，但对 AI 特别有效，因为它强制 AI 去查 token 列表。

还有一个技巧是在给 AI 的指令里直接嵌入规则摘要。比如在系统提示里写："本项目使用 4px 间距阶梯，颜色必须用 CSS 变量，断点只有 sm/md/lg/xl 四个。"这样 AI 在生成时就有意识，减少后续校验的报错量。实测下来，加了这句提示后，间距相关的报错减少了大概六成。

4.4 常见问题速查表

这个表是我在实际项目中遇到问题后整理的，基本覆盖了八成以上的常见故障。遇到新问题时，先对照这个表排查，能省不少时间。

5. 效果评估与持续优化

5.1 怎么衡量这套工作流有没有用

搭完一套工作流，你得知道它到底有没有产生价值。我用的指标有三个：

第一个是 AI 生成代码的首次校验通过率。就是 AI 生成完代码后，不经过任何人工修改，直接跑 design:check 能通过的比例。这个指标反映的是 AI 对设计规则的"理解程度"。刚开始可能只有三四成，随着你在指令里嵌入规则摘要、调整规则级别，这个比例会逐步上升。我的项目从最初的 35% 提升到了 78%，花了大概三周时间。

第二个是设计相关的代码审查评论数量。以前人工审查时，审查者会花大量时间在"这个间距不对""这个颜色不是 token"这类问题上。有了自动校验后，这类评论应该大幅减少，审查者可以把精力放在交互逻辑、可访问性这些更复杂的问题上。我统计过，设计类评论从每周 40 多条降到了 10 条左右。

第三个是页面视觉一致性的主观评分。这个比较主观，但可以用一个简单的方法：让团队成员在不看代码的情况下，给页面的视觉一致性打分（1-5 分）。每个月做一次，看趋势。这个指标虽然不精确，但能反映整体方向。

5.2 规则集的迭代节奏

规则集不是定完就不动的。我的做法是每两周回顾一次，看看哪些规则报错最多、哪些规则从来没触发过。

报错最多的规则，要么是规则本身有问题（误报），要么是 AI 或人确实容易犯这个错（需要加强提示）。从来没触发过的规则，可能是规则太宽松，也可能是这个维度大家本来就做得很好，可以考虑收紧或移除。

迭代时有个原则：每次只改一到两条规则。一次性改太多，你无法判断效果变化是哪个改动带来的。而且改太多容易引起团队反弹，毕竟规则变严意味着大家要改更多代码。

还有一个经验是保留规则变更日志。每次改规则都记一笔：改了什么、为什么改、预期效果是什么。过几个月回头看，这份日志能帮你理解规则集的演化逻辑，也能在团队新人问"为什么有这条规则"时给出答案。

5.3 从"校验"到"引导"的进阶思路

校验是被动的——出了问题才报错。更高级的做法是主动引导，在 AI 生成代码之前就把设计约束"喂"给它。

具体怎么做？我试过几种方式：

一种是在项目里放一个DESIGN.md，用自然语言描述设计规则，然后在给 AI 的指令里让它先读这个文件。这种方式对 AI 的理解能力要求较高，实测下来效果一般，AI 经常读了就忘。

另一种是把设计规则做成代码片段库。比如把常用的间距组合、颜色搭配、响应式模式写成可复用的代码块，AI 生成时优先从这些代码块里选。这个方式效果更好，因为它把"规则"变成了"素材"，AI 不需要理解规则，只需要选择合适的素材。

还有一种更激进的思路：用 AI 来生成校验规则。你给 AI 看一批"好"的页面和"坏"的页面，让它总结出区分两者的规则。这个思路我还在试验阶段，初步结果有点意思，但稳定性还不够，暂时不推荐在生产环境用。

6. 一些个人体会

这套 impeccable 工作流我断断续续搞了大半年，最大的感受是：工具是次要的，规则的定义和迭代才是核心。我见过太多团队花大力气搭工具链，结果规则定义得乱七八糟，最后工具跑起来了但没人看结果。

另一个体会是不要追求完美。设计规则不可能覆盖所有情况，总会有例外。关键是建立一个"例外可以被讨论和记录"的机制，而不是让例外悄悄绕过规则。我在项目里加了一个design-exceptions.md，任何绕过规则的地方都要在这里记一笔，写明原因和负责人。这个文件慢慢变成了团队的设计决策档案，挺有价值的。

最后说一个实操小技巧：如果你也在用 AI coding agents 做前端，不妨先从一个最简单的规则开始——只校验颜色 token。这条规则最容易实现，效果也最直观。等这条跑顺了，再加间距、再加圆角。一步一步来，比一次性搞个大而全的方案要靠谱得多。