1. 当impeccable成为前端交付的硬指标第一次看到impeccable这个词被拿来形容前端代码是在一个做设计系统的朋友嘴里。他说他们团队现在评审页面不看功能跑没跑通先看像素级还原度和交互细节有没有毛刺。功能能跑只是及格线impeccable——无懈可击、挑不出毛病——才是交付标准。这个词后来被不少做 AI coding agents 的团队借去当项目代号意思很直白让 AI 写出来的前端别一眼就是AI 味要经得起设计师和资深前端的审视。这篇东西就是围绕这个目标展开的。核心要解决的问题是AI coding agents 生成的前端代码怎么从能看做到impeccable。涉及的关键词有 AI coding agents、frontend design、CLI、browser extension。适合三类人看一是正在用 Codex CLI、Zcode CLI 这类命令行工具写前端的人二是想搞清楚 AI 生成前端到底卡在哪、怎么补的人三是团队里负责前端质量把关、想把 AI 产出纳入交付流程的人。我不打算把这篇写成工具说明书。市面上的 CLI 安装教程一搜一大把真正稀缺的是为什么 AI 写的前端总是差一口气以及这口气怎么补回来。所以下面会从实际踩坑出发把 AI 前端生成的质量断层拆开讲再给出可复现的补救流程。你不需要有很深的工程背景但最好动手跑过至少一个 AI coding agent不然有些细节会缺少体感。2. AI 写前端为什么总差一口气质量断层的三个来源2.1 训练数据里能跑的丑代码占比太高AI coding agents 的前端能力本质上是从海量公开代码里学出来的。问题在于公开代码库里功能正确但设计粗糙的样本占了绝大多数。一个能跑通的登录页可能用的是默认的浏览器按钮样式、随手写的 margin、没有设计 token 的硬编码颜色。模型见得多了默认输出就往这个方向偏。这就解释了为什么你让 AI 生成一个卡片组件它给你的往往是结构对、样式凑合的东西。不是它不会写好看的而是凑合在训练分布里是多数派。要让它输出 impeccable 的结果你得在提示里把多数派压下去明确告诉它设计约束。2.2 上下文窗口里缺少设计系统的锚点前端设计和后端逻辑有个本质区别后端有明确的正确性标准接口返回对不对前端的美观和一致性是相对的——相对于你项目已有的设计系统。AI 如果不知道你项目用的是 8px 栅格、主色是哪个 hex、圆角统一用 6px 还是 12px它只能猜。猜出来的东西单看没问题放进你的项目就格格不入。我见过太多团队抱怨AI 生成的组件和现有页面风格不搭根因就在这。解决思路不是换更强的模型而是把设计系统的关键约束喂进上下文。这个后面会讲具体怎么喂。2.3 交互细节是 AI 的盲区因为它看不见运行结果静态代码层面AI 能写得很好。但前端有一大半质量体现在运行时hover 的过渡曲线、focus 的可见轮廓、加载态的骨架屏、空状态的文案、错误态的提示位置。这些细节 AI 在生成时是盲写的它没有浏览器可以看效果只能靠训练里学到的模式去猜。提示判断一个 AI coding agent 前端能力强不强别只看它生成的静态页面重点看它处理 loading、empty、error 这三种状态时的表现。这三种状态最能暴露它是不是真的理解了交互。这三个来源叠加起来就是为什么很多人用 Codex CLI 或 Zcode CLI 生成前端后第一反应是能用但得大改。理解了断层在哪补救才有方向。3. 把设计约束喂进 CLI上下文工程的实操3.1 为什么要在 CLI 层面做这件事而不是在对话里用 CLI 工具Codex CLI、Zcode CLI 这类和用网页版对话有个关键差异CLI 通常支持把项目文件、配置文件作为上下文自动注入。这意味着你可以把设计系统的约束固化成项目里的文件而不是每次对话都手动粘贴一遍。这个差异的价值在于一致性。手动粘贴你今天记得贴、明天忘了AI 输出就飘。固化到文件里每次调用 CLI 它都自动读到输出风格就稳。这是把impeccable从偶然变成必然的关键一步。3.2 设计约束文件该写什么一份可抄的清单我自己的做法是在项目根目录放一个design-context.md内容分几块。下面这份是精简版你可以直接改成自己项目的# 设计系统约束 ## 栅格与间距 - 基础单位 4px所有间距必须是 4 的倍数 - 常用间距8 / 12 / 16 / 24 / 32 / 48 ## 颜色 - 主色 #2563EB悬停 #1D4ED8禁用 #93C5FD - 文本主色 #111827次要 #6B7280禁用 #9CA3AF - 背景 #FFFFFF次级背景 #F9FAFB - 禁止硬编码颜色必须引用上述 token ## 圆角与阴影 - 圆角统一 6px卡片 8px - 阴影只用两级sm 用于输入框md 用于卡片 ## 交互 - 所有可点击元素必须有 hover 和 focus-visible 态 - 过渡时长 150ms缓动 ease-out - 禁用态用 opacity 0.5不用改颜色 ## 组件状态 每个交互组件必须实现default / hover / focus / active / disabled 每个数据组件必须实现loading / empty / error / success这份文件的作用是给 AI 一个锚。它生成任何组件前先读这份约束输出就会往你的设计系统上靠。实测下来加了这份文件之后AI 生成组件的返工率能降一大截尤其是颜色和间距这两块基本不用再手动调。3.3 在 CLI 调用时怎么挂载这份约束不同 CLI 的挂载方式不一样但思路相通。以常见的做法为例你可以在调用时把设计文件作为上下文传入或者在项目里配置一个默认的上下文清单让 CLI 每次启动自动加载。关键点是别把整份设计文档塞进去。上下文窗口是有限的塞太多无关内容反而稀释了关键约束。我的经验是控制在 500 字以内只放AI 最容易写错的那几条颜色 token、间距单位、必须实现的状态。其他细节让它自己发挥。注意设计约束文件要跟着项目走别放在全局配置里。不同项目的设计系统不一样全局配置会导致 A 项目的约束污染 B 项目的输出。4. 从生成到 impeccable一套可复现的迭代流程4.1 第一轮生成只求结构不求完美很多人一上来就让 AI生成一个完美的登录页结果拿到一堆细节但结构混乱的东西。我的做法是分轮次。第一轮只给结构要求需要哪些区块、每个区块放什么元素、数据从哪来。样式约束先不展开让它把骨架搭对。这一轮的目标是结构正确。结构错了后面调样式是白费功夫。判断结构对不对看三点语义标签用没用对button 还是 div、层级关系清不清楚、有没有把该拆的组件拆出来。4.2 第二轮套设计约束重点盯颜色和间距结构定了第二轮把设计约束文件挂上让它按约束重写样式。这一轮重点检查两样东西颜色有没有用 token、间距是不是 4 的倍数。这两块是 AI 最容易偷懒的地方它可能直接写color: blue或者margin: 13px。发现硬编码不要直接让它改而是问它为什么这里没用 token。有时候它会给一个合理理由比如这个颜色确实不在设计系统里这时候你要决定是补 token 还是接受例外。这个过程本身就是在帮 AI 校准。4.3 第三轮补交互状态这是拉开差距的地方前两轮做完页面静态看已经不错了。第三轮专门补状态hover、focus、loading、empty、error。这一轮是impeccable和能用的分水岭。我的做法是直接列清单让 AI 逐项实现而不是笼统地说补全交互状态。清单式的要求它执行得更彻底。比如所有按钮补 hover / focus-visible / active / disabled表单补校验错误态和提交中态列表补 loading 骨架屏和 empty 空状态网络请求补 error 态和重试入口4.4 用 browser extension 做视觉验收生成完了怎么验收靠肉眼看代码不靠谱得在浏览器里实际跑。这时候 browser extension 就派上用场了。我常用的做法是配合浏览器开发者工具逐项核对检查项具体看什么常见问题间距用审查工具量实际像素出现非 4 倍数间距颜色取色对比设计 token硬编码颜色混入交互态手动触发 hover/focus缺 focus-visible响应式拖动窗口看断点断点处布局崩状态模拟慢网/空数据无 loading/empty这个表格可以当验收清单用。每生成一个页面过一遍问题基本跑不掉。5. 那些文档不会写的踩坑记录5.1 AI 会自作主张加它认为好看的样式这是最隐蔽的坑。你让它生成一个按钮它可能顺手加个渐变、加个阴影、加个圆角动画理由是这样更好看。单看确实好看但和你项目风格不搭。应对办法是在设计约束里明确写禁止添加未指定的视觉效果。这句话很管用能压住它大部分自作主张。如果它还加就在提示里点名批评它会收敛。5.2 响应式断点它总是猜错AI 生成响应式布局时断点值经常是它自己编的比如 768px、1024px 这种通用值。但你的项目可能用的是 640px、960px。这个不喂给它它永远猜不对。我的做法是把断点值写进设计约束文件并且明确所有媒体查询必须使用这些断点。加了之后响应式这块的返工基本消失。5.3 它会把无障碍属性当装饰品AI 知道要加aria-label、role这些但它经常加错地方或者加得没意义。比如给一个纯装饰的图标加aria-label或者给已经有文本的按钮再加一遍。这块我的经验是别指望 AI 一次写对无障碍但可以让它自查。生成完之后让它检查所有 aria 属性是否必要且正确它会自己发现一部分问题。剩下的靠人工过一遍重点看交互元素的可访问名称。5.4 CLI 的上下文丢失问题用 CLI 连续生成多个组件时有时候它会忘记前面几轮定下的约束。这不是 bug是上下文窗口的机制。应对办法是每生成 2-3 个组件重新挂载一次设计约束文件或者把关键约束在提示里复述一遍。提示如果你发现 AI 输出风格突然飘了第一反应应该是上下文是不是丢了而不是模型变笨了。重新挂载约束八成能救回来。6. 把 impeccable 变成流程而不是运气6.1 建立生成-验收-回归的闭环单次生成做到 impeccable 不难难的是每次都做到。这需要流程。我的做法是三步闭环生成挂约束、验收过清单、回归把这次发现的问题补进约束文件。第三步最容易被忽略但价值最大。每次验收发现的新问题比如AI 又把 focus 轮廓去掉了就补一条约束禁止移除 focus-visible 轮廓。约束文件越用越厚AI 的输出越用越稳。这就是把个人经验沉淀成团队资产的过程。6.2 给不同页面类型准备不同的提示模板登录页、列表页、详情页、表单页它们的状态需求不一样。与其每次从零描述不如准备几套提示模板。比如列表页模板里预置必须实现 loading 骨架、empty 空状态、error 重试表单页模板里预置必须实现字段校验、提交中禁用、成功反馈。模板的好处是省事且不漏。新人拿到模板照着填就能生成质量稳定的页面不用重新踩一遍坑。6.3 定期用真实设计稿做回归测试约束文件和模板会随着项目演进过时。我的习惯是每个月拿一份新的设计稿让 AI 按现有约束生成一遍看还原度。如果还原度下降说明约束该更新了。这个动作花不了多少时间但能保证流程不腐化。6.4 关于工具选型的一点个人看法Codex CLI、Zcode CLI 这类工具底层模型能力差异其实没有想象中大。真正拉开差距的是你怎么组织上下文。我见过用同一个工具有人生成的东西要改半天有人生成的基本能直接用差别就在约束文件写得好不好、迭代流程顺不顺。所以别在工具选型上纠结太久。挑一个顺手的把精力花在上下文工程和验收流程上收益大得多。工具会迭代流程和方法是你的。最后分享一个我一直在用的小技巧每次让 AI 生成前端之前先让它用一句话复述这个项目的设计约束是什么。它复述对了再让它动手。这一步花不了几秒但能提前发现上下文有没有挂上省下大量返工时间。踩过几次生成完才发现约束没生效的坑之后这个前置检查已经成了我的肌肉记忆。
