AI前端代码质量差？用这套Skill终结“塑料感”代码

其实我在两三个月前就注意到一个挺扎心的现象拿 Cursor 或者 Claude Code 写前端效率是上来了但生成出来的界面总有一种说不出的“塑料感”。按钮圆角全是 8px卡片千篇一律的白色配浅灰阴影字体用 system-ui 从头用到尾组件命名随意到让人血压升高。你要是让 AI 修改某个页面它甚至会给你叠上一堆遮罩、渐变、毛玻璃视觉上花里胡哨代码层面一塌糊涂。社区给这类输出起了个名字就叫 AI 前端 Slop。说白了Slop 就是 AI 在没有明确约束时靠概率平均出来的“最安全但最无味”的产物。它不报错、能运行但细节经不起推敲代码也谈不上可维护。最近 GitHub 上有个开源项目特别火Star 数冲到 8.2 万专门对付这个问题——它不是一个新框架也不是 lint 工具而是一套集成到 AI Agent 里的 skill用规则和流程把“AI 生成代码”这件事重新拉回工程规范轨道。我实际用了大概三周从 Cursor 到 Claude Code 再到 Codex 都试了一遍今天就把这套 skill 的玩法、原理和踩坑记录全部分享出来。这套 skill 解决的核心问题很简单当你让 AI 写前端时它缺少一个“懂行的资深工程师”在旁边把关。普通 Prompt 是嘴皮子约束而这个 skill 直接在 Agent 的推理路径里焊死了一套检查清单。它包含代码规范、性能预算、可访问性检查、视觉品味规则、组件设计约束甚至还有专门的调试步骤。你不需要在每个 Prompt 里啰嗦“请注重代码质量”skill 加载之后所有对话都会自动带上这套规则。1. 内容整体设计与思路拆解1.1 项目定位不是模板而是“行为准则”先解释一下 skill 到底是什么。在 Claude Code 这类 Agent 工具里skill 本质是一个带固定结构的目录目录里有一个SKILL.md作为主说明文件还有一堆子文件存放具体规则。Agent 会在合适的时机自动读取这些文件就像给模型外挂了一本工作手册。这个项目的聪明之处在于它把前端工程的“经验”变成了 Agent 能执行的“判定逻辑”而不是又一套代码模板。作者在 README 里写得很直白AI 生成前端代码质量差根源不是模型能力不够而是缺少约束和检查。比如让 GPT 写一个列表页它大概率会给你 flex map 三目运算符然后草草收场。但如果你把“列表空态怎么处理”“异步竞态怎么规避”“首屏字段如何取舍”写进规则里模型就会朝这些方向多走几步。这个项目就是把几百条这样的规则沉淀了下来。我这边把它当作团队的“前端新人培训手册”来看。新同学接手项目时直接让 AI 按照这套 skill 工作产出的代码风格、注释习惯、组件拆分粒度都比较统一省去大量 code review 的琐碎沟通成本。1.2 为什么传统 Prompt 治不了 Slop一个常见误区是既然 AI 输出不好我就把需求写详细点多强调几遍“注意质量”不就行了。实测下来这种做法收效甚微。原因很现实大模型的注意力是有限的。Prompt 越长后面的指令越容易被忽略。你在开头写“代码要优雅”它在生成到第 200 行时大概率已经忘了这回事。skill 不一样的地方在于它把检查项做成了可执行的模块。模型生成完代码后skill 会触发一个 review 阶段逐条核对“有没有给图片写 alt”“有没有做错误边界”“CSS 里有没有写死像素值”这些具体点。这些检查项不是泛泛而谈的“提高质量”而是能一一对照的硬指标。模型能不能执行取决于规则是否足够明确。比如“按钮必须提供 hover、focus、disabled、loading 四种状态”这一点模型看到就一定会生成对应的样式。另一个关键原因是skill 可以持续叠加和沉淀。项目里除了核心前端规则还允许你自己加规则文件。我最近就把团队内部“接口层必须统一走 request 封装”的约定写了进去之后 Agent 生成的所有网络请求代码都会自动走我们封装好的函数这一步直接把不少隐性 bug 消灭在摇篮里。1.3 项目架构三层防御机制继续拆这套 skill 的内部结构你会发现它不是一坨文件堆在一起而是有清晰的分层设计。第一层是全局规则定义了所有前端任务都适用的底线包括语义化 HTML、无障碍基础、响应式布局、命名规范。第二层是场景规则针对具体任务类型提供专项约束比如写表单时有“标签必须关联输入框”“校验错误要靠近输入框展示”的规则写列表时有“分页/加载更多/无限滚动的取舍标准”。第三层是检查清单Agent 在生成完毕后会拿着清单逐项自检。这三层设计逻辑非常像代码评审的流程先看整体风格再看局部实现最后逐条核对细节。我在实际体验中最明显的感觉是AI 输出的代码从“能跑就行”变成了“能评审通过”。它会在代码注释里写出自己遵循了哪条规则有时候甚至连测试用例都按照规范补齐了省了我大量重复劳动。2. 核心细节解析与实操要点2.1 规范规则不是摆设是生产力的底座很多开发者听到“代码规范”四个字就下意识反感觉得是束缚、是教条。但这套 skill 里对规范的定义非常务实它不追求“最优代码”只追求“无意外代码”。比如 HTML 部分强制要求使用语义化标签nav、main、section、aside 各归其位。表面看这是给屏幕阅读器用的实际收益每个人都能感知浏览器默认样式、SEO 抓取、后续维护时的代码可读性全都受益。CSS 部分也有明确方法论。项目推荐采用 utility-first 结合 BEM 的方式而不是让风格完全二选一。它会在规则里明确“样式覆盖不超过两级”“禁止使用!important”“颜色必须取自设计令牌”。我第一次看到这条规则时觉得有点死板但用多了就明白AI 没有“克制”这种品质你给它越窄的边界它产出越可控。颜色固定用令牌视觉就不会跑偏禁止!important就不会出现样式互相打架的问题。JavaScript 层面更偏重工程习惯。比如副作用要收敛到明确的地方事件监听器必须清理异步操作必须有竞态保护。这些都是一个合格前端工程师的肌肉记忆但 AI 不会天生具备必须靠规则塑造。2.2 性能预算与 JSON.stringify 的隐性开销性能优化是这套 skill 很有价值的一块因为普通 Prompt 根本不会管性能模型只会关注“实现功能”。而这个 skill 内置了性能预算的概念首屏资源不超过某个体积、图片必须懒加载、列表渲染超过一定数量就必须做虚拟滚动等等。特别要提一个细节就是JSON.stringify在前端性能里的陷阱。很多开发者习惯用它做深拷贝但没意识到它在数据量大时有严重的性能问题。我自己实测过一个包含 10 万条数据、嵌套 5 层的对象用JSON.stringify深拷贝耗时大约在 80ms 到 120ms 之间而用structuredClone只需要 20ms 左右。更别提如果对象里有undefined、函数、循环引用JSON.stringify会直接把你坑了。skill 里的性能规则明确写了“禁止用 JSON.stringify 做深拷贝”推荐使用structuredClone或者手写递归。这一个小点放在日常代码里可能一辈子遇不到问题但一旦遇到大规模数据渲染就是线上事故和流畅体验的分水岭。还有关于前端性能优化skill 给出了非常具体的操作清单我挑几条直接抄出来组件卸载时必须移除全局事件监听和定时器动画只用transform和opacity避免操作 layout 属性通过content-visibility: auto让屏外内容跳过渲染。每一条背后都有真实的浏览器渲染原理支撑不是拍脑袋想出来的。2.3 视觉品味也是可以规则化的很多人觉得审美这东西没法教 AI这套 skill 却硬是把“taste”拆成了可量化的规则。你翻开它的视觉规则文件会发现里面写得很细页面主色调不超过 3 个相邻元素间距必须符合 4px 或 8px 的间距系统字体大小层级不少于 3 档且不小于 14px边框圆角建议 2px、8px、16px 三档禁止随意取中间值阴影必须使用两层以上才能营造层次感动效时长默认 150ms 到 300ms且必须支持prefers-reduced-motion。这些规则的逻辑本质是“减少决策面提升一致性”。人类设计师可以靠感觉拿捏一个 6px 的圆角是否合适AI 做不到但如果只有三档可选它选出来的一定在视觉系统内。我用这套规则让 AI 做了一个后台仪表盘生成的界面让我团队的设计师都吃了一惊说审美终于“在线”了。移动端适配部分更有意思规则直接要求“小屏不降级信息密度而是调整呈现优先级”强行让 AI 去思考移动端用户真正需要的核心操作是什么。2.4 组件拆分与可维护性组件设计是前端开发的灵魂也是 AI 最容易翻车的重灾区。AI 默认倾向是“一个页面一个大组件”因为这样最快完成任务。但工程上这种写法会导致一个文件几千行状态互相纠缠后面每改一个需求都提心吊胆。skill 里对组件拆分做了硬性要求单一组件职责不超过一个业务概念组件 props 超过 8 个必须拆分或合并组件文件超过 400 行必须重构子组件不能直接修改父组件传入的对象。这套规则看起来简单执行效果却立竿见影。我让 AI 实现一个复杂的筛选器面板没用 skill 之前它生成的是一个带 30 多个 props 的大型组件逻辑全部堆在一起。加载 skill 之后它会自动拆分出条件组、日期范围选择器、标签输入框等多个子组件每个组件职责清晰状态提升到父级统一管理。代码可读性、方便程度完全是两个量级。命名规范这块也值得一提。项目里对变量命名有明确约定布尔变量必须以is、has、should开头事件处理函数统一用handle前缀返回 JSX 的函数必须用render前缀常量一律大写蛇形。这种规则最大价值是让 AI 生成代码的“指纹”稳定团队里不管谁让 AI 干活出来的代码风格都像一个老手写的。3. 实操过程与核心环节实现3.1 安装接入几分钟就能跑起来先说说怎么把这套 skill 装起来。以 Claude Code 为例它支持全局 skills 目录和项目级 skills 目录两种方式。全局的放在~/.claude/skills/项目级的放在.claude/skills/。装好之后 Agent 会自动扫描不需要额外配置。我用的是直接从 GitHub 克隆的方式命令很简单cd ~/.claude/skills git clone https://github.com/example/frontend-craftsman.git项目目录结构大概是这样的frontend-craftsman/ ├── SKILL.md ├── rules/ │ ├── html-semantics.md │ ├── css-style.md │ ├── javascript-practices.md │ ├── accessibility.md │ ├── performance-budget.md │ └── visual-taste.md ├── checklists/ │ ├── component-review.md │ └── page-review.md └── scripts/ └── scan-for-common-issues.js装完之后我建议在SKILL.md顶部显式加上你的技术栈偏好比如 Vue 还是 React、是否使用 TypeScript、UI 组件库选型。因为 skill 默认规则是框架无关的你补充这一小段能让它更贴合自己的项目。我自己是在文件里加了“本项目使用 Vue 3 TypeScript ViteUI 库用 Element Plus禁止引入额外 UI 依赖”之后生成代码的技术选型基本没跑偏过。3.2 实测同一需求的两次生成对比为了让你直观感受到这个 skill 的威力我做了一次严格对照实验。同一个需求“做一个带搜索和筛选的用户列表页”分别用普通 Prompt 和加载 skill 后的 Agent 生成模型的推理模型完全一样只有 skill 不同。普通 Prompt 生成的代码一个大组件从头写到尾props 里塞了 20 多个字段没有拆分任何子组件样式全部写在 scoped 里且大部分是硬编码颜色没有 loading 状态、没有空态、没有错误处理搜索功能直接用 filter 全量遍历完全没有防抖。加载 skill 后的代码组件结构层次分明拆出了UserTable、FilterPanel、SearchInput三个子组件状态通过组合式函数管理网络请求带竞态保护表格有 loading 骨架屏搜索输入有 300ms 防抖列表空数据有专门的 EmptyState颜色全部引用于设计令牌并为每个组件配了基础的单测。最让我欣慰的是代码注释质量。加载 skill 后AI 不是机械地写“这里执行搜索”而是会标注“防抖 300ms避免每次按键都触发请求同时保留请求序号防止竞态”。这种注释才是真正有信息量的注释。3.3 关键参数和行为配置skill 的规则文件用 Markdown 编写Agent 会直接读取解析。规则描述格式非常重要我观察到一个好的规则描述包含三个要素条件、动作、理由。举个例子性能规则里有一条“当列表渲染超过 200 条数据时必须采用虚拟滚动。理由大量 DOM 节点会导致布局和绘制时间显著上升影响滚动性能。”这种格式模型特别容易理解执行率也高。我在实际使用中总结了一些自定义规则的技巧。规则越具体越好最好给出边界阈值。不要写“注意性能”要写“首屏必须控制在 1.5 秒内超过 200KB 的 JS 包必须做代码分割”。规则需要用正面语言描述写“必须做什么”比“禁止做什么”效果更好。给 Agent 留出解释空间让它可以在不确定时先问你再动手而不是猜一个沉默的默认值。比如说我之前加过一条规则“当实现一个完整页面时如果需求描述不够清晰如未指定排序方式、分页样式先列出 3 个左右的疑点向用户确认不要直接按默认方案写代码。”这简单一句话直接让 AI 生成内容的返工率大幅下降。3.4 学会调用内置检查工具这个 skill 还带了一个scripts/scan-for-common-issues.js脚本用法就是交给 Agent 在生成完代码后自动执行也可以手动用 node 跑一下。脚本会扫描整个前端目录检查出一些基础问题是否用了危险内联样式、是否有硬编码颜色值、是否存在超过 400 行的组件文件、有没有console.log残留。脚本本身是开源的你可以随意魔改。我就在里面加了两个团队自己的规则一个是扫描 TODO 注释必须在提交前消除另一个是检查 API 请求是否统一走了 request 封装。装好之后就是一行命令的事集成进 CI 也没有问题。它跟 ESLint 不冲突定位不同这个脚本更偏工程结构和设计规范的检查ESLint 偏语法和风格。4. 常见问题与排查技巧实录4.1 一个问题速查表我整理了这三周实际使用中最常遇到的几个问题以及对应解法直接做成表格方便你排查时快速查阅。问题现象根本原因解决方案skill 加载了但 Agent 不遵守规则规则描述太模糊模型无法理解触发条件重写规则明确触发场景、边界条件、动作要求生成代码结构过于复杂过度设计规则堆叠过多模型为了满足全部规则而过度设计检查规则之间是否冲突按场景拆分规则文件skill 不生效Agent 完全不读文件路径放错了或 SKILL.md 格式不对检查是否放在.claude/skills/下SKILL.md 头部是否有name和description字段只对某些模型生效部分模型对长上下文工具的理解较弱切换 Claude 最新模型或 GPT-5老模型确实不太行规则之间互相冲突全局规则和场景规则有重叠矛盾给场景规则加“higher priority”注释或重新整合全局规则4.2 三个我自己踩出来的调试技巧第一让 Agent 在开工前先输出“执行计划”。在 Prompt 里直接说“先阅读 skill 里的规则然后输出你计划怎么实现这个页面列出涉及的关键组件和 API 请求确认后再生成代码”。你会发现 Agent 一旦先把计划说出口后续生成内容的质量立刻上一个台阶因为它相当于给自己立了一个承诺后面的行为有了基线。第二把规则文件按场景拆开。我最初把所有规则写在一个超大文件里结果模型常常顾此失彼。后来我按场景拆成“列表页规则”“表单页规则”“仪表盘规则”并配置成只有在对应任务出现时才加载效果立竿见影。Claude Code 的 skill 机制支持根据目录名自动匹配务必要利用好这个机制。第三用 git diff 来做回归检查。每次让 Agent 生成完代码不要急着接受直接在终端跑git diff逐行看改动。这不是为了审查代码而是为了观察它有没有在你不注意的地方“自作主张”。我有一次发现它在某个不相关的配置文件里加了一条危险规则要不是 diff 看得细这个问题可能就上线了。4.3 与团队协作的落地建议最后聊一下如何把 skill 变成团队资产。我建议你把 skill 目录纳入 Git 仓库统一管理而不是各自复制一份。让小组里资深的同事定期更新规则比如每次 code review 发现共性问题就往 skill 里加一条规则。一个月下来这套 skill 就成了你们团队经验的活文档比 Wiki 靠谱得多。还有一点要提醒AI 生成的前端代码虽然质量提升了但 skill 不能替代代码评审。工具是流程辅助核心还是人的判断。没有兜底的情况下让 AI 直接提交生产代码风险依然太高。我的习惯是让 Agent 生成代码后先自测一轮然后我快速过 diff跑一下测试和构建命令确认没问题再合并。有了 skill 这套规则兜底我自己的 review 负担轻了很多从逐行纠错变成了重点关注逻辑是否合理。5. 适用范围与后续扩展5.1 从页面开发到前端面试准备有意思的是这套 skill 除了在生产开发中好用前端面试准备阶段也能派上用场。你可以让 AI 严格按照 skill 规则实现一套经典题目比如实现一个带防抖搜索和虚拟列表的页面然后对着生成结果反向学习看看一个“资深工程师标准”的代码长什么样。这比我当年背八股文效率高多了。前端面试题里面不少原理题也可以通过让 AI 先写一段符合规范代码再逐行问你“为什么要这么写”得到比标准答案更有说服力的解释。5.2 对接 Codex 与更多 AgentClaude Code 的 skill 机制相对成熟但并不是唯一支持 skill 的平台。这套项目本身是开放目录结构理论上任何支持目录式技能加载的 Agent 都能用。Codex 现在也支持类似规范我已经跑通了几次基础流程配置方式就是把 skill 目录挂到 Codex 的配置里。不同工具对 skill 文件的加载策略略有差异但核心规则文件都是 Markdown迁移成本非常低。5.3 下一步可以怎么玩如果你本身是前端团队的负责人或者“工具党”可以试试用它的思路创建自己的 skill。项目里有skill-creator相关的说明按它给的结构把你的团队约定、项目技术栈、历史踩坑记录填进去就能定制一套完全属于你们团队的专用 skill。我已经开始尝试为后端接口规范写一套类似的规则效果同样显著。技术上它本质就是“把人的经验结构化后喂给模型”逻辑是相通的。说起来我最喜欢的反而是这套 skill 的一个小细节。它要求在生成代码以后Agent 自检完成时在回复里写一句“我没有做完的任务有...”。这给了人类一个显式的兜底信号。刚开始我不理解为什么要有这条后来才发现训练过的 Agent 倾向于过度自信地“假装任务完成”而这一条迫使它暴露没做的事。对 AI 生成代码这件事来说知道边界比什么都重要。希望这套 skill 也能给你的 AI 前端开发加点边界感。