vue-best-practices

vue-best-practices 技能概览

vue-best-practices 是做什么的

vue-best-practices 是一个面向 Vue 的指令型技能，适用于 Vue 3 项目中的代码生成、代码评审和重构。它的核心目标不只是“写出 Vue 代码”，而是“按照当前主流且能在真实项目压力下长期维护的架构默认值来写 Vue 代码”。实际使用中，它会引导代理优先采用 Composition API、<script setup lang="ts">、显式数据流，以及很多通用前端提示词常常忽略的 Vue 专属决策方式。

谁适合安装 vue-best-practices

如果你是团队开发者或独立开发者，正在使用 Vue 3、.vue 单文件组件、Vue Router、Pinia 风格状态管理、基于 Vite 的应用，或支持 SSR 的 Vue 应用，那么这个技能会很合适。尤其当你希望 AI 助手不再跑偏到泛用 JavaScript 写法，而是稳定遵循 Vue 原生约定时，vue-best-practices 的价值会更明显。

它真正解决的工作问题

vue-best-practices 的真实价值，在于在动手编码前就尽量减少那些本可避免的设计失误。这个技能会明确要求代理先确认架构，再把几个核心参考保持在活跃上下文里：响应式机制、SFC 结构、组件数据流和 composables。相比一句普通的“帮我做个组件”，它对实现层面的决策更有帮助。

这个技能和普通提示词有什么不同

vue-best-practices 的差异点在于它有一条明确的决策路径。它不只是说一句“请用 Vue 3”，而是先设定默认做法和边界条件：

• 默认采用 Composition API 和 <script setup lang="ts">
• 如果项目明确是 Options API 或 JSX，应切换到别的技能
• 将 props、emits、v-model、provide/inject、异步组件、过渡动画和性能问题都视为一等设计事项
• 遇到边界情况时优先查阅针对性的参考文档，而不是只靠模型记忆

什么情况下 vue-best-practices 很适合

当你需要 vue-best-practices for Frontend Development 来处理下面这些问题时，它通常很对路：

• 创建或重构 Vue 组件
• 在 props/emits、v-model、provide/inject 或 store 之间做取舍
• 设计 composable
• 在 SSR 场景下决定异步组件策略
• 设计 slot API、处理 fallthrough attrs、过渡动画、KeepAlive 和长列表性能
• 评审某个 Vue 实现是否足够地道，而不只是“能跑”

什么情况下它不是合适的选择

如果代码库本身就是刻意以 Options API 为主，或高度依赖 JSX，那么不要把 vue-best-practices 当成主要指导。这个技能本身也写明了：遇到这类情况，如果有更合适的技能，就应该切换。它也不能替代框架专属文档，例如 Nuxt 路由、测试配置，或参考资料未覆盖的部署问题。

如何使用 vue-best-practices 技能

vue-best-practices 的安装上下文

先安装父级技能仓库，再从该技能集合中调用 vue-best-practices：

npx skills add vuejs-ai/skills --skill vue-best-practices

仓库路径为：
skills/vue-best-practices

GitHub 源地址：
https://github.com/vuejs-ai/skills/tree/main/skills/vue-best-practices

先读这些文件

如果你想快速抓住重点，建议先看：

• skills/vue-best-practices/SKILL.md
• skills/vue-best-practices/references/reactivity.md
• skills/vue-best-practices/references/sfc.md
• skills/vue-best-practices/references/component-data-flow.md
• skills/vue-best-practices/references/composables.md

这四份 references 在技能本体里被明确标为必须先读的核心上下文。如果跳过它们，你基本会错过这个技能大部分真正有用的部分。

使用 vue-best-practices 时，你需要提供哪些输入

vue-best-practices usage 的效果，会在你提供架构上下文而不只是功能需求时明显提升。最低限度的有效输入包括：

• Vue 版本，以及是否为 Vue 3
• 项目是否已经使用 TypeScript
• 代码库要求使用 Composition API、Options API 还是 JSX
• router/store 的上下文
• 是 SSR 还是纯客户端场景
• 这个组件承担什么职责
• 现有父子组件之间的数据流
• 对性能、可访问性或包体积的限制

弱提示词只会说“帮我做个组件”。强提示词会交代这个组件位于应用的哪个位置、数据应该如何流动。

