1. 从"impeccable"这个词说起：一个被低估的前端质量信号

第一次看到"impeccable"作为项目名，我下意识去查了这个词的本义——无可挑剔的、零瑕疵的。放在前端设计和 AI coding agents 的语境里，这个词其实点出了一个很尖锐的问题：当 AI 能帮你把代码写出来之后，谁来保证它写出来的东西是"无可挑剔"的？

过去一年我一直在用各种 CLI 工具配合 AI 编码代理做前端项目，从 codex cli 到各类 agent 工具链，踩过的坑比写过的组件还多。最典型的场景是这样的：你让 AI 生成一个登录表单，它三秒钟给你吐出来两百行 JSX，结构完整、逻辑通顺，但你把浏览器一开——间距是乱的，焦点态没有，移动端直接溢出，无障碍属性一个没有。代码"能跑"，但离"impeccable"差了十万八千里。

这就是我想在这篇里聊清楚的核心：impeccable 代表的不是某个具体工具，而是一套前端质量的验收标准，以及如何用 CLI 和浏览器扩展把 AI 生成的前端代码从"能跑"拉到"无可挑剔"。它适合三类人：一是正在用 AI coding agents 做前端但总在收尾阶段返工的开发者；二是想建立一套自动化前端质量门禁的团队；三是刚接触 CLI 工具链、想知道这些命令行工具到底能帮上什么忙的新手。

我下面会从实际工作流出发，把"AI 写前端"这件事拆成几个可控的环节，每个环节告诉你用什么工具、为什么这么选、以及我踩过的具体坑。不堆概念，只讲能直接抄作业的东西。

2. AI coding agents 写前端的真实短板在哪里

2.1 为什么 AI 生成的界面总是"差一口气"

先说结论：AI coding agents 在前端领域的短板，不在"写不出来"，而在"写不完整"。它擅长的是结构化的、有明确模式的代码——一个卡片组件、一个列表渲染、一个表单提交逻辑，这些它闭着眼都能写。但它天然缺失三样东西。

第一是视觉反馈闭环。AI 看不到渲染结果，它只能根据训练数据里的"常见写法"来推断样式。你让它写一个padding: 16px，它不知道在你的设计系统里这个值应该是12px还是20px，更不知道这个间距在 375px 宽的屏幕上会不会挤成一团。它没有眼睛。

第二是状态覆盖的完整性。人类开发者写组件时会本能地想到 hover、focus、active、disabled、loading、error、empty 这些状态，因为我们在浏览器里见过太多次"忘了写 focus 样式导致键盘用户完全没法用"的惨案。AI 默认只写 happy path，也就是"数据正常、交互正常"的那一条路径。

第三是跨断点的连续性。响应式设计本质上是一组约束条件下的连续函数，AI 更倾向于把它当成几个离散的断点来写，结果就是 768px 到 1024px 之间经常出现诡异的布局跳变。

提示：判断一个 AI 生成的前端组件是否合格，最快的办法不是读代码，而是把它丢进浏览器，然后用键盘 Tab 键走一遍，再缩放到 320px 宽度看一眼。这两个动作能暴露 80% 的问题。

2.2 CLI 工具链在其中的角色定位

那 CLI 工具在这里扮演什么角色？我的理解是：CLI 是把"人的验收标准"翻译成"机器可执行的检查"的桥梁。

你不可能每次都手动去点一遍所有状态，但你可以用命令行工具把这件事自动化。比如用 codex cli 这类工具生成代码之后，紧接着跑一条 lint 命令、一条无障碍检查命令、一条视觉回归命令，把不合格的产物直接拦在提交之前。这就是 CLI 的价值——它让"impeccable"从一个主观形容词变成一组可量化的通过/不通过。

我实际用下来，一个比较顺的工作流是这样的：

1. 用 AI agent 生成组件初稿
2. 立刻跑静态检查（ESLint + Stylelint）
3. 跑无障碍扫描（axe 类工具）
4. 在浏览器里做视觉确认
5. 有问题就带着具体报错回到 agent 让它修

这个循环里，第 2、3 步完全可以在 CLI 里完成，第 4 步可以借助浏览器扩展辅助。关键在于不要让 AI 一次性写完整个页面再验收，而是小步快跑，每生成一个组件就过一遍检查。

2.3 一个反直觉的观察：约束越强，AI 表现越好

这里分享一个我反复验证过的经验：你给 AI 的约束越具体、越机械化，它生成的前端代码质量越高。

很多人用 AI 写前端的方式是"帮我写一个漂亮的登录页"，这种模糊指令得到的结果往往很平庸。但如果你换成"用我们项目现有的 Button 和 Input 组件，按照 design token 里的 spacing-3 和 radius-2，写一个包含邮箱、密码、记住我、提交按钮的登录表单，所有交互元素必须有可见的 focus ring"，结果会好非常多。

