impeccable：为AI编码代理注入前端设计规范与质量约束

1. 从"impeccable"这个词说起：它到底想解决什么问题

第一次看到"impeccable"这个项目名，我脑子里蹦出来的不是词典释义，而是一个很具体的场景：你让 AI coding agent 帮你改一个前端页面，它噼里啪啦输出一堆代码，跑起来一看——间距不对、颜色不统一、响应式在某个断点直接崩了。代码"能跑"，但离"能看"差了十万八千里。

impeccable 这个词本身的意思是"无可挑剔的、完美的"，放在 AI coding agents 和 frontend design 这个语境里，它的野心就很清楚了：让 AI 写出来的前端代码不只是功能正确，而是视觉上、结构上都挑不出毛病。它不是一个框架，也不是一个 UI 库，更像是一层"质量约束层"——通过 CLI 和 browser extension 两种形态，把前端设计的规范、检查、修正能力塞进 AI 编码的工作流里。

我为什么对这个方向感兴趣？因为过去一年多我一直在用各种 AI coding agent 做前端项目，踩过的坑基本可以归成三类：第一类是 AI 生成的 CSS 缺乏系统性，东一个margin: 13px西一个padding: 7px，完全没有设计 token 的概念；第二类是 AI 对响应式断点的理解很粗糙，经常只考虑桌面端；第三类是 AI 改完代码后没人验证视觉效果，等到人工 review 时已经积重难返。impeccable 想做的，就是在这三个环节里插一道自动化的"审美与规范检查"。

这篇文章适合谁看？如果你正在用 Codex CLI、Zcode CLI 这类命令行 AI 编码工具，或者你在浏览器里用 AI 辅助改前端，那 impeccable 的 CLI 和 browser extension 两种用法你都该了解一下。如果你只是偶尔让 AI 写个 demo 页面，那这篇文章里的思路（设计 token 约束、断点检查、视觉回归）同样值得借鉴，因为这些问题跟工具无关，是 AI 前端生成的通病。

2. impeccable 的核心设计思路拆解

2.1 为什么是"CLI + Browser Extension"双形态

我一开始也疑惑，为什么不做成一个纯 CLI 工具，或者干脆做成一个 IDE 插件？后来实际用下来才明白这个设计的分寸感。

CLI 形态解决的是批量、可脚本化、可进 CI的问题。你在终端里跑impeccable check ./src，它扫描你的样式文件、组件文件，输出一份规范报告。这个形态天然适合放进 pre-commit hook 或者 CI pipeline，让每次提交都过一遍检查。对于用 Codex CLI 这类工具做自动化编码的团队来说，CLI 是唯一能无缝嵌入的方式——AI 生成代码、CLI 检查、不通过就打回，形成闭环。

Browser Extension 形态解决的是实时、可视化、所见即所得的问题。前端设计的很多问题，光看代码是看不出来的，必须渲染出来才知道。比如两个元素的实际间距、某个颜色在真实背景下的对比度、hover 状态的过渡是否生硬。浏览器扩展能直接读取渲染后的 computed style 和布局信息，这是纯静态分析做不到的。

提示：这两种形态不是二选一的关系。我的实际用法是——开发阶段用 browser extension 实时看问题，提交前用 CLI 做一次全量扫描，两者互补。

2.2 它和 ESLint / Stylelint 的本质区别

很多人第一反应是"这不就是 Stylelint 吗"。我一开始也这么想，但用下来发现定位完全不同。

Stylelint 是规则驱动的：你配置一堆规则，它告诉你哪一行违反了规则。它的强项是语法层面的一致性，比如禁止!important、强制属性顺序。但它不理解"设计意图"——它不知道你这个margin是想表达 8px 的栅格系统，还是随手写的。

impeccable 更偏向意图驱动：它试图理解你的设计系统（design tokens、间距比例、颜色语义），然后检查代码是否符合这个系统。举个具体例子，Stylelint 会告诉你"这里用了 px 而不是 rem"，但 impeccable 会告诉你"这个间距值 13px 不在你的间距比例尺（4/8/12/16/24/32）里，建议改成 12px 或 16px"。前者是语法检查，后者是设计一致性检查。

