1. 从impeccable这个词说起一个被低估的前端质量信号第一次看到impeccable这个词是在一份前端代码评审的清单里。它被用来形容一个组件的实现状态——不是能用不是跑通了而是无可挑剔。这个词在词典里的意思是完美的、无可指摘的但放在前端开发和 AI coding agents 的语境下它其实指向一个非常具体的东西代码在视觉、交互、可维护性三个维度上都没有明显短板。这个标准听起来很虚但拆开来看非常实在。视觉上间距、对齐、色彩对比度、响应式断点都要经得起放大镜看交互上加载态、空状态、错误态、边界情况都要有兜底可维护性上命名、抽象层级、依赖关系要清晰到别人接手时不需要问你。大多数项目卡在能用这一档离impeccable还差着好几轮打磨。为什么现在要专门聊这个话题因为 AI coding agents 的普及正在改变前端开发的节奏。以前一个页面从零到能用可能要半天现在用 CLI 工具配合 agent十几分钟就能出一个能跑的版本。但能跑和impeccable之间的鸿沟并没有因为 AI 而缩小反而因为生成速度太快很多人跳过了打磨环节直接进入下一个任务。结果就是代码库里堆满了差不多能用的组件技术债越滚越大。这篇内容适合几类人看一是正在用或准备用 AI coding agents 做前端开发的工程师想知道怎么把生成结果推到无可挑剔的水准二是团队里负责代码质量的人需要一套可操作的检查标准三是对 CLI 工具链感兴趣、想了解 codex cli、openspec cli 这类工具怎么配合前端工作流的人。我会从工具选型、工作流设计、质量检查、常见坑四个角度展开尽量把每个环节的为什么讲清楚。需要提前说明的是下面提到的工具和方法都是基于公开信息和常见实践的合理推演具体版本和命令请以你实际使用的工具文档为准。前端生态变化快思路比具体命令更重要。2. AI coding agents 在前端场景下的能力边界2.1 生成速度带来的虚假完成感用 AI agent 写前端代码最直观的感受就是快。一个带表单验证、状态管理、响应式布局的页面描述清楚需求后几十秒就能出一版。这种速度会给人一个错觉任务完成了。但实际上生成出来的代码往往只是骨架正确细节上全是毛刺。我见过太多这样的情况agent 生成的组件在桌面端看着没问题一到移动端就溢出按钮的 hover 态有但 focus 态和 disabled 态缺失列表渲染没做 key 的稳定处理数据更新时整个列表重渲染。这些问题不会让页面报错但会让它离impeccable很远。更麻烦的是这些问题在快速迭代中很容易被忽略等到用户反馈时已经积累了一堆。所以第一件要建立的心智模型是AI agent 负责的是从 0 到 0.7剩下的 0.3 才是决定质量的关键。这 0.3 包括边界情况处理、无障碍支持、性能优化、代码组织。把 agent 当成一个手很快但经验尚浅的初级工程师你的角色是那个把关的资深工程师。2.2 哪些前端任务适合交给 agent哪些不适合不是所有前端工作都适合让 agent 来做。根据实际使用经验可以大致分成三类任务类型适合程度原因样板代码生成表单、列表、卡片高模式固定agent 训练数据充足样式调整与响应式适配中需要视觉判断agent 容易差不多就行复杂交互逻辑拖拽、动画编排低状态机复杂agent 容易漏边界情况无障碍与语义化低需要主动意识agent 默认不关注性能敏感路径低需要 profiling 数据支撑agent 靠猜这个表格不是绝对的但能帮你快速判断什么时候该自己上手。我的习惯是结构性的、重复性的交给 agent判断性的、体验性的自己来。比如生成一个数据表格的骨架可以让 agent 做但列宽怎么分配、空数据怎么展示、加载骨架屏怎么设计这些要自己定。2.3 impeccable在前端语境下的可操作定义把无可挑剔翻译成可检查的条目我一般用下面这个清单视觉层间距使用统一的设计 token不出现魔法数字颜色对比度满足 WCAG AA 标准所有断点下无溢出、无遮挡。交互层每个可点击元素有 hover、focus、active、disabled 四态异步操作有 loading 和 error 反馈空状态有引导文案。代码层组件职责单一props 类型完整没有未使用的 import 和变量命名能自解释不需要注释补充。无障碍层语义化标签正确使用图片有 alt表单控件有关联 label键盘可完整操作。这个清单看起来基础但真正每条都做到的项目并不多。agent 生成的代码通常能过前两条的一半后两条基本要靠人工补。把这份清单固化到你的评审流程里是通往impeccable的第一步。3. CLI 工具链的选型逻辑codex cli 与同类工具怎么选3.1 为什么前端工作流需要 CLI 而不是纯 IDE 插件很多人习惯在 IDE 里用 AI 插件觉得方便。但做前端质量打磨时CLI 工具有几个 IDE 插件替代不了的优势。第一是可脚本化。你可以把 codex cli 这类工具嵌到 npm scripts 或 CI 流程里比如提交前自动跑一遍代码检查、自动生成组件文档、自动补全缺失的测试。IDE 插件是交互式的很难自动化。第二是上下文可控。CLI 工具通常允许你精确指定要处理的文件范围、要参考的配置文件、要遵循的规范文档。IDE 插件往往把整个项目塞进上下文反而稀释了重点。做impeccable级别的打磨时精确的上下文比海量的上下文更有用。第三是可复现。CLI 命令可以写进文档、写进脚本、分享给同事别人跑同样的命令能得到类似的结果。IDE 插件里的对话是临时的很难沉淀成团队资产。所以如果你的目标是系统性地提升前端代码质量而不是偶尔问几个问题CLI 工具链是更合适的选择。3.2 codex cli 的安装与常见卡点codex cli 的安装本身不复杂但网络环境不同体验差异很大。常见的安装方式是通过 npm 全局安装npm install -g openai/codex-cli如果遇到安装很慢的情况通常是 npm registry 的访问问题。可以检查一下当前的 registry 配置npm config get registry如果返回的不是你期望的源可以临时切换npm install -g openai/codex-cli --registryhttps://registry.npmjs.org安装完成后用codex --version验证。如果提示命令找不到检查 npm 全局 bin 目录是否在 PATH 里npm config get prefix这个路径下的 bin 目录需要加到环境变量里。Windows 和 macOS/Linux 的配置方式不同这里不展开但这是新手最常卡住的地方。注意安装过程中如果遇到权限报错不要直接用 sudo 全局安装容易导致后续权限混乱。更稳妥的做法是配置 npm 的用户级 prefix或者用 nvm 这类版本管理工具。3.3 几个容易混淆的 CLI 工具定位热词里出现了好几个 CLI 名字容易搞混。我按自己的理解梳理一下它们的定位差异codex cli偏向代码生成和重构的通用 agent 工具适合处理给我写一个 XX 组件这类任务。openspec cli偏向规范驱动开发强调先写规格再生成代码适合需要严格对齐需求的场景。zcode cli通常指某些特定平台的代码辅助工具定位和 codex 类似但生态不同。minimax cli偏向多模态能力前端场景下可能用于生成图片资源或设计稿转代码。选哪个不是非此即彼实际工作中经常组合使用。比如用 openspec cli 生成组件规格再用 codex cli 按规格实现最后人工打磨。关键是理解每个工具擅长什么别指望一个工具包打天下。3.4 安装 codex cli 很慢时的排查思路node 安装 codex cli 很慢是个高频问题。排查顺序建议这样先确认是网络问题还是包本身问题。换一个简单的包试试npm install -g lodash如果也慢就是网络问题。网络问题的话检查是否有可用的镜像源。国内常用的镜像源配置方式这里不具体展开但思路是找一个响应快的 registry。如果只有 codex cli 慢可能是包体积大或依赖多。可以加--verbose看卡在哪个环节。实在慢的话考虑用pnpm或yarn替代 npm它们的依赖解析和缓存机制在某些场景下更快。这些排查步骤不只适用于 codex cli任何 npm 包安装慢都可以套用。4. 把 agent 生成结果推到impeccable的实操流程4.1 第一步先定规范再让 agent 动手大多数人用 agent 的流程是描述需求 → 生成代码 → 看效果 → 不满意再改。这个流程的问题在于agent 不知道你的项目规范生成的东西风格可能和现有代码完全不一致。更有效的流程是先把规范喂给 agent再让它生成。规范包括设计 token 文件颜色、间距、字号、圆角组件命名约定比如 Button 还是 BtnProps 怎么命名目录结构约定组件放哪、样式放哪、测试放哪代码风格配置ESLint、Prettier 的配置文件把这些文件路径告诉 agent让它生成前先读一遍。这一步多花两分钟后面省下的返工时间可能是二十分钟。4.2 第二步用分步生成替代一次性生成一次性让 agent 生成整个页面结果往往是一大坨代码问题藏在里面很难找。更好的做法是拆成几步先生成组件的静态结构HTML 骨架 基础样式确认结构没问题后再加交互逻辑交互没问题后再补边界情况loading、error、empty最后补无障碍属性每一步生成完都检查一遍问题早发现早修。这种小步快跑的方式比一次性生成再大修要高效得多。4.3 第三步建立 agent 输出的检查清单生成完代码后不要急着提交。按下面的清单过一遍结构检查组件是否只做一件事有没有把不相关的逻辑塞在一起Props 是否有完整的类型定义有没有用 any有没有硬编码的字符串、颜色、尺寸样式检查间距是否来自设计 token有没有 13px、17px 这种魔法数字响应式断点是否覆盖了主要设备深色模式如果有是否适配交互检查所有异步操作是否有 loading 态失败情况是否有 error 提示空数据是否有 empty 态按钮的 disabled 态是否正确无障碍检查交互元素是否可以用键盘操作图片是否有 alt表单控件是否有关联的 label颜色对比度是否达标这份清单可以做成一个 markdown 文件放在项目里每次评审时对照。时间长了会形成肌肉记忆很多问题在生成阶段就能避免。4.4 第四步用 diff 审查而不是通读agent 生成或修改代码后不要从头到尾读一遍那样效率低还容易漏。用 git diff 看改动重点关注有没有删除不该删的代码有没有引入新的依赖有没有改动公共组件的行为有没有留下 console.log 或调试代码diff 审查的好处是聚焦在变化上而不是全貌上。对于 agent 这种经常做局部修改的场景diff 是最高效的审查方式。4.5 一个真实的打磨案例举个具体例子。我让 agent 生成一个用户列表组件第一版出来是这样的function UserList({ users }) { return ( div {users.map(user ( div key{user.id} span{user.name}/span span{user.email}/span /div ))} /div ); }能跑但离 impeccable 差得远。我按清单逐条改加 loading 态if (loading) return Skeleton /加空态if (!users.length) return EmptyState /加错误态if (error) return ErrorState message{error} /用语义化标签外层用ul每项用li加无障碍列表加aria-label样式抽离用设计 token 替代内联样式加类型用 TypeScript 定义 User 类型改完之后的代码量是原来的三倍但这才叫无可挑剔。agent 给的是起点不是终点。5. 那些 agent 不会主动告诉你的坑5.1 上下文窗口的遗忘问题用 CLI 工具处理大文件时agent 经常忘记前面的约定。比如你开头说了所有颜色用 CSS 变量生成到后面又冒出硬编码的#333。这不是 agent 笨是上下文窗口的限制。应对方法有两个一是把关键约定放在每次请求的开头重复一遍二是把大任务拆小每个小任务单独请求。我倾向于后者因为重复约定本身也占上下文。5.2 生成代码的过度自信agent 生成的代码往往看起来很自信——命名规范、结构清晰、注释完整。但这种自信有时候是假象。我遇到过 agent 生成的一个日期格式化函数逻辑写得漂漂亮亮但边界情况闰年、时区全错。如果只看代码不测试很容易被唬住。所以对 agent 生成的任何逻辑代码都要写测试验证。特别是涉及计算、转换、边界判断的部分测试不能省。5.3 依赖引入的隐性成本agent 为了解决问题经常会引入新依赖。比如为了格式化日期引入 dayjs为了处理类名引入 clsx。单个依赖看起来不大但积累起来会让 bundle 膨胀。我的做法是agent 引入新依赖时先问一句能不能用现有依赖或原生 API 实现。很多时候答案是能。比如日期格式化如果只是简单场景Intl.DateTimeFormat就够了不需要额外依赖。5.4 样式方案的精神分裂如果项目里同时存在 CSS Modules、styled-components、Tailwind 三种样式方案agent 会随机选一种来用导致代码风格混乱。这不是 agent 的问题是项目本身的问题。解决方法是统一样式方案并且在给 agent 的规范里明确写清楚本项目使用 XX 方案不要用其他方案。规范越明确agent 的输出越一致。5.5 删除 codex cli 或清理环境的注意事项有时候需要卸载或清理 CLI 工具。删除 codex cli 的命令很简单npm uninstall -g openai/codex-cli但要注意几点一是配置文件可能残留在用户目录下比如~/.codex/需要手动清理二是如果有项目级的配置或缓存也要一并清理三是如果之前在 CI 里配置了相关命令记得同步更新 CI 脚本否则会报错。提示卸载前先确认没有其他项目依赖这个工具。全局工具的影响范围比想象中大尤其是在多项目共用一个开发环境时。6. 把impeccable变成团队习惯而不是个人追求6.1 把检查清单固化到 CI 里个人追求impeccable靠自觉团队追求impeccable靠流程。最有效的固化方式是把检查项写进 CIESLint 规则覆盖命名、未使用变量、import 顺序Stylelint 规则覆盖样式规范无障碍检查用 axe-core 或类似工具自动化视觉回归测试用截图对比CI 不通过就不让合并这样impeccable就从个人标准变成了团队底线。一开始可能会有阻力但坚持几周后大家会习惯。6.2 建立 agent 输出的评审规范团队用 agent 生成代码时需要一套评审规范。我建议包含这几条agent 生成的代码必须经过人工审查才能合并审查时用 diff 而不是通读重点检查边界情况、无障碍、性能敏感路径新引入的依赖需要单独说明理由这套规范的目的不是限制 agent 的使用而是确保 agent 的输出经过质量把关。agent 是加速器不是替代品。6.3 定期回顾 agent 引入的问题每隔一段时间回顾一下 agent 生成的代码里出现过哪些问题。是样式不一致是边界情况遗漏还是依赖膨胀把高频问题整理出来更新到给 agent 的规范里。这样下一轮生成时同样的问题会减少。这个回顾不需要很正式每周花半小时看看最近的 PR 就够了。关键是形成发现问题 → 更新规范 → 减少问题的循环。6.4 我个人在实际操作中的体会用了大半年 AI coding agents 做前端最大的体会是agent 改变的是速度不是标准。以前一天能打磨一个组件现在一天能打磨五个但每个组件的质量标准没有降低。如果因为速度快就降低标准那只是把技术债的生产效率提高了。另一个体会是规范的价值被 agent 放大了。以前规范不清晰影响的是人人还能靠经验补现在规范不清晰影响的是 agentagent 会严格按字面执行规范里的漏洞会被放大成代码里的问题。所以用 agent 之前先把规范理清楚这个投入回报率极高。最后一个体会是关于impeccable这个词本身。它不是一个终点而是一个方向。没有代码是真正无可挑剔的但朝着这个方向走代码质量会持续提升。agent 能帮你走得更快但方向得自己定。 
长河君 · 2026/10/26 20:12:54 · 阅读 1.2k AI coding agents 前端代码打磨：从能跑到 impeccable 的实践指南
1. 从impeccable这个词说起一个被低估的前端质量信号第一次看到impeccable这个词是在一份前端代码评审的清单里。它被用来形容一个组件的实现状态——不是能用不是跑通了而是无可挑剔。这个词在词典里的意思是完美的、无可指摘的但放在前端开发和 AI coding agents 的语境下它其实指向一个非常具体的东西代码在视觉、交互、可维护性三个维度上都没有明显短板。这个标准听起来很虚但拆开来看非常实在。视觉上间距、对齐、色彩对比度、响应式断点都要经得起放大镜看交互上加载态、空状态、错误态、边界情况都要有兜底可维护性上命名、抽象层级、依赖关系要清晰到别人接手时不需要问你。大多数项目卡在能用这一档离impeccable还差着好几轮打磨。为什么现在要专门聊这个话题因为 AI coding agents 的普及正在改变前端开发的节奏。以前一个页面从零到能用可能要半天现在用 CLI 工具配合 agent十几分钟就能出一个能跑的版本。但能跑和impeccable之间的鸿沟并没有因为 AI 而缩小反而因为生成速度太快很多人跳过了打磨环节直接进入下一个任务。结果就是代码库里堆满了差不多能用的组件技术债越滚越大。这篇内容适合几类人看一是正在用或准备用 AI coding agents 做前端开发的工程师想知道怎么把生成结果推到无可挑剔的水准二是团队里负责代码质量的人需要一套可操作的检查标准三是对 CLI 工具链感兴趣、想了解 codex cli、openspec cli 这类工具怎么配合前端工作流的人。我会从工具选型、工作流设计、质量检查、常见坑四个角度展开尽量把每个环节的为什么讲清楚。需要提前说明的是下面提到的工具和方法都是基于公开信息和常见实践的合理推演具体版本和命令请以你实际使用的工具文档为准。前端生态变化快思路比具体命令更重要。2. AI coding agents 在前端场景下的能力边界2.1 生成速度带来的虚假完成感用 AI agent 写前端代码最直观的感受就是快。一个带表单验证、状态管理、响应式布局的页面描述清楚需求后几十秒就能出一版。这种速度会给人一个错觉任务完成了。但实际上生成出来的代码往往只是骨架正确细节上全是毛刺。我见过太多这样的情况agent 生成的组件在桌面端看着没问题一到移动端就溢出按钮的 hover 态有但 focus 态和 disabled 态缺失列表渲染没做 key 的稳定处理数据更新时整个列表重渲染。这些问题不会让页面报错但会让它离impeccable很远。更麻烦的是这些问题在快速迭代中很容易被忽略等到用户反馈时已经积累了一堆。所以第一件要建立的心智模型是AI agent 负责的是从 0 到 0.7剩下的 0.3 才是决定质量的关键。这 0.3 包括边界情况处理、无障碍支持、性能优化、代码组织。把 agent 当成一个手很快但经验尚浅的初级工程师你的角色是那个把关的资深工程师。2.2 哪些前端任务适合交给 agent哪些不适合不是所有前端工作都适合让 agent 来做。根据实际使用经验可以大致分成三类任务类型适合程度原因样板代码生成表单、列表、卡片高模式固定agent 训练数据充足样式调整与响应式适配中需要视觉判断agent 容易差不多就行复杂交互逻辑拖拽、动画编排低状态机复杂agent 容易漏边界情况无障碍与语义化低需要主动意识agent 默认不关注性能敏感路径低需要 profiling 数据支撑agent 靠猜这个表格不是绝对的但能帮你快速判断什么时候该自己上手。我的习惯是结构性的、重复性的交给 agent判断性的、体验性的自己来。比如生成一个数据表格的骨架可以让 agent 做但列宽怎么分配、空数据怎么展示、加载骨架屏怎么设计这些要自己定。2.3 impeccable在前端语境下的可操作定义把无可挑剔翻译成可检查的条目我一般用下面这个清单视觉层间距使用统一的设计 token不出现魔法数字颜色对比度满足 WCAG AA 标准所有断点下无溢出、无遮挡。交互层每个可点击元素有 hover、focus、active、disabled 四态异步操作有 loading 和 error 反馈空状态有引导文案。代码层组件职责单一props 类型完整没有未使用的 import 和变量命名能自解释不需要注释补充。无障碍层语义化标签正确使用图片有 alt表单控件有关联 label键盘可完整操作。这个清单看起来基础但真正每条都做到的项目并不多。agent 生成的代码通常能过前两条的一半后两条基本要靠人工补。把这份清单固化到你的评审流程里是通往impeccable的第一步。3. CLI 工具链的选型逻辑codex cli 与同类工具怎么选3.1 为什么前端工作流需要 CLI 而不是纯 IDE 插件很多人习惯在 IDE 里用 AI 插件觉得方便。但做前端质量打磨时CLI 工具有几个 IDE 插件替代不了的优势。第一是可脚本化。你可以把 codex cli 这类工具嵌到 npm scripts 或 CI 流程里比如提交前自动跑一遍代码检查、自动生成组件文档、自动补全缺失的测试。IDE 插件是交互式的很难自动化。第二是上下文可控。CLI 工具通常允许你精确指定要处理的文件范围、要参考的配置文件、要遵循的规范文档。IDE 插件往往把整个项目塞进上下文反而稀释了重点。做impeccable级别的打磨时精确的上下文比海量的上下文更有用。第三是可复现。CLI 命令可以写进文档、写进脚本、分享给同事别人跑同样的命令能得到类似的结果。IDE 插件里的对话是临时的很难沉淀成团队资产。所以如果你的目标是系统性地提升前端代码质量而不是偶尔问几个问题CLI 工具链是更合适的选择。3.2 codex cli 的安装与常见卡点codex cli 的安装本身不复杂但网络环境不同体验差异很大。常见的安装方式是通过 npm 全局安装npm install -g openai/codex-cli如果遇到安装很慢的情况通常是 npm registry 的访问问题。可以检查一下当前的 registry 配置npm config get registry如果返回的不是你期望的源可以临时切换npm install -g openai/codex-cli --registryhttps://registry.npmjs.org安装完成后用codex --version验证。如果提示命令找不到检查 npm 全局 bin 目录是否在 PATH 里npm config get prefix这个路径下的 bin 目录需要加到环境变量里。Windows 和 macOS/Linux 的配置方式不同这里不展开但这是新手最常卡住的地方。注意安装过程中如果遇到权限报错不要直接用 sudo 全局安装容易导致后续权限混乱。更稳妥的做法是配置 npm 的用户级 prefix或者用 nvm 这类版本管理工具。3.3 几个容易混淆的 CLI 工具定位热词里出现了好几个 CLI 名字容易搞混。我按自己的理解梳理一下它们的定位差异codex cli偏向代码生成和重构的通用 agent 工具适合处理给我写一个 XX 组件这类任务。openspec cli偏向规范驱动开发强调先写规格再生成代码适合需要严格对齐需求的场景。zcode cli通常指某些特定平台的代码辅助工具定位和 codex 类似但生态不同。minimax cli偏向多模态能力前端场景下可能用于生成图片资源或设计稿转代码。选哪个不是非此即彼实际工作中经常组合使用。比如用 openspec cli 生成组件规格再用 codex cli 按规格实现最后人工打磨。关键是理解每个工具擅长什么别指望一个工具包打天下。3.4 安装 codex cli 很慢时的排查思路node 安装 codex cli 很慢是个高频问题。排查顺序建议这样先确认是网络问题还是包本身问题。换一个简单的包试试npm install -g lodash如果也慢就是网络问题。网络问题的话检查是否有可用的镜像源。国内常用的镜像源配置方式这里不具体展开但思路是找一个响应快的 registry。如果只有 codex cli 慢可能是包体积大或依赖多。可以加--verbose看卡在哪个环节。实在慢的话考虑用pnpm或yarn替代 npm它们的依赖解析和缓存机制在某些场景下更快。这些排查步骤不只适用于 codex cli任何 npm 包安装慢都可以套用。4. 把 agent 生成结果推到impeccable的实操流程4.1 第一步先定规范再让 agent 动手大多数人用 agent 的流程是描述需求 → 生成代码 → 看效果 → 不满意再改。这个流程的问题在于agent 不知道你的项目规范生成的东西风格可能和现有代码完全不一致。更有效的流程是先把规范喂给 agent再让它生成。规范包括设计 token 文件颜色、间距、字号、圆角组件命名约定比如 Button 还是 BtnProps 怎么命名目录结构约定组件放哪、样式放哪、测试放哪代码风格配置ESLint、Prettier 的配置文件把这些文件路径告诉 agent让它生成前先读一遍。这一步多花两分钟后面省下的返工时间可能是二十分钟。4.2 第二步用分步生成替代一次性生成一次性让 agent 生成整个页面结果往往是一大坨代码问题藏在里面很难找。更好的做法是拆成几步先生成组件的静态结构HTML 骨架 基础样式确认结构没问题后再加交互逻辑交互没问题后再补边界情况loading、error、empty最后补无障碍属性每一步生成完都检查一遍问题早发现早修。这种小步快跑的方式比一次性生成再大修要高效得多。4.3 第三步建立 agent 输出的检查清单生成完代码后不要急着提交。按下面的清单过一遍结构检查组件是否只做一件事有没有把不相关的逻辑塞在一起Props 是否有完整的类型定义有没有用 any有没有硬编码的字符串、颜色、尺寸样式检查间距是否来自设计 token有没有 13px、17px 这种魔法数字响应式断点是否覆盖了主要设备深色模式如果有是否适配交互检查所有异步操作是否有 loading 态失败情况是否有 error 提示空数据是否有 empty 态按钮的 disabled 态是否正确无障碍检查交互元素是否可以用键盘操作图片是否有 alt表单控件是否有关联的 label颜色对比度是否达标这份清单可以做成一个 markdown 文件放在项目里每次评审时对照。时间长了会形成肌肉记忆很多问题在生成阶段就能避免。4.4 第四步用 diff 审查而不是通读agent 生成或修改代码后不要从头到尾读一遍那样效率低还容易漏。用 git diff 看改动重点关注有没有删除不该删的代码有没有引入新的依赖有没有改动公共组件的行为有没有留下 console.log 或调试代码diff 审查的好处是聚焦在变化上而不是全貌上。对于 agent 这种经常做局部修改的场景diff 是最高效的审查方式。4.5 一个真实的打磨案例举个具体例子。我让 agent 生成一个用户列表组件第一版出来是这样的function UserList({ users }) { return ( div {users.map(user ( div key{user.id} span{user.name}/span span{user.email}/span /div ))} /div ); }能跑但离 impeccable 差得远。我按清单逐条改加 loading 态if (loading) return Skeleton /加空态if (!users.length) return EmptyState /加错误态if (error) return ErrorState message{error} /用语义化标签外层用ul每项用li加无障碍列表加aria-label样式抽离用设计 token 替代内联样式加类型用 TypeScript 定义 User 类型改完之后的代码量是原来的三倍但这才叫无可挑剔。agent 给的是起点不是终点。5. 那些 agent 不会主动告诉你的坑5.1 上下文窗口的遗忘问题用 CLI 工具处理大文件时agent 经常忘记前面的约定。比如你开头说了所有颜色用 CSS 变量生成到后面又冒出硬编码的#333。这不是 agent 笨是上下文窗口的限制。应对方法有两个一是把关键约定放在每次请求的开头重复一遍二是把大任务拆小每个小任务单独请求。我倾向于后者因为重复约定本身也占上下文。5.2 生成代码的过度自信agent 生成的代码往往看起来很自信——命名规范、结构清晰、注释完整。但这种自信有时候是假象。我遇到过 agent 生成的一个日期格式化函数逻辑写得漂漂亮亮但边界情况闰年、时区全错。如果只看代码不测试很容易被唬住。所以对 agent 生成的任何逻辑代码都要写测试验证。特别是涉及计算、转换、边界判断的部分测试不能省。5.3 依赖引入的隐性成本agent 为了解决问题经常会引入新依赖。比如为了格式化日期引入 dayjs为了处理类名引入 clsx。单个依赖看起来不大但积累起来会让 bundle 膨胀。我的做法是agent 引入新依赖时先问一句能不能用现有依赖或原生 API 实现。很多时候答案是能。比如日期格式化如果只是简单场景Intl.DateTimeFormat就够了不需要额外依赖。5.4 样式方案的精神分裂如果项目里同时存在 CSS Modules、styled-components、Tailwind 三种样式方案agent 会随机选一种来用导致代码风格混乱。这不是 agent 的问题是项目本身的问题。解决方法是统一样式方案并且在给 agent 的规范里明确写清楚本项目使用 XX 方案不要用其他方案。规范越明确agent 的输出越一致。5.5 删除 codex cli 或清理环境的注意事项有时候需要卸载或清理 CLI 工具。删除 codex cli 的命令很简单npm uninstall -g openai/codex-cli但要注意几点一是配置文件可能残留在用户目录下比如~/.codex/需要手动清理二是如果有项目级的配置或缓存也要一并清理三是如果之前在 CI 里配置了相关命令记得同步更新 CI 脚本否则会报错。提示卸载前先确认没有其他项目依赖这个工具。全局工具的影响范围比想象中大尤其是在多项目共用一个开发环境时。6. 把impeccable变成团队习惯而不是个人追求6.1 把检查清单固化到 CI 里个人追求impeccable靠自觉团队追求impeccable靠流程。最有效的固化方式是把检查项写进 CIESLint 规则覆盖命名、未使用变量、import 顺序Stylelint 规则覆盖样式规范无障碍检查用 axe-core 或类似工具自动化视觉回归测试用截图对比CI 不通过就不让合并这样impeccable就从个人标准变成了团队底线。一开始可能会有阻力但坚持几周后大家会习惯。6.2 建立 agent 输出的评审规范团队用 agent 生成代码时需要一套评审规范。我建议包含这几条agent 生成的代码必须经过人工审查才能合并审查时用 diff 而不是通读重点检查边界情况、无障碍、性能敏感路径新引入的依赖需要单独说明理由这套规范的目的不是限制 agent 的使用而是确保 agent 的输出经过质量把关。agent 是加速器不是替代品。6.3 定期回顾 agent 引入的问题每隔一段时间回顾一下 agent 生成的代码里出现过哪些问题。是样式不一致是边界情况遗漏还是依赖膨胀把高频问题整理出来更新到给 agent 的规范里。这样下一轮生成时同样的问题会减少。这个回顾不需要很正式每周花半小时看看最近的 PR 就够了。关键是形成发现问题 → 更新规范 → 减少问题的循环。6.4 我个人在实际操作中的体会用了大半年 AI coding agents 做前端最大的体会是agent 改变的是速度不是标准。以前一天能打磨一个组件现在一天能打磨五个但每个组件的质量标准没有降低。如果因为速度快就降低标准那只是把技术债的生产效率提高了。另一个体会是规范的价值被 agent 放大了。以前规范不清晰影响的是人人还能靠经验补现在规范不清晰影响的是 agentagent 会严格按字面执行规范里的漏洞会被放大成代码里的问题。所以用 agent 之前先把规范理清楚这个投入回报率极高。最后一个体会是关于impeccable这个词本身。它不是一个终点而是一个方向。没有代码是真正无可挑剔的但朝着这个方向走代码质量会持续提升。agent 能帮你走得更快但方向得自己定。