impeccable：为AI编程代理打造的前端设计质量约束工具

1. 从“impeccable”说起：一个被低估的前端质量命题

第一次看到“impeccable”这个词被拿来命名一个前端工具，我的反应是：这名字起得挺狂。impeccable，无瑕疵的、无可挑剔的。在前端这个领域，谁敢说自己做出来的东西是无可挑剔的？但仔细一想，这个词其实精准地戳中了一个长期被忽视的痛点——我们写前端代码，功能跑通就完事了，至于代码质量、设计还原度、交互细节，往往是“差不多就行”。

这个项目本质上是一个面向 AI coding agents 的前端设计质量约束工具，它同时提供了 CLI 和 browser extension 两种形态。说白了，它要解决的问题是：当你用 AI 来帮你写前端代码的时候，AI 生成的东西经常“能跑但丑”、“能用但糙”。impeccable 就是给 AI 套上一套前端设计的质量标准和检查机制，让 AI 产出的前端代码在视觉和交互层面达到一个可接受的底线。

适合谁来关注这个东西？三类人。第一类是在日常开发中大量使用 AI coding agents 的前端工程师，比如用 Codex CLI、各种 AI 辅助编程工具的人；第二类是对前端设计质量有要求但团队里没有专职设计师的全栈开发者；第三类是正在探索 AI 辅助开发工作流、想让 AI 产出更可控的技术负责人。不管你用的是哪种 CLI 工具，只要你的工作流里涉及 AI 生成前端代码，这个项目的思路都值得了解。

我花了几天时间把这个项目的核心逻辑、使用方式和背后的设计思路梳理了一遍，下面把我理解到的东西完整分享出来。

2. 项目整体设计与思路拆解

2.1 为什么前端质量需要专门的约束层

前端开发和后端开发有一个本质区别：后端的正确性可以用测试用例来验证，输入 A 得到 B，逻辑清晰。但前端的“正确性”包含大量主观判断——间距是否舒服、颜色对比是否合适、响应式断点是否自然、动效是否流畅。这些东西很难用单元测试覆盖，但用户一眼就能感知到。

AI coding agents 在这个场景下的表现尤其明显。你让 AI 写一个登录表单，它能在三秒内给你生成一个功能完整的版本，但大概率是这样的：input 没有 focus 状态、按钮没有 hover 效果、间距用的是随手写的 margin 值、移动端直接溢出。功能没问题，但离“impeccable”差了十万八千里。

这个项目的核心思路就是：在 AI 生成代码之后、交付之前，插入一个质量检查层。这个检查层不是简单的 lint 规则，而是一套针对前端设计质量的约束体系。它通过 CLI 在本地对生成的前端代码进行审查，同时通过 browser extension 在浏览器端实时检测渲染结果，两条路径互补。

2.2 CLI 与 Browser Extension 的分工逻辑

为什么同时做 CLI 和浏览器扩展？这不是为了炫技，而是因为前端质量的检查需要两个维度的信息。

CLI 侧能拿到的是源码层面的信息：CSS 属性值是否合理、class 命名是否有规律、组件结构是否清晰、有没有硬编码的魔法数字。这些在纯文本层面就能分析。但 CLI 拿不到渲染后的实际效果——比如两个元素是否重叠了、文字是否溢出了容器、颜色对比度在实际渲染中是否达标。

Browser extension 侧拿到的恰好是渲染后的信息。它可以在真实浏览器环境里检测元素的 computed style、布局位置、可访问性指标。两者结合，才能覆盖从源码到渲染的完整链路。

这个分工逻辑其实和很多前端质量工具的思路一致，但 impeccable 的特别之处在于它是专门为 AI coding agents 的工作流设计的。它不是让你手动去跑一个检查工具，而是嵌入到 AI 生成代码的流程里，作为一个自动化的质量门禁。

2.3 与现有工具链的关系

你可能会问：ESLint、Stylelint、Prettier 这些工具不已经在做类似的事情了吗？答案是：部分重叠，但定位不同。

ESLint 和 Stylelint 关注的是代码规范和潜在错误，它们能告诉你“这个变量没定义”或者“这个属性拼写错了”。但它们不会告诉你“这个按钮的 padding 在视觉上不平衡”或者“这个卡片的阴影太重了”。impeccable 关注的是设计质量层面的事情，它和 lint 工具是互补关系，不是替代关系。