这个区别决定了它们的适用场景：Stylelint 适合所有项目，impeccable 更适合有明确设计系统的项目，或者你想让 AI 生成的前端代码自动对齐某个设计规范时。

2.3 与 AI coding agents 的协作逻辑

这是我觉得 impeccable 最有意思的地方。它不是被动地"检查"AI 生成的代码，而是可以主动地把规范"喂"给 AI。

具体机制是这样的：impeccable 会从你的项目里提取出一份"设计约束摘要"——包括你的间距比例尺、颜色 token、字体层级、断点定义。这份摘要可以以特定格式输出，然后你在给 Codex CLI 或 Zcode CLI 写 prompt 的时候，把这份摘要作为上下文传进去。这样 AI 在生成代码之前就知道"这个项目只用这几个间距值、这几个颜色"，从源头上减少违规。

我实测下来，加了这份约束摘要之后，AI 生成代码的首次通过率大概从 60% 出头提升到了 85% 左右。这个提升幅度因项目而异，但方向是明确的：与其事后检查，不如事前约束。

3. 核心细节解析与实操要点

3.1 安装与初始化：别跳过 init 这一步

impeccable 的安装本身不复杂，但初始化配置这一步很多人会跳过，然后发现检查结果全是噪音。我踩过这个坑，所以单独拎出来说。

安装方式取决于你的使用形态。CLI 形态通常通过包管理器安装，browser extension 形态则是从浏览器扩展商店获取。这里我不展开具体命令，因为不同版本可能有差异，重点说初始化。

初始化（impeccable init或类似命令）会做几件事：扫描你的项目结构，识别样式方案（是纯 CSS、Sass、Tailwind 还是 CSS-in-JS），然后生成一份配置文件。这份配置文件里最关键的是三个部分：

• 设计 token 映射：把你的实际值映射到语义化的 token 名。比如#3B82F6映射到color-primary。
• 间距比例尺：定义项目允许的间距值集合。
• 断点定义：明确项目支持的响应式断点。

注意：如果你的项目用的是 Tailwind，初始化时一定要选对模式。Tailwind 的间距体系是内置的，impeccable 需要读取tailwind.config.js才能正确理解你的比例尺，选错模式会导致所有间距检查都误报。

3.2 设计 token 的提取与对齐

这一步是整个工具的价值核心，也是最需要人工介入的地方。impeccable 能自动提取，但自动提取的结果往往需要修正。

我拿一个真实项目举例。项目里颜色值有 47 个不同的十六进制值，impeccable 自动聚类后归成了 12 个 token。但其中有 3 个聚类是错的——它把两个语义完全不同但色值接近的颜色归成了一类（比如"危险红"和"品牌红"色值只差一点点）。这种错误必须人工修正，因为语义错了，后续所有检查都会跟着错。

修正的方法是在配置文件里手动覆盖聚类结果，给每个 token 明确的语义名。这个过程大概花了我半小时，但一次性投入换来的是后续所有检查的准确性。

间距比例尺的提取相对简单，因为大部分项目的间距值本来就集中在几个数上。但有个细节要注意：行高（line-height）和间距（margin/padding）要分开处理。我见过有项目把行高也纳入间距比例尺检查，结果所有文本行高都被标记为违规，因为行高通常是无单位倍数（1.5、1.75）而不是像素值。

3.3 断点检查的配置技巧

响应式检查是 impeccable 相比纯静态工具的最大优势，但配置不当会非常吵。

默认配置下，它会检查所有已定义的断点。但实际项目里，很多断点只在特定组件上有意义。比如一个数据表格组件可能只在lg断点以上才显示完整列，在小屏上本来就是横向滚动的，你不需要它在sm断点也"完美"。

我的做法是配置组件级断点豁免。在配置文件里，针对特定组件路径，声明它只需要检查哪些断点。这样既保留了检查能力，又避免了无意义的告警。

另一个技巧是设置断点容差。真实设备的视口宽度是连续的，而断点是离散的。impeccable 默认会在断点值精确匹配时检查，但实际渲染时可能有 1-2px 的偏差。设置一个小的容差（比如 ±2px）能减少很多假阳性。

