1. 从"impeccable"这个词说起：为什么前端设计需要AI编码代理来兜底

第一次看到"impeccable"被拿来命名一个开发工具，我脑子里蹦出来的不是词典释义，而是一个很具体的画面：凌晨两点，你盯着自己刚写完的页面，明明每个组件都跑通了，但整体看上去就是"差一口气"——间距忽大忽小、颜色灰度不统一、响应式断点处元素挤成一团。这种"说不上哪里错，但就是不够好"的状态，恰恰是绝大多数前端项目的真实写照。

impeccable 这个词本身的意思是"无可挑剔的、完美的"，把它用在 AI coding agents 和 frontend design 的交叉领域，指向的其实是一个非常明确的诉求：让 AI 编码代理不只是把功能写出来，而是把界面做到经得起挑剔。这跟过去几年我们习惯的"AI 帮我补全代码"完全是两个层次的事情。补全代码解决的是"能不能跑"，而 impeccable 这类工具想解决的是"跑起来之后好不好看、合不合理、符不符合设计规范"。

从关键词组合来看——AI coding agents、frontend design、CLI、browser extension——这明显是一个横跨命令行和浏览器两端的工作流工具。CLI 负责在开发环节介入，browser extension 负责在预览和调试环节介入，中间靠 AI coding agents 做设计决策和代码生成。这个组合不是随便拼的，它对应的是前端开发里最割裂的两个场景：写代码的时候在编辑器/终端里，看效果的时候在浏览器里。传统工具要么只管一头，要么两头的数据对不上，而 impeccable 想做的显然是打通这条链路。

适合读这篇内容的人，我大致分三类：第一类是已经在用 codex cli、claude code 这类 AI 编码工具，但发现生成的前端代码"能用不好看"的开发者；第二类是做设计系统、组件库，想让 AI 帮忙守住设计规范的团队；第三类是对 CLI + browser extension 这种双端工作流感兴趣，想搞清楚它到底怎么落地的人。不管你是哪一类，下面这些内容都是围绕"impeccable 这类工具在实际项目里怎么用、坑在哪、怎么绕"来展开的，不是产品说明书，是我自己趟过一遍之后的经验整理。

2. impeccable 到底在解决前端设计的哪个环节

2.1 前端"不够好"的三种典型症状

要理解 impeccable 的价值，得先看清楚它瞄准的痛点。我把前端设计里最常见的"不够好"归纳成三种症状，这三种在 AI 生成代码的场景下会被放大。

第一种是视觉一致性崩塌。AI 生成组件的时候，每个组件单独看都没问题，但放到一起就露馅：按钮的圆角有的是 6px 有的是 8px，卡片的阴影有的是0 2px 4px有的是0 4px 8px，文字颜色在#333和#2c2c2c之间反复横跳。人写代码会累、会偷懒，AI 写代码则是"每次重新决策"，没有全局记忆，所以一致性问题反而更严重。

第二种是响应式逻辑缺失。AI 很擅长写一个在 1440px 下完美的布局，但一到 768px 或者 375px 就原形毕露。它不会主动去想"这个三栏布局在手机上应该变成什么"，除非你明确告诉它。而 impeccable 这类工具的一个核心能力，就是在生成阶段就把断点逻辑纳入考量。

第三种是可访问性被忽略。对比度不够、缺少 focus 状态、语义化标签乱用——这些问题在人工 review 时都容易被放过，AI 生成时更是默认不会管。但恰恰是这些细节，决定了一个界面是"能看"还是"无可挑剔"。

2.2 CLI 端和 browser extension 端各自承担什么角色

impeccable 的工作流拆成两端，这个设计我觉得是它最聪明的地方。CLI 端负责的是生成和约束：你在终端里调用它，它读取你的项目配置、设计 token、组件规范，然后驱动 AI coding agent 生成符合规范的代码。这里的"约束"是关键——它不是让 AI 自由发挥，而是给 AI 套上一个设计系统的笼子。

browser extension 端负责的是检查和反馈。代码写完了，在浏览器里跑起来，extension 会实时扫描当前页面，把不符合规范的地方标出来：这个间距不在你的 spacing scale 里、这个颜色不在你的 palette 里、这个元素的对比度只有 3.2:1 达不到 AA 标准。更关键的是，这些反馈可以回流到 CLI 端，形成闭环。

