vue-best-practices

vue-best-practices skill 概覽

vue-best-practices 的用途

vue-best-practices 是一個專注於 Vue 的指令型 skill，適合用在 Vue 3 專案中的程式碼產生、審查與重構。它的核心任務不只是「寫出 Vue 程式碼」，而是「依照當代主流架構預設，寫出在真實專案壓力下依然容易維護的 Vue 程式碼」。實務上，它會引導代理優先採用 Composition API、<script setup lang="ts">、明確的資料流，以及一般前端提示常常忽略的 Vue 專屬設計判斷。

誰適合安裝 vue-best-practices

vue-best-practices 特別適合正在使用 Vue 3、.vue 單檔元件、Vue Router、Pinia 風格狀態管理、Vite 應用，以及具備 SSR 能力的 Vue 專案的團隊與個人開發者。如果你希望 AI 助手不要再偏向泛用 JavaScript 寫法，而是穩定遵循 Vue 原生慣例，這個 skill 會很有幫助。

真正要解決的工作

vue-best-practices 的真正價值，在於於動手寫碼前先減少可避免的設計錯誤。這個 skill 會明確要求代理先確認架構，再把幾個核心參考維持在當前上下文中：reactivity、SFC 結構、元件資料流與 composables。和單純一句「幫我做這個 component」相比，它對實作決策更有幫助。

這個 skill 有什麼不同

vue-best-practices 的差異化重點在於它的決策路徑。它不只是說「使用 Vue 3」，而是先建立預設與邊界：

• 預設採用 Composition API 與 <script setup lang="ts">
• 如果專案明確是 Options API 或 JSX，應切換到其他 skill
• 把 props、emits、v-model、provide/inject、async components、transitions 與效能視為一等設計議題
• 遇到邊界情況時，優先查對應參考文件，而不是只靠記憶作答

什麼情況下 vue-best-practices 特別適合

當你需要 vue-best-practices for Frontend Development 來協助以下工作時，它通常很適合：

• 建立或重構 Vue components
• 在 props/emits、v-model、provide/inject 或 store 之間做選擇
• 設計 composable
• 做出考量 SSR 的 async component 選擇
• 設計 slot API、處理 fallthrough attrs、transitions、KeepAlive 與大型清單效能
• 檢查某個 Vue 實作是否符合慣用寫法，而不只是「能動就好」

什麼情況下它不是對的 skill

如果你的 codebase 本來就刻意以 Options API 為主，或大量使用 JSX，請不要把 vue-best-practices 當成主要指引。這個 skill 本身也明說，在這些情況下若有其他可用 skill，應該改載入別的。它也不能取代框架專屬文件，像是 Nuxt routing、測試設定，或參考資料未涵蓋的部署議題。

如何使用 vue-best-practices skill

vue-best-practices 的安裝與使用脈絡

先安裝上層 skill repository，再從該集合中呼叫 vue-best-practices skill：

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

Repository 路徑為：
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 在 skill 本身就被列為必讀核心上下文。如果跳過它們，你幾乎會失去這個 skill 大部分的實用價值。

這個 skill 需要你提供哪些輸入

當你提供的是架構背景，而不只是功能需求時，vue-best-practices usage 的效果會明顯提升。最低限度有用的輸入包括：

• Vue 版本，以及是否為 Vue 3
• 專案是否已經使用 TypeScript
• codebase 需要的是 Composition API、Options API，還是 JSX
• router/store 的脈絡
• SSR 還是純 client-only 的情境
• 這個 component 的職責
• 既有的 parent/child 資料流
• 對效能、無障礙或 bundle size 的限制

弱的 prompt 只會要求做一個 component；強的 prompt 會說清楚這個 component 在整個 app 中的位置，以及資料應該如何流動。

把模糊需求變成有力的 prompt

弱：

• “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.”

這種寫法能提供 vue-best-practices 足夠的上下文，讓它真正套用資料流與 component API 的判斷原則。

第一次使用的最佳流程

一套實用的 vue-best-practices guide 可以這樣跑：

1. 在要求產生程式碼之前，先確認專案架構。
2. 明確說明 Composition API 是否為預設。
3. 要求代理先查閱核心 references。
4. 如果 component 邊界還不清楚，先請它提出實作方案再寫碼。
5. 產生 component。
6. 再跑第二輪，專注做 Vue 專屬審查：reactivity、attrs、slots、效能與 SSR 行為。

這個流程正好對應 skill 所強調的「先確認架構，再開始寫碼」。

如何提出正確的架構決策問題

當問題被表述成「決策題」而不是「直接吐一段程式碼」時，這個 skill 最有價值。好的例子包括：

• “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?”

這些問題都能直接對應到 repository 中的相關 references。

依任務挑選值得帶入的 reference 檔案

請依任務有選擇地使用以下 references：

• references/component-async.md：處理 lazy loading 與 SSR hydration 時機
• references/component-slots.md：slot API 設計與 defineSlots
• references/component-fallthrough-attrs.md：$attrs 與 useAttrs()
• references/component-keep-alive.md：快取行為與 stale state 風險
• references/component-transition.md 與 references/component-transition-group.md：進場／離場情境
• references/animation-class-based-technique.md：非 mount/unmount 類效果
• references/state-management.md：狀態歸屬的決策
• references/perf-virtualize-large-lists.md：大型清單渲染
• references/perf-v-once-v-memo-directives.md：選擇性渲染最佳化

哪些實用 prompt 模式能得到更好的輸出

