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/LessStylelint 是首选。它支持自定义插件你可以写一个插件来校验间距是否在阶梯上、颜色是否用了 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阻断提交必须修复颜色 token 使用、间距阶梯warn提示但不阻断圆角值、字体大小info仅记录供参考断点使用、阴影值这个分级不是拍脑袋定的而是根据这条规则违反后对用户体验的影响程度来定。颜色和间距直接影响视觉一致性所以设为 error。圆角和字体大小有一定灵活性设为 warn。断点和阴影更多是设计偏好设为 info。分级之后CLI 校验的输出也要对应分级。Stylelint 支持severity配置你可以给每条规则单独设级别。Browser extension 那边则用不同颜色的标注来区分级别比如红色 error、黄色 warn、蓝色 info。4.3 AI 生成代码的特殊处理AI 生成的代码和人类写的代码在犯错模式上有明显差异。人类容易犯的错是拼写错误、忘记加单位、复制粘贴导致的值不一致。AI 容易犯的错则是过度使用魔法数字AI 倾向于直接写padding: 13px而不是用变量因为它觉得这样更直接忽略设计 tokenAI 可能不知道你的 token 体系随手写颜色值响应式断点随意AI 可能用media (max-width: 767px)而不是你定义的md断点针对这些特点校验规则要有所侧重。比如对于颜色我加了一条规则禁止在 CSS 中出现十六进制颜色值必须用 var(--color-xxx)。这条规则对人类来说可能有点烦但对 AI 特别有效因为它强制 AI 去查 token 列表。还有一个技巧是在给 AI 的指令里直接嵌入规则摘要。比如在系统提示里写本项目使用 4px 间距阶梯颜色必须用 CSS 变量断点只有 sm/md/lg/xl 四个。这样 AI 在生成时就有意识减少后续校验的报错量。实测下来加了这句提示后间距相关的报错减少了大概六成。4.4 常见问题速查表问题现象可能原因排查步骤解决方案CLI 校验通过但页面看起来不对校验只查代码不查渲染用 browser extension 在页面上复查补充 extension 校验规则AI 生成的代码大量报错规则太严或 AI 不知道规则检查报错类型看是否集中在某几条规则调整规则级别或在指令里嵌入规则摘要Extension 标注位置偏移标注元素用了 transform 或定位检查标注元素的定位方式改用 outline 或基于 getBoundingClientRect 定位规则文件改了但 extension 没生效缓存或拉取间隔问题手动刷新 extension检查网络请求缩短拉取间隔或加手动刷新按钮Stylelint --fix 改坏了代码自动修复规则有 bug对比修复前后的 diff禁用该规则的 fix 能力只保留检测第三方组件样式报错规则未排除第三方目录查看报错文件路径在 ignoreFiles 里加入第三方目录这个表是我在实际项目中遇到问题后整理的基本覆盖了八成以上的常见故障。遇到新问题时先对照这个表排查能省不少时间。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。这条规则最容易实现效果也最直观。等这条跑顺了再加间距、再加圆角。一步一步来比一次性搞个大而全的方案要靠谱得多。
