重新認識 Vue.js | Kuro Hsu

Appearance

AI 輔助開發與 vue-skills ​

重新認識 Vue.js: 008 天絕對看不完的 Vue.js 3.x 指南

把 AI 當成一位熟稔 Vue、但剛加入專案的助手：它可以產生樣板、檢查寫法，或在遭遇瓶頸時協助找方向；但若沒有先說明團隊慣例，它只能從許多「都能運作」的方案中猜一個。

Vue 的彈性讓這個問題特別明顯。同一個需求可能使用 Options API 或 Composition API、一般 <script> 或 <script setup>，共享狀態也可能選擇 Pinia、composable 或 provide / inject。這些選擇不一定有絕對的對錯，混在同一個專案裡卻會讓程式難以維護。

本節將介紹給 AI agent 使用的 vue-skills，看看 skill 如何提供較一致的 Vue 慣例，以及人類開發者仍然需要負責哪些判斷。

Agent skill 是什麼？ ​

Agent skill 不是重新訓練 AI，也不是替模型安裝一份永遠正確的記憶。它比較像交給新進成員的專案手冊：告訴 agent 什麼情況要採用哪些流程、慣例與檢查方式。

依照 Agent Skills 規格，一個 skill 至少是一個包含 SKILL.md 的資料夾，也可以附帶其他資源：

text
skill-name/
├── SKILL.md        # 名稱、觸發描述與主要指示
├── references/     # 需要時才讀取的技術參考
├── scripts/        # 可重複執行的工具
└── assets/         # 樣板或其他靜態資源

多數支援 skill 的 agent 會採取漸進式載入：

階段Agent 取得的內容用途
啟動時skill 的名稱與描述判斷目前任務是否相關
skill 被觸發時完整的 SKILL.md依照工作流程與慣例執行
任務需要時references/、scripts/、assets/只載入這次真正需要的細節

因此，skill 的價值不只是「多給 AI 一段提示詞」，而是把可重複使用的知識、流程與工具整理成有明確觸發條件的工作單位。

vue-skills 是什麼？ ​

vuejs-ai/skills 是給 AI agent 使用的 Vue 3 社群技能包。它把常見問題、實務慣例與檢查方式拆成不同的 skill，讓 agent 能依任務載入適合的規則，例如：

  • vue-best-practices（Composition API、TypeScript、SSR 與效能等通則）
  • vue-options-api-best-practices（專案明確使用 Options API 時）
  • vue-router-best-practices（路由）
  • vue-pinia-best-practices（狀態管理）
  • vue-testing-best-practices（測試）
  • vue-debug-guides（錯誤、警告與 hydration 問題）
  • create-adaptable-composable（可接受 ref、getter 或一般值的組合式函式）

Vue 允許多種有效寫法；skill 的作用，是先替 agent 設定專案希望採用的預設方向。例如專案已經統一使用 Composition API 與 <script setup>，agent 就不必每次重新猜測要使用哪一套 API。

vue-skills 不是 Vue 官方規範

vuejs-ai/skills 的 README 將專案定位為早期實驗性的社群專案，也提醒內容可能不完整。Skill 可以降低寫法不一致的機率，但不能保證產出正確，更不能取代 Vue 官方文件、專案規範與實際測試。

Skill 能減少猜測，但不能代替需求說明 ​

如果只對 AI 說「做一個待辦清單」，它仍然不知道專案使用 JavaScript 還是 TypeScript、元件應該如何拆分、資料要存在哪裡，以及完成後要執行哪些測試。

Skill 能提供框架層級的預設慣例，讓 agent 不必反覆猜測技術選擇；但具體需求仍要由提示詞與專案內容補齊：

資訊來源應該回答的問題
Vue skillVue API、元件結構與常見陷阱
專案規範目錄、命名、套件選擇與驗證指令
這次的提示詞要做什麼、不可改什麼、完成條件是什麼

把 skill 裝好，不代表可以把需求縮成一句模糊指令。越明確的任務邊界與驗收條件，越容易得到能安全合併的結果。

安裝與觸發 ​

小提醒：以 vue-skills repo 為準

vue-skills 是持續演進的社群專案，安裝方式與技能名稱可能隨版本調整。以下為撰寫當下的用法，實際請以 vue-skills repo 的 README 為準。

依目前 repo 說明，支援 Agent Skills 的工具可以透過 skills CLI 安裝：

sh
npx skills add vuejs-ai/skills

Claude Code 也可以透過 Marketplace 安裝整包或個別 skill：

text
# 加入 Marketplace
/plugin marketplace add vuejs-ai/skills

# 安裝整包
/plugin install vue-skills-bundle@vue-skills

# 只安裝需要的 skill
/plugin install vue-best-practices@vue-skills

不同 agent 支援的安裝位置與觸發方式不一定相同。不要直接假設某個工具的路徑適用於所有工具，也不必為了「可能有用」一次載入所有 skill；選擇與目前技術堆疊和任務相關的項目即可。