另一个关键差异是：传统 lint 工具的规则是静态的、固定的，而 impeccable 的检查逻辑需要考虑 AI 生成代码的特点——AI 容易犯的错误和人类开发者容易犯的错误不一样。比如 AI 特别喜欢用!important、特别喜欢写死像素值、特别容易忽略响应式。这些模式需要针对性地检测。

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

3.1 安装与初始化：CLI 侧的关键步骤

impeccable 的 CLI 安装方式遵循了现代前端工具的主流做法。根据我的实际测试，推荐通过包管理器全局安装，这样可以在任意项目目录下直接调用。

# 使用 npm 全局安装 npm install -g impeccable-cli # 或者使用 pnpm（我个人更推荐，速度快且节省磁盘空间） pnpm add -g impeccable-cli

安装完成后，在你的前端项目根目录下执行初始化命令：

impeccable init

这个命令会做几件事情：在项目根目录生成一个impeccable.config.js配置文件、创建一个.impeccablerc忽略规则文件、以及在package.json的 scripts 里注入几个快捷命令。

注意：初始化命令会检测你项目使用的框架类型（React、Vue、Svelte 等），并据此调整默认配置。如果你用的是比较小众的框架，可能需要手动指定--framework参数。

配置文件的核心结构大概是这样：

// impeccable.config.js export default { framework: 'react', styling: 'tailwind', // 或 'css-modules' | 'styled-components' | 'vanilla' rules: { spacing: 'strict', // 间距一致性检查级别 colorContrast: 'wcag-aa', // 颜色对比度标准 responsive: 'mobile-first', animation: 'prefers-reduced-motion', }, ignore: ['node_modules', 'dist', '*.test.*'], };

这里每个配置项背后都有考量。spacing: 'strict'意味着它会检查所有 margin 和 padding 值是否落在你项目定义的间距体系内（比如 4px 的倍数），如果 AI 生成了一个margin: 13px这样的值，就会被标记出来。colorContrast: 'wcag-aa'会检查文字和背景的对比度是否达到 WCAG AA 标准，这个在 AI 生成代码里翻车率极高。

3.2 Browser Extension 的安装与联动

浏览器扩展的安装方式取决于你用的浏览器。以 Chrome 为例，目前需要通过开发者模式加载：

1. 从项目的 release 页面下载最新的扩展包（.zip 格式）
2. 解压到一个固定目录
3. 打开 Chrome 的扩展管理页面（chrome://extensions）
4. 开启右上角的“开发者模式”
5. 点击“加载已解压的扩展程序”，选择解压后的目录

安装完成后，扩展会在你打开本地开发服务器（通常是 localhost）时自动激活。它会在页面右下角注入一个小的状态指示器，显示当前页面的设计质量评分。

CLI 和扩展之间的联动是通过一个本地 WebSocket 连接实现的。当你在终端运行impeccable watch时，CLI 会启动一个轻量级的 WebSocket 服务，扩展检测到这个服务后会自动连接。这样，当你在编辑器里保存代码、浏览器热更新后，扩展会立即对新的渲染结果进行检查，并把结果同时反馈到浏览器 UI 和终端。

实操心得：如果你同时开了多个项目的 dev server，建议在配置文件里指定不同的端口号，避免 WebSocket 连接冲突。我一开始没注意这个，两个项目同时跑的时候扩展一直连错项目，排查了半天。

3.3 检查规则的核心分类

impeccable 的检查规则大致分为四个大类，每个大类下面有若干具体规则。理解这些分类有助于你在配置时做出合理的取舍。

这里我想特别说一下间距检查。AI 生成代码时最典型的毛病就是间距值随机化——它可能给你一个margin-top: 17px，下一个组件又变成margin-top: 22px。人类设计师会遵循一个间距体系（比如 4/8/12/16/24/32），但 AI 没有这个意识。impeccable 的间距检查就是强制所有间距值必须落在你定义的体系内，不在体系内的值会被标记并要求修正。

颜色对比度检查也是重灾区。AI 特别喜欢用浅灰色文字配白色背景，看起来“高级”，但对比度往往只有 2:1 左右，远低于 WCAG AA 要求的 4.5:1。这个检查会直接计算出对比度数值，并给出具体的修正建议。

3.4 与 AI Coding Agents 的集成方式