我实测下来，这个双端设计的价值在于把"设计 review"从人工变成了半自动。以前你要么靠设计师肉眼盯，要么靠 Storybook 里一个个组件翻，效率极低。现在 extension 直接在真实页面上扫，CLI 直接根据扫描结果改代码，中间省掉了大量来回沟通。

2.3 和纯 prompt 驱动的 AI 编码有什么本质区别

很多人会问：我用 codex cli 直接写 prompt 让它生成前端代码，不也一样吗？区别在于约束的来源。

纯 prompt 驱动的情况下，约束来自你每次写的提示词。你这次说"用 8px 圆角"，下次忘了说，AI 就给你 12px。约束是临时的、易失的、依赖记忆的。

impeccable 这类工具把约束外化成了配置文件。你的设计 token、间距体系、颜色规范、断点定义，全部写在一个地方，AI 每次生成都读这个配置。约束是持久的、可版本控制的、团队共享的。这个区别看起来小，但在多人协作的项目里是决定性的——它意味着设计规范不再靠"口口相传"和"代码 review 时抓"，而是靠工具强制执行。

3. 把 impeccable 跑起来：环境准备里那些没人告诉你的细节

3.1 安装前的依赖检查清单

在动手装之前，有几项依赖必须先确认，否则后面会卡在莫名其妙的地方。我踩过的坑基本都集中在这一步。

首先是 Node 版本。impeccable 这类 CLI 工具通常要求 Node 18 以上，部分功能依赖 Node 20 的原生 fetch 和新的模块解析逻辑。如果你机器上还是 Node 16，先升级，别想着凑合。用node -v确认，低于 18 直接去装 nvm 或者 fnm 管理多版本。

其次是包管理器的一致性。如果你的项目用 pnpm，全局 CLI 也尽量用 pnpm 装；混用 npm 和 pnpm 会导致依赖树解析不一致，CLI 读不到项目里的配置文件。这个坑我在一个 monorepo 项目里踩过，排查了两个小时才发现是包管理器混用。

第三是浏览器扩展的加载方式。browser extension 端通常需要开发者模式手动加载，Chrome 和 Edge 的加载路径不一样，Firefox 又是另一套。如果你团队里有人用 Safari，那基本可以放弃扩展端，只能走 CLI 单端流程。

3.2 配置文件的结构与字段含义

impeccable 的核心是一份配置文件，通常叫impeccable.config.json或者嵌在package.json里。这份文件决定了 AI 生成代码时遵守什么规则。我把它拆成几个关键字段来讲。

designTokens字段是重中之重。这里定义你的颜色、间距、字号、圆角、阴影等基础变量。写法上建议直接引用你现有的设计系统，比如从 Tailwind config 或者 CSS 变量里同步过来，避免维护两份。

breakpoints字段定义响应式断点。这里有个细节：不要只写断点数值，还要写每个断点下的布局策略。比如mobile: { maxWidth: 768, layout: 'stack' }，告诉 AI 在移动端应该堆叠而不是并排。

rules字段是约束规则。可以定义"禁止使用 magic number"、"所有颜色必须来自 palette"、"交互元素必须有 focus 状态"这类硬性规则。规则写得越具体，AI 生成的结果越可控。

agent字段指定用哪个 AI coding agent 来驱动。这里就涉及到 codex cli、claude code 这些工具的选择了，后面单独讲。

3.3 第一次运行时的验证方法

装完之后别急着上真实项目，先拿一个最小 demo 验证链路通不通。我的做法是建一个空目录，放一个最简单的 HTML 文件，然后跑 CLI 的初始化命令。

验证分三步：第一步，CLI 能不能正确读取配置文件，跑impeccable validate看有没有报错；第二步，AI agent 能不能被正确调用，跑一个生成命令看有没有输出；第三步，browser extension 能不能连上本地开发服务器，打开页面看扩展图标有没有亮。

这三步任何一步失败，都别往下走。我见过太多人跳过验证直接上项目，结果生成了一堆代码发现配置根本没生效，白忙活。