裝好之後，agent 可能依 skill 的描述自動判斷是否需要載入；為了降低漏掉的機率，vuejs-ai/skills 建議在提示詞明確寫出 use vue skill。例如：

use vue skill

請先閱讀現有元件與專案規範，再建立待辦清單：
- 使用專案既有的 Composition API 與 <script setup>
- 保留目前的資料存取方式，不新增狀態管理套件
- 補上新增、切換完成狀態的測試
- 完成後執行型別檢查與測試，並說明變更檔案

這段提示詞同時給了 agent 四種資訊：要使用的 skill、修改前要閱讀的內容、架構限制，以及可驗證的完成條件。Skill 負責補充 Vue 慣例，不會取代這些要求。

一個可靠的 AI 協作迴圈 ​

要求 AI 一次吐出大量程式碼並不穩定；比較可靠的做法是讓它走完一個能被檢查的迴圈：

  1. 先讀專案：確認 package.json、現有元件、型別與專案規範，不要只靠模型記憶猜版本。
  2. 選擇最小的 skill 集合：一般元件使用 Vue 通則；碰到 Router、Pinia 或測試時，再加入對應 skill。
  3. 寫清楚限制與驗收條件：指出哪些檔案在範圍內、哪些行為不能改，以及要通過哪些指令。
  4. 小步實作：先完成一個可驗證的改動，再處理下一個部分，避免一次產生難以審查的大量變更。
  5. 執行工具驗證：至少包含專案既有的格式檢查、型別檢查、測試與建置。
  6. 人工閱讀 diff：確認資料流、錯誤處理、清理行為、可讀性與實際需求，而不只看測試是否變綠。

Skill 也要接受專案規範約束

如果 skill 建議的寫法與既有架構不同，應先判斷差異，而不是直接大規模改寫。使用者的明確需求與專案規範，優先於通用 skill 的偏好。

反覆糾正的規則，可以整理成專案 skill ​

公開的 Vue skill 解決框架共通問題；但每個團隊還會有自己的 API 錯誤格式、目錄結構、元件命名或測試要求。如果同一件事需要反覆提醒 agent，可以考慮把它整理成專案層級的 skill，並跟著程式碼一起進行版本控制與審查。

下面是一個最小概念範例；實際存放位置請依使用的 agent 而定：

md
---
name: project-vue-conventions
description: 本專案的 Vue 元件、資料存取與驗證慣例。修改 Vue 檔案時使用。
---

# 專案 Vue 慣例

- 修改前先閱讀相鄰元件，不引入第二套寫法
- API 呼叫統一放在既有的 composable 層
- 不可忽略 loading、error 與空資料狀態
- 完成前執行 `pnpm typecheck` 與 `pnpm test`

專案 skill 應該保持單一關注點，內容改動也要像程式碼一樣接受 review。當 Vue、Nuxt 或其他相依套件升級時，也要一起檢查 skill 是否仍符合目前版本。

AI 只是輔助，人要比車兇！ ​

AI 就跟櫻木花道的左手一樣只是輔助，真正做主、負責的還是我們自己。vue-skills 再方便，也只是輔助工作流，並非本書的規範來源。

  • 本書所有範例與說明皆以 Vue 官方文件、實際安裝版本與本書範例準則為準；vue-skills 則作為「生成、檢查與程式碼審查（Code Review）」的輔助工具。
  • AI 產出採用前仍需人工閱讀與驗證，因為它可能提供看似正確、實則過時或含有錯誤的程式碼。
  • 特別是版本相關的細節（例如 Vue 3.5 的新語法），AI 的訓練資料與 skill 都可能跟不上，更要對照官方文件與專案 lockfile 確認。

審查 AI 產出時，至少問自己這幾個問題：

  • 使用的 API 是否符合專案實際版本？
  • 寫法是否與相鄰程式碼一致，還是平白引入另一套架構？
  • props、事件與共享狀態的資料流是否清楚？
  • 事件監聽、計時器或非同步請求是否正確清理？
  • 測試是在驗證需求，還是只驗證 AI 自己寫出的實作？
  • diff 是否只包含這次任務需要的範圍？

後續實作會穿插底下這種「AI 協作」小節，示範怎麼搭配對應技能，並標明該自己檢查的重點：

AI 協作：用 vue skill 加速

情境：要建立一個購物車的 Pinia store。 做法：明確要求使用 vue-pinia-best-practices，並提供現有 store、資料形狀與驗收條件。 AI 產出：store 的骨架，含 state、getters 與 actions。 工具驗證：執行型別檢查與 store 測試。 人工驗證重點：state 是否正確、getters 是否為純函式，以及有沒有符合本書的命名與結構慣例。

到這裡，我們已經把現代 Vue 的開發環境（Vite 專案、DevTools、編輯器、AI 輔助）都準備好了。從下一章開始，我們就要正式進入 Vue 的核心，先從最基本的心智模型談起。

Copyright © 2020-present Kuro Hsu