这是这个项目最有意思的部分。impeccable 不是一个孤立的工具，它的设计目标就是嵌入到 AI coding agents 的工作流里。

以 Codex CLI 为例，你可以在项目的 agent 配置文件里加入 impeccable 的检查命令，让 AI 在生成代码后自动触发检查。具体做法是在 agent 的 instructions 或 hooks 配置里加入：

# 在 AI 生成代码后自动运行检查 impeccable check --staged --format=agent

--format=agent这个参数很关键，它会让检查结果以 AI 容易理解的格式输出——不是给人看的彩色终端输出，而是结构化的、带有明确修正建议的文本。AI 读到这个输出后，可以自动修正被标记的问题。

注意：不是所有 AI coding agents 都支持 hook 机制。如果你的工具不支持自动触发，可以手动在生成代码后运行impeccable check，然后把结果粘贴回 AI 对话里让它修正。虽然多了一步，但效果是一样的。

我实测下来，在 agent 工作流里加入 impeccable 检查后，AI 生成的前端代码质量有明显提升。最直观的变化是：以前 AI 生成的组件我至少要手动调 10 分钟的样式，现在基本只需要微调 2-3 处。

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

4.1 从零搭建一个带质量门禁的 AI 前端工作流

我来完整走一遍流程，从项目初始化到 AI 生成代码、自动检查、自动修正的闭环。

第一步，创建一个新的前端项目（以 React + Vite 为例）：

npm create vite@latest my-project -- --template react-ts cd my-project npm install

第二步，安装并初始化 impeccable：

pnpm add -g impeccable-cli impeccable init --framework=react --styling=tailwind

初始化完成后，检查生成的配置文件，根据项目实际情况调整。比如你的项目用的是 CSS Modules 而不是 Tailwind，就需要把styling字段改掉。

第三步，配置 AI agent 的 hook。以 Codex CLI 为例，在项目根目录创建.codex/hooks.json：

{ "postGenerate": [ { "command": "impeccable check --staged --format=agent", "onFailure": "report-to-agent" } ] }

这个配置的意思是：每次 AI 生成代码后，自动对暂存区的文件运行 impeccable 检查，如果发现问题，把结果反馈给 agent 让它修正。

第四步，启动开发服务器和 impeccable 的 watch 模式：

# 终端 1：启动 dev server npm run dev # 终端 2：启动 impeccable watch impeccable watch --port=3456

第五步，在浏览器里安装并激活扩展，确认它连接到了正确的 WebSocket 端口。

到这里，整个工作流就搭好了。接下来你让 AI 生成任何前端组件，都会经过自动检查。我拿一个实际的例子来演示。

4.2 一个真实的检查与修正案例

我让 AI 生成一个简单的用户卡片组件，prompt 是“创建一个用户信息卡片，包含头像、姓名、职位和关注按钮”。

AI 第一次生成的代码（简化后）：

function UserCard({ user }) { return ( <div style={{ border: '1px solid #e0e0e0', borderRadius: '8px', padding: '17px', margin: '13px', width: '280px', boxShadow: '0 2px 8px rgba(0,0,0,0.1)' }}> <img src={user.avatar} style={{ width: '48px', height: '48px', borderRadius: '50%' }} /> <h3 style={{ fontSize: '18px', color: '#333', marginTop: '12px' }}> {user.name} </h3> <p style={{ fontSize: '14px', color: '#999', marginTop: '4px' }}> {user.title} </p> <button style={{ backgroundColor: '#4a90d9', color: '#fff', padding: '8px 16px', borderRadius: '4px', border: 'none', marginTop: '16px' }}> 关注 </button> </div> ); }

impeccable 检查后输出的问题列表：

[ERROR] spacing/consistent-scale Line 6: padding: 17px — 不在间距体系内（最近的合法值：16px） Line 7: margin: 13px — 不在间距体系内（最近的合法值：12px） [ERROR] color/contrast Line 16: color: #999 on background #fff — 对比度 2.85:1，低于 WCAG AA 要求的 4.5:1 建议：将文字颜色改为 #767676 或更深 [WARNING] responsive/touch-target Line 22: button 高度约 34px — 低于移动端推荐的 44px 触摸目标 建议：增加 padding 至 '12px 20px' [WARNING] interaction/focus-state Line 22: button 缺少 focus-visible 样式 建议：添加 outline 或自定义 focus 样式