原因很简单：AI 不缺生成能力，缺的是边界。CLI 工具链和浏览器扩展的作用，本质上就是在给它划定边界——哪些规则必须遵守，哪些检查必须通过。当你把 impeccable 的标准前置成约束，而不是后置成验收，整个流程的效率会有质的变化。

3. 搭建一套可复现的前端质量检查流水线

3.1 环境准备：别在工具安装上浪费时间

先把基础环境理清楚。我假设你本地已经有 Node.js 环境（建议 18 以上），包管理器用 pnpm 或 npm 都行，我个人偏好 pnpm 因为装依赖快。

核心要装的几类工具：

安装命令大致是这样：

pnpm add -D eslint prettier stylelint stylelint-config-standard @axe-core/cli playwright typescript

这里有个坑要提前说：axe-core CLI 需要浏览器驱动，第一次跑的时候它会去下载 Chromium，国内网络环境下这一步经常卡住。我的做法是提前用 Playwright 把浏览器装好，然后让 axe 复用同一个浏览器实例，能省掉很多等待。

pnpm exec playwright install chromium

装完之后建议先跑一个空项目验证工具链是通的，别等到项目写到一半才发现某个工具根本没装上。

3.2 把检查脚本串成一条命令

工具装好了，但如果每次要手动敲五条命令，没人会坚持。我的做法是在package.json里把它们串起来：

{ "scripts": { "check:lint": "eslint src --ext .ts,.tsx", "check:style": "stylelint \"src/**/*.{css,scss}\"", "check:a11y": "axe http://localhost:3000 --exit", "check:types": "tsc --noEmit", "check:all": "pnpm check:types && pnpm check:lint && pnpm check:style && pnpm check:a11y" } }

check:all就是你的质量门禁。AI 生成完代码，跑这一条，全绿才算过关。

注意：axe命令里的--exit参数很关键，它让扫描发现问题时返回非零退出码，这样在 CI 里才能正确拦截。不加这个参数，问题再多它也返回 0，等于白跑。

3.3 为什么我把无障碍检查放在最前面

很多人把无障碍当成"锦上添花"，我恰恰相反，我把它当成第一道筛子。原因有三个。

第一，无障碍问题往往对应着真实的可用性缺陷。一个按钮没有可访问名称，屏幕阅读器用户用不了，但普通用户在某些场景下（比如图标按钮）也会困惑。一个对比度不足的文字，视力正常的用户在强光下也看不清。

第二，axe 的报错非常具体，它会直接告诉你"这个元素缺少 alt 属性""这个表单控件没有关联 label"，这种精确的报错非常适合直接喂回给 AI agent 让它修。相比之下，视觉问题很难用文字描述清楚。

第三，无障碍检查跑得快、误报少，作为第一道门禁不会拖慢开发节奏。

我实测下来，一个中等复杂度的页面，axe 扫描通常几秒钟出结果，而且报出来的问题基本都是真问题。把它放在流水线最前面，能拦掉相当一部分低级错误。

4. 浏览器扩展在验收环节的补位作用

4.1 CLI 检查不到的那部分：真实渲染

CLI 工具再强，也有它够不着的地方。它检查的是代码和 DOM 结构，但真实渲染出来的视觉效果、动画流畅度、字体加载后的布局偏移，这些只有浏览器里才能看到。

这就是浏览器扩展的补位价值。我常用的几类扩展：

• 无障碍审计类：在页面上直接高亮出有问题的元素，比看 CLI 报错直观得多
• 响应式预览类：一键切换各种设备宽度，快速发现断点问题
• 设计标注类：叠加网格和间距标注，检查 AI 写的间距是否符合设计系统
• 性能分析类：看布局偏移、长任务、渲染阻塞

这些扩展的共同点是：它们把"需要专业知识才能判断的问题"变成了"肉眼可见的标注"。你不需要记住 WCAG 的每一条标准，扩展会直接在你眼前把问题圈出来。

4.2 一个具体的验收动作清单

我把每次 AI 生成前端代码后的验收动作固定成了这么几步，你可以直接照搬：

1. 键盘走查：只用 Tab 和 Enter，看能不能完成所有交互。焦点顺序对不对，焦点样式看不看得见。
2. 缩放走查：从 320px 拉到 1920px，看有没有溢出、重叠、跳变。
3. 状态走查：手动触发 loading、error、empty 三种状态，看有没有对应的 UI。
4. 对比度走查：用扩展检查文字和背景的对比度是否达标。
5. 动效走查：如果开了"减少动态效果"的系统设置，动画是否被正确禁用。

这五步走下来，基本能覆盖 AI 最容易漏掉的所有角落。我把它叫做"五步验收法"，虽然土，但真的管用。

4.3 把验收结果结构化地反馈给 AI