4. 实操过程与核心环节实现

4.1 用 CLI 做一次完整的前端规范扫描

我拿一个中等规模的项目走一遍完整流程，你可以对照着操作。

项目背景：React + Tailwind，大约 80 个组件，有明确的设计系统但执行得不严格。

第一步，在项目根目录运行扫描命令。输出是一份结构化报告，按严重程度分级。我拿到的第一份报告有 340 条告警，这个数字很吓人，但别慌，大部分是同一类问题。

第二步，按类别聚合看。340 条里，间距违规 210 条，颜色违规 85 条，断点问题 45 条。间距违规占了大头，这符合我的预期——Tailwind 虽然内置了间距体系，但开发者经常用任意值语法（mt-[13px]）绕过它。

第三步，处理策略。我没有逐条修，而是先看有没有批量修复的可能。impeccable 提供了自动修复功能，但我的经验是自动修复只用于低风险类别。间距值从 13px 改成 12px 是安全的，但颜色替换可能改变视觉语义，必须人工确认。

第四步，修复后重新扫描。第二轮告警降到 47 条，剩下的基本都是需要人工判断的边界情况。

整个流程走下来大概两小时，其中自动修复花了 10 分钟，人工确认花了大部分时间。这个投入是值得的，因为修复后的代码库有了统一的设计语言，后续 AI 生成代码时也有了明确的参照。

4.2 Browser Extension 的实时检查工作流

CLI 是"事后检查"，browser extension 是"事中检查"，两者的工作流完全不同。

我的日常用法是这样的：在浏览器里打开正在开发的页面，扩展会自动激活，在页面上叠加一层可视化标记。违规的元素会被高亮，鼠标悬停能看到具体问题。

这个实时反馈的价值在于缩短反馈循环。以前我改完一个组件的样式，要切到终端跑检查，再切回浏览器看效果。现在改完直接在浏览器里就能看到有没有违规，改起来快很多。

但有个坑要注意：扩展的检查是基于当前渲染状态的。如果你的页面有懒加载或者条件渲染，某些元素在初始状态下不存在，扩展就检查不到。我的做法是在检查前手动触发所有状态——展开所有折叠面板、切换到所有 tab、滚动到底部触发懒加载。这样才能拿到完整的检查结果。

另一个实用技巧是用扩展做设计走查。我会在扩展里开启"仅显示违规"模式，然后逐个页面过一遍。这比对着设计稿肉眼比对快得多，而且能发现一些肉眼容易忽略的问题，比如某个元素的对比度刚好卡在 WCAG 标准的边缘。

4.3 把 impeccable 接入 AI 编码工作流

这是我最想分享的部分，因为这才是 impeccable 区别于传统 lint 工具的核心价值。

我的工作流是这样的：在给 Codex CLI 或 Zcode CLI 写 prompt 之前，先运行 impeccable 的"约束导出"命令，生成一份当前项目的设计约束摘要。这份摘要大概长这样：

