vue-options-api-best-practices

vue-options-api-best-practices 技能總覽

這個技能能幫你處理什麼

vue-options-api-best-practices 是一套聚焦型指引，專門協助你撰寫與審查使用 Options API 的 Vue 3 元件，特別適合仍以 data()、methods、生命週期 hooks 與基於 this 的元件邏輯為主流寫法的程式碼庫。它真正的用途不是從零教你學 Vue，而是幫你避開那些會讓 Options API 程式碼變得脆弱、難以型別化，或具誤導性的常見錯誤。

最適合仍在交付 Options API 的團隊

這個技能特別適合維護 Vue 2 升級到 Vue 3 過渡期的前端開發者、已將 Options API 視為團隊標準的企業級 Vue 專案，或是在較舊元件模式下搭配 TypeScript 的團隊。如果你的日常工作常碰到 defineComponent、props 型別、生命週期 hooks，或修正 this 相關問題，vue-options-api-best-practices 會是很實用的選擇。

它和一般 Vue 提示詞有什麼不同

一般提示詞很可能給你 Composition API 範例、混用不同模式，或直接忽略 TypeScript 的邊界情況。這個技能則會明確聚焦在 Options API 解法，並點出具體陷阱，例如：

• 在 methods 與生命週期 hooks 中使用 arrow function，導致 this 綁定失效
• 帶狀態的 debounce 或 throttle 方法被多個元件實例共用
• TypeScript 在 props、computed、事件與 inject 型別上的特有限制
• 舊版 TypeScript 在 prop validator 上的相容性注意事項

什麼情況下值得安裝這個技能

當你希望在既有 Options API 元件內進行重構、code review、類 lint 的修正，或做出對遷移安全的調整，而且想得到一致、低猜測成本的答案時，就很適合安裝 vue-options-api-best-practices。尤其當你需要模型尊重既有結構，而不是「好心地」把整份程式碼全部改寫成 Composition API 時，這個技能特別有價值。

如何使用 vue-options-api-best-practices 技能

vue-options-api-best-practices 的安裝情境

請在 agent 可讀取專案檔案的環境中，從 vuejs-ai/skills repository 加入這個技能。常見安裝方式如下：

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

如果你的環境使用不同的 loader，重點是要啟用 skills/vue-options-api-best-practices 資料夾，讓 agent 能讀取 SKILL.md 與 reference/ 底下的檔案。

先讀這些檔案

對這個技能來說，最高效且最有價值的閱讀順序是：

1. skills/vue-options-api-best-practices/SKILL.md
2. skills/vue-options-api-best-practices/reference/no-arrow-functions-in-methods.md
3. skills/vue-options-api-best-practices/reference/no-arrow-functions-in-lifecycle-hooks.md
4. skills/vue-options-api-best-practices/reference/stateful-methods-lifecycle.md
5. 依你的問題對應閱讀 TypeScript 參考文件：
   • reference/ts-options-api-use-definecomponent.md
   • reference/ts-strict-mode-options-api.md
   • reference/ts-options-api-proptype-complex-types.md
   • reference/ts-options-api-type-event-handlers.md
   • reference/ts-options-api-provide-inject-limitations.md
   • reference/ts-options-api-computed-return-types.md
   • reference/ts-options-api-arrow-functions-validators.md

這個技能需要哪些輸入

vue-options-api-best-practices 在你提供實際元件程式碼或接近完整的片段時效果最好，而且要明確說明答案必須維持在 Options API。建議一併提供：

• Vue 版本
• TypeScript 版本（若相關）
• 目前的元件程式碼
• 明確的 bug、警告或重構目標
• 是否禁止使用 Composition API
• 是否會同時存在多個元件實例

如果缺少這些脈絡，模型可能會抓不到某個模式為什麼不安全。

把模糊需求改寫成高品質提示

弱提示：
「Fix this Vue component.」

較強的提示：
「Use the vue-options-api-best-practices skill. Keep this component in Vue 3 Options API with defineComponent. Identify any this binding issues, prop typing problems, and lifecycle mistakes. If debounce or throttle is present, make sure each component instance gets its own stateful function and include cleanup in unmounted().」