验收发现问题之后，怎么反馈给 AI 也有讲究。我的经验是：不要笼统地说"这里有问题"，要把问题描述成可验证的断言。

比如你发现焦点样式看不见，不要跟 AI 说"焦点样式有问题"，而要说"按钮在 focus 状态下必须有至少 2px 的可见轮廓，且轮廓颜色与背景对比度不低于 3:1"。后者 AI 能直接执行，前者它只能猜。

这个思路其实和 CLI 报错是一样的——axe 之所以好用，就是因为它把问题描述成了"某元素缺少某属性"这种精确断言。你在人工反馈时也应该遵循同样的原则。

5. 让 AI agent 自己遵守 impeccable 标准的几个技巧

5.1 用配置文件把标准固化下来

与其每次在对话里重复要求，不如把标准写进项目配置文件，让 AI agent 每次都能读到。我通常会在项目根目录放几个文件：

• .eslintrc/eslint.config.js：代码规范
• .stylelintrc：样式规范
• AGENTS.md或类似约定文件：写给 AI 的项目约定

最后这个文件特别重要。我会在里面明确写清楚：本项目所有交互元素必须有可见焦点态；所有图片必须有 alt；所有表单控件必须有关联 label；间距只能使用 design token 里定义的值。AI agent 读到这些约定后，生成代码的合规率会明显提升。

5.2 给 AI 一个"验收清单"作为生成目标

另一个技巧是：在让 AI 生成代码之前，先把验收清单给它。

比如你要生成一个模态框组件，可以这样下指令："生成一个模态框组件，生成完成后请自查以下各项：焦点是否被正确捕获在模态框内、Esc 键是否能关闭、关闭后焦点是否回到触发元素、是否有 aria-modal 和 role 属性、背景内容是否对辅助技术隐藏。"

这种"带着验收标准生成"的方式，比"先生成再验收"效率高得多。因为 AI 在生成时就会把这些约束考虑进去，而不是等你发现问题再返工。

5.3 用 CLI 的退出码做自动化拦截

最后说一个工程化的点。如果你在 CI 里跑这套检查，一定要利用好退出码。前面提到的check:all脚本，只要任何一环失败就会返回非零，CI 就会拦截这次提交。

我见过不少团队把检查配成了"只警告不拦截"，结果就是警告越积越多，最后没人看。质量门禁必须是硬的，要么过要么不过，没有中间地带。这也是"impeccable"这个词的另一层含义——它不接受"差不多"。

6. 我在实际项目里踩过的几个坑

6.1 坑一：过度依赖自动检查，忽略了真实用户路径

有一次我特别得意，因为所有自动检查全绿，结果上线后收到反馈说"用键盘完全没法操作下拉菜单"。原因是 axe 只检查了静态 DOM，而那个下拉菜单的键盘交互逻辑是错的——方向键不响应，Esc 不关闭。这类交互逻辑层面的问题，静态检查根本发现不了。

教训是：自动检查是底线，不是全部。真实用户路径的走查不能省。

6.2 坑二：AI 生成的"看起来对"的样式

AI 特别擅长生成"看起来对"的 CSS。比如它写display: flex; justify-content: space-between，看起来没问题，但在内容超长时就会挤成一团。它写overflow: hidden，看起来没问题，但把焦点轮廓也一起裁掉了。

这类问题的隐蔽性在于：在正常数据下它确实是对的。只有边界数据、极端内容、特殊状态才会暴露。所以我在验收时一定会用超长文本、空数据、特殊字符去测一遍。

6.3 坑三：工具链本身的维护成本

最后一个坑比较现实：这套工具链本身是需要维护的。ESLint 插件会更新，规则会变，浏览器会升级，某个版本之后原来的配置可能就报错了。

我的应对策略是锁定版本 + 定期升级。在package.json里把关键工具的版本锁死，避免某天突然全红。然后每隔一两个月专门花时间升级一次，把该修的配置修掉。别让工具链的维护变成技术债。

7. 关于"impeccable"的一点个人理解

写了这么多工具和流程，最后想说点务实的。impeccable 这个词听起来很理想主义，但落到前端开发里，它其实是一个非常具体的目标：让每一个用户，用任何一种方式，在任何一种设备上，都能顺畅地完成他想做的事。

AI coding agents 让"写出代码"这件事变得前所未有的容易，但"写出无可挑剔的代码"反而变得更难了，因为生成速度越快，验收环节的压力就越大。CLI 工具和浏览器扩展的价值，就是帮你把这个压力接住，把主观的"感觉还行"变成客观的"检查通过"。

我自己现在的习惯是：AI 生成完代码，先跑一遍check:all，全绿了再打开浏览器走五步验收，有问题就带着具体断言回去让 AI 修。这个循环跑顺了之后，返工率能降一大半。工具是死的，流程是活的，关键是找到适合自己项目节奏的那一套。