设计约束摘要 间距比例尺: 4, 8, 12, 16, 24, 32, 48, 64 颜色 token: primary(#3B82F6), danger(#EF4444), success(#10B981), ... 字体层级: xs(12px), sm(14px), base(16px), lg(18px), xl(20px), 2xl(24px) 断点: sm(640px), md(768px), lg(1024px), xl(1280px)

然后我把这份摘要作为系统提示的一部分传给 AI。实测下来，AI 生成代码时引用这些 token 的概率大幅提升，不再随手写魔法数字。

更进一步，我配置了一个 pre-commit hook：每次提交前自动跑 impeccable 检查，如果有新增违规就阻止提交。这样 AI 生成的代码在进入代码库之前就被过滤了一遍。

提示：约束摘要不要写得太长。我试过把完整的 token 列表（包括所有颜色变体）都塞进去，结果 AI 反而抓不住重点。后来精简到只保留最常用的 8-10 个 token，效果更好。

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

5.1 检查结果全是噪音怎么办

这是新手最常见的问题。我第一周用的时候，报告里 90% 都是我不关心的告警，差点放弃。

排查思路分三步。第一，确认初始化配置是否正确。大部分噪音来自配置错误，比如 Tailwind 项目没选对模式，导致所有间距都被误判。第二，检查是否有全局豁免规则没配。比如你的项目用了某个第三方组件库，它的样式你不想管，就应该把node_modules或特定路径加入豁免。第三，调整告警级别。impeccable 的告警是分级的，把不关心的类别降到 info 级别，只关注 error 和 warning。

我整理了一份常见噪音来源和对应处理方式：

5.2 自动修复改坏了代码怎么回滚

自动修复是双刃剑。我遇到过一次，自动修复把某个组件的间距从 13px 改成 12px，结果那个组件是绝对定位的，1px 的差异导致它和相邻元素重叠了。

从那以后我定了规矩：自动修复前必须确保有干净的 git 状态。这样出问题可以git diff看具体改了什么，git checkout回滚。另外，自动修复后一定要跑一遍视觉回归测试，或者至少人工过一遍关键页面。

impeccable 的自动修复支持--dry-run模式，先看会改什么再决定是否执行。这个习惯我强烈建议养成，尤其是对生产代码库操作时。

5.3 与现有 lint 工具冲突怎么处理

如果你的项目已经有 ESLint 和 Stylelint，impeccable 可能会和它们报重复的问题。我的处理原则是职责分离：

• ESLint 管 JavaScript/TypeScript 逻辑问题
• Stylelint 管 CSS 语法和属性顺序
• impeccable 管设计一致性和响应式

配置上，把 Stylelint 里和设计一致性相关的规则关掉，交给 impeccable 管。这样各司其职，不会互相打架。

5.4 大型项目的性能问题

项目大了之后，全量扫描会变慢。我那个 80 组件的项目，全量扫描要 40 秒左右。如果放进 pre-commit hook，每次提交都等 40 秒，体验很差。

解决方案是增量扫描。impeccable 支持只扫描变更的文件，配合 git 的 diff 能力，只检查本次提交涉及的文件。这样扫描时间降到 2-3 秒，完全可以接受。

配置增量扫描的关键是正确设置基准分支。我一开始设错了，导致它把整个项目都当成"变更"，性能问题依旧。正确做法是设置成main或master，然后它只检查当前分支相对基准分支的变更文件。

6. 我踩过的坑和几条实在建议

先说一个最容易被忽略的点：impeccable 的检查结果不是圣旨。它基于规则和统计，不理解你的业务上下文。我遇到过它建议把某个间距从 15px 改成 16px，但那个 15px 是设计师刻意为之，为了和旁边的图标视觉对齐。这种时候要相信自己的判断，该豁免就豁免。

第二个坑是关于 browser extension 的。扩展的检查依赖页面完全渲染，但现代前端应用大量使用懒加载和代码分割。我的建议是专门准备一个"检查模式"，在这个模式下关闭懒加载、强制渲染所有组件。这需要一点开发工作，但一次投入长期受益。

第三个坑是团队协作。impeccable 的配置文件应该进版本控制，但每个人的本地豁免可能不同。我的做法是：项目级配置进 git，个人级豁免放在.impeccable.local并加入.gitignore。这样团队共享核心规范，个人保留灵活性。

最后分享一个我觉得最有价值的用法：把 impeccable 当成 AI 编码的"验收标准"。以前我让 AI 改前端，改完自己肉眼看看觉得差不多就提交了。现在我会跑一遍 impeccable，把报告作为验收依据。这不仅是质量把关，更重要的是——当 AI 生成的代码被 impeccable 打回时，我会把具体的违规信息反馈给 AI，让它重新生成。这个"生成-检查-反馈-再生成"的循环，比单纯人工 review 效率高得多，而且 AI 在这个过程中确实在"学习"你的项目规范。

这个循环我跑了大概两个月，现在 AI 生成前端代码的首次通过率稳定在 85% 以上，剩下的 15% 也基本一两轮就能修好。这个数字比我刚开始用的时候好太多了，而其中 impeccable 提供的结构化反馈是关键的一环。