把模糊需求变成高质量提示词

弱版本：

• “Build a Vue modal.”

更强的版本：

• “Using vue-best-practices, create a Vue 3 modal component with <script setup lang="ts">. The modal is controlled by the parent via props and emits, must support v-model:open, trap focus, Teleport to body, and avoid mutating props internally. Show the component API, parent usage, and explain why props/emits are better here than provide/inject.”

这种写法给了技能足够的上下文，能真正用上它在数据流和组件 API 设计方面的指导。

第一次使用 vue-best-practices 的最佳工作流

一个实用的 vue-best-practices guide 通常可以按下面的流程来：

1. 在要代码之前，先确认项目架构。
2. 明确说明 Composition API 是否是默认做法。
3. 要求代理先查阅核心 references。
4. 如果组件边界还不清晰，先让它给出实现方案，再进入代码。
5. 生成组件代码。
6. 再做第二轮，只聚焦 Vue 特有的审查点：响应式、attrs、slots、性能和 SSR 行为。

这个流程和该技能“编码前先确认架构”的核心思路是一致的。

如何提出正确的架构决策问题

这个技能最有价值的地方，在于你把问题提成“要做什么决策”，而不是直接让它“吐一段代码”。好的提问方式例如：

• “Should this state live in the parent, a composable, or Pinia?”
• “Is v-model appropriate here or should this be explicit props/emits?”
• “Should this large list use virtualization?”
• “Is <Transition> correct here, or would class-based animation be simpler?”
• “Should this component be async-loaded in SSR?”

这些问题都能直接映射到仓库里的对应参考资料。

不同任务值得带上的参考文件

可以按任务类型有选择地引入这些 references：

• references/component-async.md：用于懒加载和 SSR hydration 时机
• references/component-slots.md：用于 slot API 设计和 defineSlots
• references/component-fallthrough-attrs.md：用于 $attrs 和 useAttrs()
• references/component-keep-alive.md：用于缓存行为和陈旧状态风险
• references/component-transition.md 和 references/component-transition-group.md：用于进入/离开动画场景
• references/animation-class-based-technique.md：用于非挂载/卸载类效果
• references/state-management.md：用于状态归属决策
• references/perf-virtualize-large-lists.md：用于大列表渲染
• references/perf-v-once-v-memo-directives.md：用于选择性渲染优化

哪些实用提示词模式更容易拿到好结果

尽量使用同时要求“代码 + 解释”的提示词。例如：

• “Apply vue-best-practices and explain the chosen data-flow model.”
• “Refactor this component to Composition API with <script setup lang="ts">, and call out any reactivity pitfalls.”
• “Review this .vue file against vue-best-practices and classify issues as architecture, data flow, performance, or API design.”
• “Implement this feature and list which Vue references were used.”

这样能迫使助手把自己的假设说出来，而不是悄悄脑补一套模式。

常见的落地阻碍

最大的阻碍通常是技能默认值与实际代码库不匹配。比如你的项目是老版本 Vue、以 Options API 为主，或者大量使用 JSX/render functions，那么这个技能的默认路径反而可能带来额外改动成本。另一个常见问题是状态归属描述得太少。很多 Vue 错误，都来自只描述 UI 行为，却不说明状态到底归谁管理，结果导致错误的 prop mutation，或含糊不清的双向绑定。

生成之后要重点核查什么

在使用完 vue-best-practices skill 之后，建议重点检查：

• 子组件是否没有直接修改 props
• 使用 TypeScript 时，emits 是否显式且有类型
• 是否在 computed 更合适的地方误用了 watch
• composables 是否只承载可复用逻辑，而不是意外共享状态
• 异步组件是否带来了糟糕的加载体验
• attrs、slots 和 transitions 是否符合 Vue 约定
• 性能优化手段是否有明确依据，而不是机械套用

vue-best-practices 技能 FAQ

vue-best-practices 对新手友好吗

友好，但对新手来说，把它当成评审助手，通常比当成盲目代码生成器更有帮助。因为 references 不只是告诉你“怎么写”，还会解释为什么某些 Vue 模式更推荐，这能帮助新手尽早避开反模式。

vue-best-practices 只支持 Vue 3 吗