提示：第一次运行时建议把 AI agent 的日志级别调到 debug，这样能看到它到底读了哪些配置、做了什么决策。默认的 info 级别会把这些细节藏起来，出问题时很难排查。

4. 让 AI coding agent 真正理解设计意图的配置技巧

4.1 设计 token 的粒度怎么把握

设计 token 的粒度是个需要反复权衡的问题。太粗，AI 没有足够约束，生成的东西还是五花八门；太细，配置文件膨胀到没人愿意维护，而且 AI 读取时容易抓不住重点。

我的经验是三层粒度：第一层是原子 token，比如具体的颜色值、间距值；第二层是语义 token，比如primary-button-bg、card-padding；第三层是组件 token，比如product-card的完整样式组合。AI 生成时优先匹配组件 token，匹配不到再往下找语义 token，最后才用原子 token。

这样设计的好处是，改一个组件样式只需要改组件 token，不用动底层。而且 AI 在生成新组件时，会优先复用已有的组件 token，天然保证了风格一致。

4.2 用规则文件约束 AI 的自由发挥

光有 token 还不够，AI 还是会在 token 之外"自由发挥"。这时候需要规则文件来兜底。规则文件我一般写三类内容。

第一类是禁止项。明确告诉 AI 不许做什么，比如"禁止使用行内 style"、"禁止硬编码颜色值"、"禁止使用!important"。这些禁止项要写得斩钉截铁，不要用"尽量避免"这种模糊表述，AI 对模糊表述的理解很不稳定。

第二类是强制项。比如"所有图片必须有 alt 属性"、"所有表单元素必须有关联的 label"、"所有交互元素必须有 hover 和 focus 状态"。这些是底线，必须强制执行。

第三类是偏好项。比如"优先使用 flex 而非 grid"、"优先使用语义化标签"。这类不是硬性要求，但写上能让生成结果更符合团队习惯。

4.3 多 agent 协作时的配置隔离

如果你同时用 codex cli 和 claude code，或者团队里有人用不同的 agent，配置隔离就很重要。不同 agent 对配置的理解能力不一样，有的能读复杂嵌套的 JSON，有的只认扁平结构。

我的做法是为每个 agent 准备一份适配后的配置。主配置维护一份，然后用脚本生成各 agent 的适配版本。这样主配置是唯一真相源，适配版本自动生成，不会出现"改了主配置忘了改适配版"的问题。

另外，不同 agent 的 prompt 风格也不一样。codex cli 偏向简洁指令，claude code 对上下文更敏感。在配置里可以针对不同 agent 写不同的 prompt 模板，让每个 agent 都发挥出最佳效果。

5. browser extension 端的实时校验与反馈闭环

5.1 扩展如何扫描页面并识别设计偏差

browser extension 端的核心能力是实时扫描。它做的事情本质上是把页面上每个元素的 computed style 抓出来，然后跟你的设计 token 做比对。比对逻辑分几层。

第一层是精确匹配。元素的颜色值、间距值、字号是否精确等于某个 token。这一层最容易实现，也最容易出误报——因为浏览器计算出来的值经常是rgb()格式，而你的 token 可能是 hex，需要做格式归一化。

第二层是范围匹配。有些属性不要求精确等于某个 token，而是要求落在某个范围内。比如对比度要求大于 4.5:1，间距要求是 4 的倍数。这一层需要写更复杂的校验逻辑。

第三层是语义匹配。这一层最难，需要理解元素的语义角色。比如一个按钮，它应该有 hover 状态、focus 状态、disabled 状态，这些不是从 computed style 能直接看出来的，需要结合 DOM 结构和交互状态判断。

5.2 从扫描结果到代码修改的闭环路径

扫描出问题只是第一步，关键是能不能闭环到代码修改。impeccable 的闭环路径大致是：extension 扫描出偏差 → 生成一份偏差报告 → CLI 读取报告 → AI agent 根据报告修改代码 → 重新扫描验证。

这个闭环里最容易断的是偏差报告到代码位置的映射。extension 知道是哪个 DOM 元素有问题，但不知道这个元素对应源码里的哪一行。解决这个问题通常靠 source map，或者靠给元素加>