這種寫法能清楚告訴技能要套用什麼品質標準，以及哪些東西不能改。

用於 code review 的提示範本

在審查既有檔案時可使用：

「Apply vue-options-api-best-practices to this component. Return:

1. a short issue list grouped by severity,
2. the corrected Options API code,
3. why each change matters,
4. any TypeScript-specific follow-up needed.」

這種格式效果很好，因為技能內的參考文件本來就是按具體陷阱整理，而不是停留在寬泛的風格意見。

用於 TypeScript 修正的提示範本

如果你的主要問題是型別，提問時請帶上版本與症狀：

「Use vue-options-api-best-practices for Frontend Development. This is a Vue 3 Options API component on TypeScript 4.6. Fix typing for props, computed properties, event handlers, and injected values without converting to Composition API. Explain any legacy TS workaround that applies.」

這樣可以明確觸發技能中對應的 TypeScript 參考內容，包括 4.7 之前 validator 的注意事項。

這個技能最擅長落實的高價值規則

vue-options-api-best-practices 最值得用來檢查的重點包括：

• 絕對不要在 methods 中使用 arrow function
• 絕對不要在 Options API 的生命週期 hooks 中使用 arrow function
• 將 debounce 或 throttle 這類具狀態的方法，在 created() 中建立成每個實例各自獨立的方法
• 在 unmounted() 中清理帶狀態的函式
• 使用 defineComponent 改善型別推斷
• 針對複雜的 object、array、function 或 union props 使用 PropType
• 當 computed 的推斷不夠清楚時，補上明確的回傳型別
• 在 Options API 中謹慎處理 inject 的型別

這些問題最容易造成執行期 bug，或讓 TypeScript 報出令人困惑的錯誤。

一個好的使用請求範例

實際可用的 vue-options-api-best-practices usage 請求可以長這樣：

「Use vue-options-api-best-practices on the component below. Keep Options API only. Find any broken this usage, convert invalid arrow-function methods or hooks, and improve TypeScript for complex props and computed values. If any debounced method is shared across instances, move setup to created() and add teardown in unmounted().」

在遷移流程中如何使用它

如果你的程式碼庫正逐步遷移，建議把這個技能當作護欄，而不是一次性的大改寫工具：

1. 先拿一個有明確 bug 或型別問題的元件測試
2. 檢查 diff，確認模式上的改動
3. 把可接受的修正整理進團隊慣例
4. 對相似元件套用相同提示
5. 確認穩定後，再擴大到資料夾或批次處理

這樣可以降低 churn，也能讓技能更貼合你現有的架構。

安裝前應先了解的實際限制

這個技能本來就設計得很聚焦。當你的元件本身已經遵循 Options API 慣例時，它的幫助最大。以下情況就比較不是它的強項：

• Composition API 專案
• 元件之外的 Nuxt 或其他框架特定架構問題
• 樣式、測試或 build pipeline 問題
• 超出現有 Options API 參考範圍的進階 reactivity 設計

如果你的主要需求是「教我 Vue」，那它太專門了；但如果你的需求是「避免那些隱性的 Options API 錯誤」，它就很對症。

vue-options-api-best-practices 常見問題

vue-options-api-best-practices 對新手友善嗎

算是友善，前提是你已經看得懂基本的 Vue 元件結構。這些參考文件都很具體，也有範例導向，所以新手可以拿它來更安全地修正實際程式碼。它不是完整的 Vue 教學課程，但對常見的 Options API 錯誤來說，是很強的修正指引。

這個技能只支援 Vue 3 嗎

整體描述以 Vue 3 Options API 為核心，但其中一些核心建議同樣適用於 Vue 2 風格的 Options API，尤其是 methods 與生命週期 hooks 中 this 綁定的規則。至於 TypeScript 相關建議，則在 Vue 3 搭配 defineComponent 時最有參考價值。

vue-options-api-best-practices 會比一般提示詞更好嗎

對這類需求來說，通常是的。它最大的價值在於控制範圍：答案會留在 Options API、會主動指出已知陷阱，也會避免那種很泛的「乾脆改寫成 Composition API」建議。對維護型團隊與 code review 流程來說，因此更實用。