建議使用同時要求「程式碼 + 理由」的 prompts。例如：

• “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.”

這樣可以迫使助理把它的假設攤開，而不是默默編造一套模式。

常見的導入阻礙

最大的阻礙通常是 skill 預設與實際 codebase 不一致。如果你的專案是舊版 Vue、以 Options API 為主，或大量依賴 JSX/render functions，這個 skill 的預設很可能帶來不必要的來回修改。另一個常見阻礙，是沒有明確交代狀態歸屬。很多 Vue 問題都來自只描述 UI 行為、卻沒說清楚誰擁有 state，最後就容易出現錯誤的 prop mutation 或模糊的雙向綁定。

產生結果後要驗證什麼

使用完 vue-best-practices skill 後，請至少檢查：

• children 是否沒有直接 mutate props
• 使用 TypeScript 時，emits 是否明確且有型別
• 是否在 computed 就能解決的情況下誤用了 watch
• composables 是否承載可重用邏輯，而不是意外形成共享 state
• async components 是否造成不佳的 loading UX
• attrs、slots 與 transitions 是否符合 Vue 慣例
• 採用的效能技巧是否有根據，而不是為了最佳化而最佳化

vue-best-practices skill 常見問題

vue-best-practices 對初學者友善嗎

是，但對初學者來說，vue-best-practices 更適合作為 reviewer，而不是盲目幫你生碼的工具。references 會說明為什麼某些 Vue 模式更值得優先採用，能幫助新手不要太早學到 anti-pattern。

vue-best-practices 只支援 Vue 3 嗎

就它的預設路徑來說，實際上是的。這個 skill 明確聚焦在 Vue 3、Composition API、<script setup>、TypeScript、具 SSR 意識的模式、Volar 與 vue-tsc。如果你的 app 還在 Vue 2，或處於大量 migration 的階段，它就不是最佳選擇。

vue-best-practices 和一般 prompt 有什麼不同

一般 prompt 可能會產出一段看起來能跑的 Vue 風格程式碼；vue-best-practices 則會給助理一個明確的架構傾向，以及一套閱讀順序。這在 Vue 特別重要，因為 reactivity、元件溝通、attrs、快取與 slots 的問題，常常一開始看似沒事，久了卻很容易變得難維護。

vue-best-practices 適合既有 codebase 嗎

適合，尤其適合用於重構與審查。很多時候，它在既有 components 上比在 greenfield 專案上更有價值，因為它能協助找出狀態歸屬不清、元件責任膨脹，以及成熟 app 中很容易被忽略的 Vue 專屬正確性問題。

我應該用它處理 Pinia、Router 與 SSR 任務嗎

可以，前提是任務本質上仍然是 Vue 架構或元件行為問題。skill 描述中已明確涵蓋 Vue Router、Pinia、Vite with Vue 與 SSR 相關議題。只要你在 prompt 中把這些限制交代清楚，代理就不會誤以為這只是單純的 client-only 情境。

什麼時候不該用 vue-best-practices

以下情況建議略過：

• 專案明確要求遵循 Options API 慣例
• 專案主要以 JSX 作為撰寫方式
• 你需要 repository references 範圍外的框架專屬指引
• 你只想快速做一個一次性 prototype，並不在意 Vue 慣用寫法

如何改進 vue-best-practices skill 的使用效果

為 vue-best-practices 提供更強的架構輸入

想最快提升輸出品質，請明確指定：

• state owner
• component 邊界
• parent/child API 預期
• 是否必須使用 TypeScript
• SSR 還是 client-only rendering
• 預期規模，例如大型清單或需要快取的 views

否則這個 skill 就只能自行猜測那些原本應該被明說的設計取捨。

先要求方案，再要求實作

對於不是太單純的工作，先問：

• 哪些 state 應該放在哪裡
• 這個功能應該屬於 component、composable，還是 store
• 溝通方式應該用 props/emits、v-model、provide/inject，還是 router/store state

這樣做符合 repository「架構優先」的原則，通常比直接要求「請寫乾淨的程式碼」更能提升第一版輸出品質。

有意識地使用 reference library

vue-best-practices skill 在 references/ 資料夾裡有相當實用的深度內容。若你在 prompt 中直接點名相關檔案，結果通常會更好：

• “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”

這也是它相較於泛用 prompting 的實際優勢之一。

留意最常見的失敗模式

典型的低品質輸出，通常發生在助理：

• 直接 mutate props，而不是透過 emit 更新
• 在 computed 就足夠時仍使用 watcher
• 太早選擇 provide/inject
• 把本該做成 composable 的邏輯包進 component
• 在 class-based animation 更簡單時仍硬加 transitions
• 用 <KeepAlive> 快取 views，卻沒有設計 freshness strategy
• 在沒有證據的情況下提出過早的微型最佳化

而這些正是 vue-best-practices 想幫你減少的問題類型。

第一版之後，優化你的 review prompts

程式碼產生完後，可以再加一輪這種 second pass：

• “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.”

第一輪是把程式碼做出來；第二輪才是把這個 skill 的真正價值挖出來。

用明確交付物讓輸出更容易落地

如果你想讓 vue-best-practices usage 更有可用性，建議直接要求：

• 最終程式碼
• 一段簡短的架構說明
• 被排除的替代方案清單
• 若是重構既有程式碼，附上 migration notes
• 針對 vue-tsc、Volar 與 runtime behavior 的驗證清單

這種格式能有效降低空泛回答，也更方便把結果真正帶進實際 repo 中使用。