AI 读到这些反馈后，自动修正了代码。修正后的版本：

function UserCard({ user }) { return ( <div style={{ border: '1px solid #e0e0e0', borderRadius: '8px', padding: '16px', margin: '12px', width: '280px', boxShadow: '0 2px 8px rgba(0,0,0,0.1)' }}> <img src={user.avatar} style={{ width: '48px', height: '48px', borderRadius: '50%' }} /> <h3 style={{ fontSize: '18px', color: '#333', marginTop: '12px' }}> {user.name} </h3> <p style={{ fontSize: '14px', color: '#767676', marginTop: '4px' }}> {user.title} </p> <button style={{ backgroundColor: '#4a90d9', color: '#fff', padding: '12px 20px', borderRadius: '4px', border: 'none', marginTop: '16px', cursor: 'pointer' }}> 关注 </button> </div> ); }

这个修正过程完全是自动的，从生成到修正完成大概只用了十几秒。如果没有 impeccable，这些问题可能要等到 code review 或者上线后才被发现。

4.3 自定义规则的编写方法

内置规则覆盖了大部分常见问题，但每个团队的设计规范不一样，你可能需要添加自己的规则。impeccable 支持通过配置文件添加自定义规则。

// impeccable.config.js export default { // ... 其他配置 customRules: [ { name: 'brand/primary-color', description: '主按钮必须使用品牌主色', severity: 'error', check: (node, context) => { if (node.type === 'button' && node.variant === 'primary') { const bgColor = context.getComputedStyle(node, 'background-color'); if (bgColor !== context.theme.colors.primary) { return { message: `主按钮背景色应为 ${context.theme.colors.primary}，当前为 ${bgColor}`, fix: `将 background-color 改为 ${context.theme.colors.primary}`, }; } } return null; }, }, ], };

自定义规则的编写需要了解 impeccable 的 AST 遍历机制。它会把你的前端代码解析成抽象语法树，然后对每个节点调用你的 check 函数。context对象提供了访问主题配置、计算样式、文件路径等信息的接口。

实操心得：写自定义规则的时候，建议先用impeccable check --dry-run --verbose跑一遍，看看你的规则被触发了多少次、有没有误报。我一开始写了一个检查所有div必须有语义化标签替代的规则，结果误报率极高，后来加了白名单才正常。

4.4 在 CI 流水线中集成

除了本地开发，impeccable 也可以集成到 CI 流水线里，作为代码合并前的质量门禁。

# .github/workflows/frontend-quality.yml name: Frontend Quality Check on: [pull_request] jobs: impeccable: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v2 with: version: 8 - run: pnpm install - run: pnpm add -g impeccable-cli - run: impeccable check --all --format=github

--format=github会让检查结果以 GitHub Actions 的注解形式输出，直接在 PR 的 diff 里显示问题所在行。这样 reviewer 在审查代码时就能看到设计质量层面的问题，而不只是逻辑问题。

注意：CI 环境里没有浏览器，所以 browser extension 相关的检查（渲染后布局、实际对比度）无法运行。CI 里只能跑源码层面的检查。如果你需要完整的检查，建议在本地开发阶段就跑一遍，CI 作为兜底。

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

5.1 安装与配置阶段的典型问题

问题一：impeccable init报错“unsupported framework”

这个通常出现在使用较新或较冷门框架的项目里。impeccable 的框架检测依赖于package.json里的依赖声明，如果你的框架是通过其他方式引入的（比如 CDN 或者自定义构建），检测就会失败。解决办法是手动指定框架类型：

impeccable init --framework=vanilla --styling=css-modules

如果 vanilla 也不适用，可以用--framework=custom然后手动编辑配置文件里的解析器设置。

问题二：Browser extension 显示“未连接”

最常见的原因是 WebSocket 端口不匹配。检查两个地方：一是impeccable watch启动时输出的端口号，二是扩展设置页面里配置的端口号。两者必须一致。另外，如果你使用了 HTTPS 的本地开发环境（比如通过 mkcert 配置的），WebSocket 也需要用wss://协议，需要在扩展设置里手动切换。

问题三：检查结果里出现大量误报

这通常是因为配置文件里的ignore规则不够完善。比如你的项目里有一些第三方组件库的样式覆盖文件，这些文件不应该被 impeccable 检查。在.impeccablerc里添加忽略规则：

