最近做完一轮 Vue 项目迭代复盘了一下这一个月里用 AI 编程助手写前端代码的过程发现一个很有意思的结论不是 AI 不聪明是它压根不知道我这个项目有什么规矩。AI 写出来的组件语法挑不出大毛病但代码风格能把我逼疯——一会儿 Options API一会儿script setup样式不加 scoped全局状态随手就往 Pinia 里塞路由不做懒加载。这些代码给你团队里任何一个老前端 review都会被打回去重写。后来我给自己项目建了一套 Vue Skills。Skills 这个概念最近在很多 AI 编程工具里火起来你可以把它理解成给 AI 的入职手册——把项目的技术栈、目录结构、编码规范、最佳实践写成一个一个的技能包让 AI 在动手写代码之前先读一遍然后按你的规矩干活。我花了一个周末整理了一份针对 Vue 的完整技能包又迭代了两周现在 AI 产出的代码我基本不需要大改。这篇文章会把整套 Vue Skills 的完整思路和实操过程掰开揉碎讲清楚为什么你写的通用提示词调教不了一个长期项目、一份合格的 Vue Skills 应该包含哪些维度、SKILL.md 怎么写才能让 AI 真读进去、怎么在不同工具之间复用以及接入前后的真实对比。如果你是前端团队负责人、资深前端工程师或者天天被 AI 代码风格折磨的独立开发者这篇文章应该能帮你省下大把 review 时间。1. 为什么 AI 写 Vue 总在翻车先从根上理解 Skills 机制1.1 通用知识不等于项目规范大模型最擅长的是把预训练阶段见过的海量代码内化成一种统计规律。它确实知道 Vue 3 有 Composition API知道 ref、reactive、computed 的语法也见过无数 GitHub 开源项目的写法。但问题是这种统计规律是全行业平均水平而不是你这个项目的标准。打个比方。你去一家连锁餐厅的后厨面试官问你会不会做菜你说会这是对的——你会用刀、会开火、知道盐和糖的区别。但是这家餐厅有自己的一套出餐标准薯条要炸 90 秒摆盘的时候酱料放在右边餐具必须用银色的。这些细节你一概不知。你按自己的理解做出来的菜味道可能没问题但端上桌就是不符合这家餐厅的标准。AI 写 Vue 代码也是这个道理。它不知道你项目用的是 Vue 3 还是混着 Vue 2 的写法不知道你的目录里是views还是pages不知道请求封装是request.ts里那个http实例更不知道你们团队约定禁止在模板里写三层以上的复杂表达式。这些项目特有知识如果没有人告诉 AI它每次都会回到用全球通用平均水平的AI 默认风格来写代码。这种风格换个项目也能跑但放到具体团队里往往就是 review 时最让人头大的问题来源。1.2 解剖一段AI 味代码先给一段典型AI 味的输出看看问题出在哪template div input v-modelinputVal inputhandleChange / p{{ inputVal }}/p /div /template script export default { data() { return { inputVal: }; }, methods: { handleChange() { this.inputVal this.$refs.input.value; }, }, }; /script style .content { color: red; } /style这段代码问题不少没有使用script setup用的是 Vue 3 早期过渡期的 Options API 风格。在 Vue 3 项目里这会带来额外的this上下文心智负担同事来 review 也会觉得这不像我们项目写的。handleChange完全是多余的。v-model本身就完成了双向绑定AI 却用input手动取值再赋值属于为了逻辑而逻辑。style没有 scoped。类名一旦进入全局很容易和其他组件冲突。整个组件没有loading、error、空数据等状态数据请求失败用户只能干瞪眼。这类代码最大的问题不是不能跑而是没有体现项目的边界和约定。AI 不知道项目要求每个列表页都要有加载中/加载失败/空数据的完整状态也不知道样式必须作用域隔离更不知道组件应该只做一件事、超过 300 行就要拆分。在没有 Skills 之前解决这个问题只能靠两种笨办法一是每次提问时把规则粘贴进 prompt二是写完代码后人工 review 再一步步改。前者既费 token 又容易漏后者则把最重要的审查成本留给了人。1.3 Skills 的工作机制AI 怎么读规矩的Skills 解决的就是让项目规范成为 AI 的默认上下文。以 Claude Code 的 Agent Skills 为例机制大概是这样你在项目根目录下建立一个.claude/skills/技能名/SKILL.md文件文件头部是 YAML 格式的 frontmatter包含name和description正文是具体的指令、步骤、示例代码。当用户和 AI 对话时AI 会根据对话内容里的关键词和意图去匹配各个技能包的description。如果匹配上就把对应的 SKILL.md 文件加载进上下文然后按照其中规则执行任务。这个机制的聪明之处在于按需加载。你的技能包可以有很多个——Vue 一个、后端一个、数据库一个、部署一个——但 AI 不会一次性全部读进上下文而是根据当前任务选择最相关的。这就像你给 AI 建了一个工具箱它每次干活前会根据任务选对工具而不是把所有工具都扛在身上。把 Skills 和传统的把规范文档发给 AI做对比差异就更明显了。传统做法里规范是在一段对话中临时补充的上下文它只在当前会话有效Skills 则是沉淀在项目里的固定资产谁发起对话、哪一天发起对话都能读到同一套规则。它就像.eslintrc、.prettierrc一样是一种可执行、可持续维护的团队约定。2. 一份合格 Vue Skills 的内容设计到底要塞哪些规矩2.1 先定技术栈基线很多人在写技能包时犯一个错误一上来就写组件要优雅代码要健壮这种空话。AI 对这种话毫无感觉因为优雅没有可操作的标准。真正管用的第一章节是用最精确的话把技术栈锁死技术栈基线 - Vue 3.4统一使用 script setup 组合式 API禁止 Options API - TypeScript 严格模式禁止 any - UI 组件库Ant Design Vue 4.x - 状态管理Pinia - 路由Vue Router 4配置式集中管理 - 请求统一使用 src/utils/request.ts 导出的 http 实例 - 样式组件内一律使用 scoped 项目 CSS 变量为什么这一步决定成败因为 AI 的预训练知识里Vue 2 和 Vue 3 的代码是混在一起的。你如果不明确告诉它技术栈它很可能根据问题热度分布来选择风格——而互联网上 Vue 2 的存量代码实在太多了。一旦它默认用了 Vue 2 写法你后面再怎么纠正都费劲。技术栈基线最好还包括关键依赖版本。比如你项目里用的是 Ant Design Vue 4.xAI 如果不知道就可能给你用 3.x 的 API或者干脆手写一个替代组件。这种版本不对齐是 AI 代码最常见的隐性坑。提示技术栈基线要写你的项目实际用的版本不要照抄网上教程。AI 忠实度比你想象的高你写什么它就用什么。2.2 给 AI 画一张目录地图AI 生成代码时最迷茫的问题之一是这个文件该放哪里。你需要在技能包里放一张目录树并明确每一层的放置规则src/ api/ # 按业务域拆分请求模块例如 user.ts、order.ts assets/ components/ common/ # 跨页面通用组件 business/ # 业务聚合组件 composables/ # 可复用逻辑 layouts/ # 布局组件 router/ # 路由集中配置 stores/ # Pinia 状态 styles/ # 全局样式与 CSS 变量 utils/ # 工具函数 views/ # 页面级组件与路由一一对应随后配上文件归属决策规则路由跳转到的页面组件放views/会被两个以上页面复用的组件放components/common/只在某个业务域内复用的组件放components/business/可复用逻辑放composables/禁止写进组件内部再到处复制API 请求按资源模块拆分放api/下对应文件这步的作用是让 AI 从一个会写代码的机器变成一个了解项目结构的参与者。没有地图的 AI 可能把组件建在一个随机位置有地图的 AI 会自动选择正确的目录并且能通过路径推断模块之间的依赖关系。2.3 组件规范AI 最常犯的三个毛病在组件层面AI 的重复性问题集中在三点。第一组件过大。这是最普遍的毛病。AI 倾向于需求一个页面就往一个文件里堆。一个包含搜索表单、表格、分页、弹窗的页面它能写出一千行。处理方式是在技能包里写一条硬规则- 视图组件单文件超过 300 行必须拆分 - 拆分优先选择子组件、composables - 超过 500 行视为严重违规第二props 和 emits 定义不规范。AI 在没被约束时会用各种自创写法比如混用defineProps和 props 解构或者给 props 写运行时校验。项目规范可以明确interface Props { user: UserInfo; showAvatar?: boolean; } const props withDefaults(definePropsProps(), { showAvatar: true, }); const emit defineEmits{ (e: refresh): void; }(); // 访问 props 时用 props.xxx不要解构 props避免丢失响应式注意最后一行非常关键。很多 AI 生成的代码会把 props 解构成局部变量在模板里直接用user这样在特定场景下会丢失响应式。这种问题在 review 时很隐蔽但在技能包里写清楚AI 就能避开。第三事件和加载状态缺失。技能里可以规定页面组件必须处理 loading/error/empty 三态异步操作必须在 try/catch/finally 中完成禁止裸 throw禁止在模板里写超过 2 层的复杂表达式v-for 的 key 用唯一 id 而不是 index。2.4 Pinia 的使用边界别把 store 当成万能口袋AI 对全局状态有一种迷之偏好。哪怕只是一个页面内部的筛选条件它也喜欢放进 store好像不放全局就显得不够架构。因此技能包要明确 store 的边界放进 Pinia登录用户信息、权限、应用级别的缓存配置、跨页面共享的查询条件不放进 Pinia仅单个页面内使用的临时状态、列表筛选条件、表单内容同时要强调在组件外部禁止直接使用 store 实例。比如工具函数里不要import { useUserStore } from /stores/user后再去修改 state应通过组件内调用 action 完成修改只在 action 内部可以通过useOtherStore()获取其他 store 的方法且不要在 state 初始化阶段跨 store。这步的目的是防止 AI 把 store 写成一个巨大的全局对象。Pinia 不强制约束 state 变更方式但团队约定要求所有修改走 action这样变更链路可追踪也便于调试。AI 没有这种工程意识只能靠规则补。2.5 路由、样式与请求那些容易被忽略的工程细节路由方面需要明确集中配置、懒加载、meta 统一。示例// router/routes.ts const routes: RouteRecordRaw[] [ { path: /user, name: User, component: () import(/views/User/UserList.vue), meta: { title: 用户管理, requiresAuth: true }, }, ];添加规则禁止顶层全量 import 所有页面组件路由 path 统一小写多级路径用嵌套 children所有页面路由必须配置meta.title并确保与组件名对应便于 keep-alive样式方面组件内一律style scoped全局样式只能放styles/下的入口文件禁止在组件里写非 scoped 样式颜色、间距优先使用 CSS 变量避免硬编码魔法值。请求方面统一走request.ts的实例它已经封装了 token 注入、错误码处理、超时等逻辑不要在每个组件里新建fetch或者单独axios.create页面组件必须展示 loading 和 error 状态。这一部分的共同点AI 不知道你们项目的基建已经解决了哪些问题它容易把已经封装好的东西重新实现一遍。Skills 的价值就是告诉它基础设施已经有了你只需要在它之上写业务代码。3. SKILL.md 怎么写才能让 AI 真正读进去3.1 组织结构主文件 附录很多人的第一个版本是把所有规则写成一个超长的 SKILL.md结果 AI 读取后读了个寂寞。人的注意力有限模型的注意力也有限。上下文窗口虽然大但当一份文档动辄五六千字时中间大量规则会被模型当作次要内容忽略掉。推荐的实践是主文件做索引 关键规则详细示例和模板放子目录.claude/skills/vue-code/ SKILL.md examples/ good-page.vue good-store.ts good-api.ts templates/ page-template.vueSKILL.md 控制在 1500 字以内只放最核心的硬规则更完整的说明、正反例、长篇代码走子目录。这样 AI 在加载 SKILL.md 时能完整覆盖所有关键指令需要更多细节时再按需读取子文件。3.2 Do/Dont 示例比描述性语言有效AI 更擅长模仿不擅长执行模糊规则。与其写请合理使用状态管理不如DO: 页面内部筛选条件优先用 ref 在组件内维护不要放进 Pinia DONT: - 不要把所有筛选状态放进全局 store - 不要使用 Options API 的 data() 写法更有力的做法是给正反例代码片段。AI 会从示例中推断风格这比任何文字描述都有效。比如你希望它用withDefaults写法直接给一段代码比写请使用 withDefaults 提供默认值效果更好。3.3 示例代码是最强风格标定我在实测中注意到一个现象给 AI 一段你团队里的高质量代码它生成的代码风格会明显向示例靠拢。如果示例里用了ref而不是reactiveAI 后续大概率也更倾向用ref。所以示例文件别随手写务必要用你团队真实的高标准代码。可以放这几个示例文件examples/good-page.vue一个完整的优质页面组件包含三态处理、props 类型、事件定义examples/good-store.ts符合规范的 Pinia store包含 action 命名examples/good-api.ts标准的请求模块写法templates/page-template.vue可以直接套用的页面模板这些文件其实等于给 AI 提供了铁打的样板。它在生成新代码时会像照着图纸施工一样风格稳定在示例水平上。3.4 调试如何确认 AI 真的加载了 Skills刚开始用 Skills 时最容易遇到的问题是Ai 好像根本没理我的技能包。这时需要排查我一般按这个顺序来看 AI 的回复开头。多数工具在加载了技能包后会在回复里带一句我将按照 vue-code 技能包中的规范来完成这个任务类似的话。如果没有说明技能包可能没被选中。检查description的触发词。description写得越像搜索引擎的索引词越容易被匹配。如果里面没有Vue、组件、页面、前端这些词AI 可能判断不出来该用这个技能。检查路径和文件名。.claude/skills/vue-code/SKILL.md这个路径中技能名是目录名主文件必须是SKILL.md大小写都不能错。用工具自带的命令确认。Claude Code 有查看技能列表的命令比如/skills或类似入口如果列表里没有说明目录位置不对。提示写完技能包后最好先用一个简单但明显违反规则的 prompt 测试比如帮我写一个带筛选条件的列表页面组件。如果它没用script setup、没处理 loading说明技能包没有被加载赶紧排查而不是继续调规则文字。4. 从零搭建 Vue Skills完整实操与验证4.1 选定目录、初始化文件以 Claude Code 为例在项目根目录创建技能包目录mkdir -p .claude/skills/vue-code/examples touch .claude/skills/vue-code/SKILL.md如果你的主工具是 Codex、OpenCode路径可能不同但思路一致把技能包放在项目根目录下某个约定位置并确认工具能识别。不同工具的机制还在快速迭代最稳妥的参考是官方文档这里不写死。把SKILL.md的 YAML frontmatter 写好。name用短横线命名description写清楚触发场景和关键词。4.2 一份可直接抄的 SKILL.md 示例下面是一份可以复制后修改的骨架直接覆盖你自己的技术栈细节即可--- name: vue-code description: Vue 3 项目编码规范与开发辅助。当用户要求编写、修改 Vue 组件、页面、路由、store 或涉及前端代码时使用。 --- # Vue 3 项目编码助手 你正在参与一个 Vue 3 TypeScript Vite Pinia 项目。 请严格遵守以下团队约定。 ## 技术栈基线 - Vue 3.4统一使用 script setup 组合式 API禁止 Options API - TypeScript 严格模式禁止 any - UI 组件库Ant Design Vue 4.x - 请求统一使用 src/utils/request.ts 导出的 http 实例 ## 目录规则 - views/: 页面级组件一个路由对应一个视图文件 - components/common/: 跨页面通用组件 - components/business/: 业务聚合组件 - composables/: 可复用逻辑 - stores/: Pinia - api/: 请求模块 ## 核心规则 1. 组件 props 用 defineProps withDefaults确保完整类型 2. 页面内部状态用 ref跨组件才进 Pinia 3. 样式必须 scoped类名使用 BEM 变体 4. 路由懒加载禁止顶层全量 import 5. 请求必须处理 loading、error 状态 6. 禁止在模板中写超过 2 层的复杂表达式改用 computed 7. 视图组件单文件超过 300 行必须拆分 8. 异步操作必须 try/catch/finally禁止裸 throw ## 示例 - 优质页面组件examples/good-page.vue - 标准 store 写法examples/good-store.ts - API 模块写法examples/good-api.ts ## 输出前自查清单 在我完成代码后自查以下问题并在回复中确认 - [ ] 是否使用 script setup 组合式 API - [ ] 样式是否 scoped - [ ] 是否处理了 loading/error 状态 - [ ] 组件是否过大是否需要拆分 - [ ] 是否有任何 any 类型这份 SKILL.md 的特点规则短、可执行、自带自查清单。尤其是最后的自查清单实测能显著提升 AI 对规则的遵守率。4.3 配套示例文件的高质量写法有了一份主文件之后最重要的就是示例文件。以examples/good-page.vue为例它应该展示出一个本团队标准页面应有的样子!-- examples/good-page.vue -- script setup langts import { ref, onMounted } from vue; import { useUserStore } from /stores/user; import { fetchUserList } from /api/user; const props defineProps{ source: string; }(); const emit defineEmits{ (e: refresh): void; }(); const userStore useUserStore(); const loading ref(false); const error ref(); const list refUserInfo[]([]); const loadList async () { loading.value true; error.value ; try { list.value await fetchUserList(); } catch { error.value 加载失败请稍后重试; } finally { loading.value false; } }; onMounted(loadList); /script template div classuser-page a-table :loadingloading :data-sourcelist / a-empty v-if!loading list.length 0 / a-alert v-iferror typeerror :messageerror / /div /template style scoped .user-page { padding: 16px; } /style这份示例里最关键的是展示了三态处理和try/catch/finally。AI 在模仿这份代码生新页面时会自觉带上相同的错误处理和状态变量而不是只写一个光秃秃的表格。4.4 用测试 Prompt 做行为验证技能包建好后不要急着压到业务里先用一组标准 prompt 做行为验证。我常用的测试问题如下测试 Prompt期望行为未生效时的排查方向帮我写一个用户列表页面组件script setup、TS、loading/error 三态、表格description 是否含组件、页面关键词新增一个 /orders 路由页面路由懒加载、meta 标题、目录归属正确SKILL.md 是否在正确路径把这段筛选逻辑放到全局状态提示是否改为组件内 ref规则文字是否明确单页状态不进 store写一个 API 请求模块使用 request.ts 实例、按资源模块拆分示例文件是否正确说明请求封装如果两次测试都没有命中期望行为那就是技能包没有被加载到上下文需要排查路径、触发词、主文件格式。如果技能包生效你会明显感觉到 AI 的产出从一个通用代码生成器变成了你这个项目的结对开发者。5. 多工具跑通Claude Code、Codex、OpenCode 的适配细节5.1 不同工具的加载机制对比目前主流 AI 编程工具对项目内技能资产的支持方式和成熟度各不相同我这里列一下大致的现状具体以各工具官方文档为准工具技能目录约定主文件要求加载机制Claude Code.claude/skills/技能名/SKILL.md根据 description 匹配后按需加载机制成熟Codex CLIAGENTS.md或官方 skills 目录以官方文档为准项目指令文件机制skills 也在快速迭代OpenCode官方 skills 目录以官方文档为准社区活跃格式与 Claude 思路接近不要因为不同工具的路径不同而焦虑。底层的逻辑是通用的用文件把规则沉淀下来让 AI 在合适的场景读取。你在 Claude Code 里摸索出来的内容设计方法搬到其他工具只是改个目录位置的问题。还有一个实操心得如果你同时用多个工具做同一个项目建议把技能内容和工具加载位置解耦。也就是在你自己的skills/vue-code/目录里维护一份源文件再通过软链或者复制的方式让不同工具都能读到。5.2 一份技能包多端复用的软链方案在 macOS 或 Linux 下可以用符号链接让不同工具共享同一份技能包# 假设你维护在项目根目录的 skills/ 下 mkdir -p skills/vue-code # 编写 skills/vue-code/SKILL.md 和 examples 子目录 # 让 Claude Code 能读到 mkdir -p .claude/skills ln -s ../../skills/vue-code .claude/skills/vue-code # 让 Codex 能读到 mkdir -p .codex/skills ln -s ../../skills/vue-code .codex/skills/vue-code这样你改skills/vue-code/SKILL.md所有工具都会同步生效。Windows 下的符号链接有时权限麻烦我建议直接复制一份到对应目录改的时候再同步过去简单粗暴但稳定。5.3 把 Skills 变成团队协作资产技能包一定要进 git 仓库而且要走评审流程。我把.claude/skills/和skills/都提交到项目仓库这样新成员 clone 完项目AI 就已经自动学会了团队规范。更重要的是一套持续迭代机制每次 code review 发现 AI 产出的低质量代码把为什么不好沉淀成一条新规则补进 SKILL.md技能包变更走 PR至少有一个资深前端 review在 SKILL.md 的 frontmatter 里加版本号变化比较大的时候在 description 里注明v1.2 新增路由规范我见过不少团队把 Skills 当成一次性配置写完就再也不动。其实它应该和你的代码规范一起成长项目重构、技术栈升级、团队新约定都应该及时反映到技能包里。6. 实测效果与暴露出的边界6.1 测试场景与方法为了验证这套 Vue Skills 到底有多大作用我做了几个典型任务对比生成一个新的列表页、写一个复杂表单组件、把一个 Options API 老组件迁移到组合式 API 风格、实现一个带权限控制的动态路由。每个任务跑两遍一遍不带技能包一遍带技能包。记录代码结构、状态处理、命名规范性、样式作用域等维度。6.2 接入前后的代码质量对比接入前后对比非常明显我整理了一张简表质量维度接入前接入后组件风格Options API / script setup 混用统一 script setup TS错误处理经常没有 catchloading/error/empty 三态齐全样式作用域偶发全局无 scoped全部 scoped路由加载顶层静态 import懒加载 统一 meta组件体积单文件经常 500 行300 行左右自动拆分类型质量出现 any严格类型props 有默认值store 使用单页状态也塞 Pinia本地状态用 ref跨页才进 store最直观的体验是接入后 AI 生成的首版代码我基本只需要改业务逻辑不需要再纠正规范和风格问题。这直接省掉了大量 review 来回沟通的成本。6.3 仍然绕不开的坑Skills 不是银弹实际使用中也有一些边界。第一长对话的规则遗忘。一次很长的会话里AI 可能在中后段忽略之前的技能约束。解决办法是把大任务拆成多个小步骤并在关键步骤里简单复述规则比如在 prompt 末尾加一句注意按 vue-code 技能包规范输出。第二人工智能对架构级问题仍然无能为力。技能包可以管住怎么写但管不住为什么这么设计。一个新页面到底该放在哪个模块下、API 该怎么设计、组件抽象到什么粒度这类偏业务语义的问题仍然需要人来决策。第三技能的过度约束风险。如果 SKILL.md 写得太死AI 会变得畏手畏脚遇到特殊情况不会变通。我的经验是分两层硬规则比如禁止 any、必须 scoped和软建议比如可以考虑拆分。硬规则一定顶格执行软建议留给 AI 判断。另外还要提醒一点不同工具的 Skills 机制还在快速迭代今天能用的路径和加载方式下个版本可能就变了。别把知识焊死在记忆里以官方文档为准定期检查技能包是否还在生效。最后再分享一点个人体会把 AI 调教好本质上和带一个新人前端工程师没有区别。你不能指望他第一天就懂你们项目所有约定但你可以给他一本好手册让他少犯低级错误。Vue Skills 就是这本手册而且它比人更听话——只要规则写得足够明确AI 的交规遵守率甚至会超过记性不好的同事。迭代了一个多月我的习惯是每发现一次 review 里让 AI 重写代码的情况就立刻想这是不是一个可以沉淀进 Skills 的规则。如果是就花两分钟补进去。这样每次教训都不会白费技能包会越来越贴合项目。如果你也想做这件事我的建议是别追求一步到位。先写技术栈基线和目录规则这两个最基础的章节马上投入使用。等发现 AI 出现了某种新问题再针对性地加规则。这样滚动迭代两到三周后你就能得到一份让你 code review 轻松很多的 Vue Skills。最后再分享一个小技巧在 SKILL.md 里加一条输出前自查清单让 AI 在完成代码后逐项自检一遍。这个词我后来反复在各种项目里用效果出奇地好。很多 AI 犯错不是不知道规则而是生成时没来得及检查。自查清单相当于是给它的代码加了一道接近零成本的自动化 review规则命中率能提高一大截。