什麼情況不該使用 vue-options-api-best-practices

如果你的專案主要是 Composition API、<script setup>，或是框架特定程式碼，且 Options API 問題不是核心，那就不適合選 vue-options-api-best-practices。它也不是處理一般前端架構設計，或無關的 TypeScript 工具鏈問題的正確技能。

vue-options-api-best-practices 安裝後有包含自動化功能嗎

沒有證據顯示這個技能資料夾內含任何 bundled scripts 或自動檢查機制。它的價值在於整理過的參考指引，而不是工具本身。請把 vue-options-api-best-practices install 理解為替 agent 啟用知識，而不是取代 linter。

它能幫忙解決 TypeScript strict mode 的痛點嗎

可以，這其實正是使用這個技能的一大理由。它會引導你處理 defineComponent、更嚴格的 this 使用方式、以 PropType 描述複雜 props、事件處理器型別、computed 回傳型別註記，以及 Options API 中 inject 的型別限制，這些都是 strict mode 下團隊常卡住的地方。

如何提升 vue-options-api-best-practices 的使用效果

提供完整元件脈絡給模型

想讓 vue-options-api-best-practices 輸出更準，最快的方法就是直接貼出整個元件，而不是只貼零碎幾行。這個技能很多檢查點都仰賴 data、methods、props、hooks 與實例重用之間的互動關係。

明確說出不可協商的限制

如果你一定要留在 Options API，請直接講清楚：
「Do not convert to Composition API.」
這一句就能避免在混合 Vue 環境中最常見的答非所問。

補上會影響建議的版本資訊

有些建議會受版本影響，尤其是 TypeScript。若你使用的是 4.7 以前版本，validator/default 的 arrow-function workaround 可能就仍然適用。若你省略版本，模型可能會給出只適用現代版本、雖然技術上沒錯但你實際無法採用的建議。

先要求找出問題，再要求改寫

更好的輸出通常來自兩階段指示：

1. 先找出所有違反 Options API best practices 的地方
2. 再產出修正後的程式碼

這樣可以降低只修一半的情況，也能幫你確認模型是否真的抓到 vue-options-api-best-practices 中那些關鍵陷阱。

明確指出共享實例風險

如果你的元件會出現在列表中，或會被大量實例化，請把這點寫出來。這能提高技能發現「把 debounce 或 throttle 定義在 methods，導致跨實例共用狀態」這類問題的機率，並提醒應改為在 created() 中為每個實例建立獨立函式。

要求說明必須對應到具體修改

高品質提示可以這樣寫：
「Fix the code and explain each change in one sentence.」
這能讓回覆更容易稽核，也更方便你把相同模式套用到其他前端程式碼中。

需要特別留意的常見失誤

即使用了 vue-options-api-best-practices，仍建議檢查輸出是否出現以下問題：

• 不小心被改寫成 Composition API
• methods 或生命週期 hooks 中仍殘留 arrow function
• debounced 函式只建立一次，導致被多個實例共用
• unmounted() 中缺少清理邏輯
• 明明需要 PropType，卻仍使用模糊的 props 型別
• 對 Options API 中已型別化的 inject 過度樂觀

這些地方比起風格一致，更關係到正確性。

透過提示範本提升重用性

對團隊而言，建議建立標準化的 vue-options-api-best-practices guide 提示範本，對應常見任務，例如：

• code review
• bug fix
• TS strict-mode cleanup
• migration-safe refactor

這能讓輸出更一致，也能減少重複做 prompt engineering。

第一輪答案後繼續迭代

如果第一版結果已經接近，但仍不完整，可以接著補一個聚焦修正：

「Re-check for any remaining Options API this binding issues and TS typing gaps. Keep the previous structure.」

這種短而明確的迭代提示，往往比一開始就要求一份龐大且完美的答案更有效。

把它當成審查標準，而不只是救火工具

vue-options-api-best-practices for Frontend Development 最好的長期用法，是拿來預防，而不只是出 bug 才求救。把它納入新元件的審查流程，而不是等問題發生後才用。當它成為可重複套用的檢查模式時，對維護舊式但仍需穩定交付的 Vue 開發流程，價值會持續放大。