用途
Vue Best Practices 是一份以指令集形式提供的 Vue.js 开发工作流技能。其定位是：当任务涉及 Vue.js 时使用，并强烈推荐以 Composition API 配合 <script setup> 和 TypeScript 作为标准方案。使用者应按工作流顺序执行，除非用户明确要求不同的顺序。
主要能力与核心原则
技能首先给出若干核心原则：保持状态可预测（单一事实来源，其余尽量派生）；让数据流显式（多数场景 Props 向下、Events 向上）；倾向于小而专注的组件；避免不必要的重渲染（合理使用 computed 与 watcher）；可读性优先，编写清晰、自解释的代码。
1. 编码前确认架构（必需）
默认技术栈为 Vue 3 + Composition API + <script setup lang="ts">。如果项目明确使用 Options API，则在可用时加载 vue-options-api-best-practices 技能；如果明确使用 JSX，则在可用时加载 vue-jsx-best-practices 技能。
技能要求在实现任何 Vue 任务前阅读并应用以下核心参考，并在整个任务期间保持在工作上下文中：
- references/reactivity.md
- references/sfc.md
- references/component-data-flow.md
- references/composables.md
同时要求在编码前规划组件边界：为非平凡功能创建简短的组件映射，用一句话定义每个组件的单一职责；默认将入口/根组件与路由级视图组件作为组合表面；除非任务是有意为之的极简单文件演示，否则将功能 UI 与功能逻辑移出入口/根/视图组件；为映射中的每个子组件定义 props/emits 契约；当添加超过一个组件时，优先采用功能文件夹布局（components/<feature>/...、composables/use<Feature>.ts）。
2. 应用必要的 Vue 基础（必需）
这部分要求在每个 Vue 任务中全部应用：
响应式：保持源状态最小化（ref/reactive），尽可能用 computed 派生；必要时用 watcher 处理副作用；避免在模板中重复计算昂贵逻辑。
SFC 结构与模板安全：SFC 各区块保持 <script> → <template> → <style> 的顺序；保持职责专注，拆分过大组件；模板保持声明式，将分支/派生逻辑移入脚本；应用 Vue 模板安全规则（涉及 v-html、列表渲染、条件渲染的选择）。
保持组件专注：当组件承担多个明确职责时进行拆分；优先使用更小的组件加 composables，而非“巨型组件”；将 UI 区块移入子组件（props 进、events 出），将状态/副作用移入 composables（useXxx()）。技能还给出客观的拆分触发条件，例如：同时拥有编排/状态与多个区块的大量展示性标记；拥有 3 个以上不同 UI 区块（如表单、筛选、列表、页脚/状态）；某模板块被重复使用或可复用（列表行、卡片、列表条目）。对于 CRUD/列表类功能（todo、table、catalog、inbox），至少拆分为：功能容器组件、输入/表单组件、列表（和/或条目）组件、页脚/操作或筛选/状态组件。仅允许非常小的临时演示使用单文件实现，且若选择单文件，需明确说明为何无需拆分。
组件数据流：以 props 向下、events 向上为主要模型；仅对真正的双向组件契约使用 v-model；仅对深层树依赖或共享上下文使用 provide/inject；用 defineProps、defineEmits 以及必要的 InjectionKey 保持契约显式且带类型。
Composables：当逻辑被复用、有状态或副作用较重时，将其抽取为 composables；保持 composable API 小、有类型且可预测；将功能逻辑与展示型组件分离。
Vue 3.5+ API：在 Vue 3.5 或更新版本上应用——优先使用解构默认值而非 withDefaults()，注意 getter 边界规则（reactive-props-destructure）；在手工实现之前先使用 3.5 内置能力：useId、onWatcherCleanup、<Teleport defer>、lazy hydration（vue-3-5-helpers）。
3. 仅当需求需要时考虑可选特性
标准可选特性不应默认添加，仅当需求存在时加载对应参考：Slots（父组件控制子内容/布局）、Fallthrough 属性（包装/基础组件安全转发 attrs/events）、<KeepAlive>（有状态视图缓存）、<Teleport>（浮层/传送门）、<Suspense>（异步子树回退边界）。动画相关特性需选择与所需动效行为匹配的最简方案：<Transition> 用于进入/离开效果，<TransitionGroup> 用于动画化列表变更，基于 class 的动画用于非进入/离开效果，状态驱动动画用于由用户输入驱动的动画。
较少见的可选特性仅在明确的产品或技术需求下使用：指令（行为特定于 DOM，不适合 composable/组件）、异步组件（重型/极少使用的 UI 应懒加载）、渲染函数（仅当模板无法表达需求时）、插件（行为需应用级安装时）、状态管理模式（应用级共享状态跨越功能边界时）。
4. 行为正确后再进行性能优化
性能工作是功能完成后的环节，不要在核心行为实现并验证前优化。涉及方向包括：大列表渲染瓶颈（perf-virtualize-large-lists）、静态子树不必要的重渲染（perf-v-once-v-memo-directives）、热列表路径中的过度抽象（perf-avoid-component-abstraction-in-lists）、过于频繁触发的昂贵更新（updated-hook-performance）。实验性内容：经测量的渲染热点可能证明 Vapor Mode 合理（Vue 3.6，可选启用，不稳定），但不应默认启用。
5. 完成前的最终自检
技能列出自检清单：核心行为可用且符合需求；所有必读参考均已阅读并应用；响应式模型最小且可预测；遵循 SFC 结构与模板规则；组件专注且良好分解，必要时拆分；入口/根与路由视图组件保持为组合表面，除非有明确的小型演示例外；组件拆分决策显式且可辩护（职责边界清晰）；数据流契约显式且有类型；在复用/复杂度合理处使用 composables；如适用，已将状态/副作用移入 composables；仅当需求要求时使用可选特性；仅在功能完成后才应用性能变更。
适用场景与限制
适用场景为涉及 Vue.js 的开发任务，尤其是希望按统一规范落地 Vue 3 项目、需要在编码前规划组件边界与数据流契约的场景。限制方面：资料未说明收费、价格、平台支持范围或具体效果数据；其中提到的各类参考文件（references/*.md）与可选技能（vue-options-api-best-practices、vue-jsx-best-practices）在实际使用中的获取方式暂未提供；Vapor Mode 被标注为实验性、不稳定且不默认启用。