就默认路径来说，基本可以视为是。这个技能强烈围绕 Vue 3、Composition API、<script setup>、TypeScript、SSR 感知模式、Volar 和 vue-tsc 展开。如果你的应用还是 Vue 2，或者正处在大量迁移阶段，它就不是最佳选择。

vue-best-practices 和普通提示词有什么区别

普通提示词也许能产出“看起来像 Vue 且能运行”的代码。vue-best-practices 则会给助手一个明确的架构偏向和阅读顺序。在 Vue 里，这一点很关键，因为响应式、组件通信、attrs、缓存和 slots 上的错误，往往一开始看不出问题，但后期会迅速变成维护负担。

vue-best-practices 适合现有代码库吗

适合，尤其适用于重构和评审。很多时候，它在现有组件上的价值甚至高于新项目，因为它能帮助你识别状态归属不清、组件职责膨胀，以及成熟应用里很容易被忽略的 Vue 特有正确性问题。

我应该把它用于 Pinia、Router 和 SSR 任务吗

可以，前提是任务本质上仍然属于 Vue 架构或组件行为问题。技能描述里已经明确覆盖了 Vue Router、Pinia、基于 Vue 的 Vite，以及 SSR 相关关注点。你只需要在提示词里把这些约束说清楚，避免代理默认按更简单的纯客户端场景来处理。

什么情况下不该用 vue-best-practices

遇到下面这些情况，建议跳过它：

• 项目明确要求遵循 Options API 约定
• 项目主要使用 JSX 作为编写方式
• 你需要仓库 references 之外的框架专属指导
• 你只想快速做一个一次性原型，并不在意 Vue 是否写得地道

如何把 vue-best-practices 用得更好

给 vue-best-practices 更强的架构输入

想最快提升输出质量，最有效的做法是明确说明：

• 状态归谁拥有
• 组件边界如何划分
• 父子组件 API 的预期
• 是否必须使用 TypeScript
• 是 SSR 还是纯客户端渲染
• 预期规模，比如大列表或缓存视图

否则，这个技能只能去猜它本该被明确告知的设计取舍。

先要方案，再要实现

对于稍复杂的任务，建议先问：

• 状态应该放在哪里
• 这个功能应该归为 component、composable 还是 store
• 组件间通信应使用 props/emits、v-model、provide/inject，还是 router/store state

这符合仓库“架构优先”的规则，通常比直接要求“写得干净一点”更能改善第一版代码质量。

有意识地使用 reference 库

vue-best-practices skill 在 references/ 目录里的内容并不浅。更好的结果，往往来自你在提示词里直接点名相关文件：

• “Use component-data-flow.md logic”
• “Check component-async.md because this is SSR”
• “Apply component-fallthrough-attrs.md because this wrapper forwards attrs”
• “Use perf-virtualize-large-lists.md because this table can exceed 5,000 rows”

这正是它相对泛用提示词的实际优势之一。

警惕 vue-best-practices 最常见的失败模式

典型的低质量输出，往往出现在助手做了这些事的时候：

• 直接修改 props，而不是通过 emit 更新
• 在 computed 足够的地方用了 watchers
• 过早选择 provide/inject
• 把本该做成 composable 的逻辑包进组件里
• 明明 class-based animation 更简单，却硬加 transitions
• 使用 <KeepAlive> 缓存视图，却没有配套的新鲜度策略
• 在没有证据的情况下给出过早的微优化建议

而这些，正是 vue-best-practices 试图帮你减少的问题。

第一稿之后，优化你的评审提示词

代码生成完成后，可以追加第二轮，例如：

• “Review this against vue-best-practices and list the top 5 risks.”
• “Find any reactivity edge cases or data-flow violations.”
• “Check whether this slot API and fallthrough attrs behavior are robust.”
• “Audit this SSR component for async loading and hydration concerns.”

第一轮的作用是产出代码，第二轮才更能逼出这个技能的真正价值。

用明确交付物让输出更可落地

如果你想让 vue-best-practices usage 的结果更扎实，建议直接要求输出包含：

• 最终代码
• 一段简短的架构说明
• 被否决的备选方案列表
• 如果是重构现有代码，给出迁移说明
• 一个针对 vue-tsc、Volar 和运行时行为的验证清单

这种格式能有效减少表面化回答，也更方便你直接落到真实仓库里使用。