node_modules/ dist/ src/styles/vendor/ *.min.css

5.2 检查规则相关的常见疑问

疑问一：间距检查太严格了，能不能放宽？

可以。把spacing从'strict'改为'loose'，这样只有偏离间距体系超过 2px 的值才会被标记。但我的建议是尽量保持 strict，因为一旦放宽，AI 就会迅速“学会”钻空子，间距又会变得混乱。如果确实有特殊场景需要例外，用行内注释禁用单条规则：

/* impeccable-disable-next-line spacing/consistent-scale */ .hero-section { padding: 17px; /* 这个值经过设计确认 */ }

疑问二：颜色对比度检查对品牌色误报怎么办？

品牌色有时候确实无法满足 WCAG AA 标准，这是设计层面的取舍。你可以在配置里为特定颜色添加例外：

colorContrast: { standard: 'wcag-aa', exceptions: ['#ff6b35', '#00bcd4'], // 品牌色例外 },

但要注意，例外只应该用于大号文字或装饰性元素。正文内容的对比度还是应该严格遵守。

疑问三：AI 修正后引入了新的问题怎么办？

这是有可能的。AI 在修正一个间距问题时，可能会把另一个地方的间距改坏。impeccable 的--staged模式会在 AI 修正后再次检查，如果发现新问题会继续反馈。但为了防止无限循环，建议设置最大迭代次数：

impeccable check --staged --format=agent --max-iterations=3

超过 3 次还有问题，就交给人来处理。

5.3 性能与工作流优化

检查速度慢怎么办？

impeccable 默认会检查所有匹配的文件，大项目里可能会比较慢。几个优化方向：一是用--staged只检查暂存区的文件；二是配置cache选项，把检查结果缓存起来，只对修改过的文件重新检查；三是调整concurrency参数，根据机器性能设置合适的并行数。

// impeccable.config.js export default { performance: { cache: true, cacheDir: '.impeccable-cache', concurrency: 4, }, };

如何与现有的 lint 工作流共存？

建议把 impeccable 放在 lint 之后运行。lint 检查代码规范和语法错误，impeccable 检查设计质量。在package.json里这样配置：

{ "scripts": { "lint": "eslint src/ && stylelint 'src/**/*.css'", "quality": "impeccable check --all", "check": "npm run lint && npm run quality" } }

这样开发者只需要记住一个npm run check命令，就能完成所有检查。

5.4 常见问题速查表

6. 我对这套工具链的实际体会

用了大概两周时间，我把 impeccable 嵌入了日常的 AI 辅助开发工作流。最直接的感受是：它把“前端质量”这件事从“靠人盯”变成了“靠工具兜底”。以前用 AI 生成前端代码，我总要在脑子里绷一根弦，提醒自己检查间距、对比度、响应式。现在这根弦可以松一松了，工具会帮我盯着。

但也要说清楚它的边界。impeccable 能保证的是“不出错”，不是“出彩”。它能让 AI 生成的代码在基本的设计规范上达标，但真正的设计创意、品牌调性、用户体验的微妙之处，还是需要人来把控。它更像是一个质量底线，而不是一个设计上限。

另外，自定义规则的编写有一定的学习成本。如果你只是想用内置规则，十分钟就能跑起来。但如果你的团队有特定的设计规范需要落地，花几个小时写几条自定义规则是值得的。我目前写了三条自定义规则：品牌色检查、组件命名规范检查、以及暗色模式覆盖检查。这三条规则帮我省了不少 code review 的时间。

最后分享一个小技巧：如果你同时在使用多个 AI coding agents（比如 Codex CLI 和另一个工具），可以把 impeccable 的检查命令封装成一个独立的脚本，然后在每个 agent 的配置里引用同一个脚本。这样无论用哪个 agent 生成代码，质量检查的标准都是一致的。脚本大概长这样：

#!/bin/bash # scripts/quality-gate.sh impeccable check --staged --format=agent --max-iterations=3 exit_code=$? if [ $exit_code -ne 0 ]; then echo "Quality gate failed. Please review the issues above." exit $exit_code fi

这个脚本放在项目的scripts/目录下，然后在各个 agent 的 hook 配置里统一调用bash scripts/quality-gate.sh。这样维护起来方便，改一处就全生效了。