vue-spec

name	vue-spec
user-invocable	true
argument-hint	<generate|update|validate|setup> <file or directory path>
metadata	{"author":"Ray","date":"2026-04-23"}
description	This skill should be used when the user asks to "add spec to component", "generate spec block", "generate spec", "update spec", "validate spec", "set up spec environment", "write component specification", "add specification", "check spec", or mentions <spec lang="md"> custom blocks in Vue SFC files. Covers spec generation, updates, batch processing, validation, and project setup (Vite plugin + ESLint) when explicitly requested.

Vue Spec Block — SFC 規格驅動開發

在 Vue SFC 中管理 <spec lang="md"> 自訂區塊，包含專案環境設定、規格生成、更新與驗證。

---

核心流程

每次執行依照以下四步驟進行。

步驟一：判斷操作類型

根據使用者請求決定操作：

• 生成：確認目標檔案尚無 <spec>，才進行生成
• 更新：讀取現有 <spec> 並根據程式碼變更更新
• 批次：用 Glob 找出指定目錄下所有 .vue 檔，逐一處理
• 驗證：比對 <spec> 與實際程式碼，回報不一致處

未指定目標檔案時，向使用者確認要處理的檔案 or 目錄。

步驟二：元件分析

讀取目標 .vue 檔案的完整內容，擷取以下資訊。

判斷元件類型：

• 頁面元件：位於 pages/ or views/，or 有使用 useRoute()
• 邏輯元件：有 props、emits、顯著的 <script setup> 邏輯
• 純展示元件：以 <template> 為主，少量 or 無 props

Composition API 擷取對照：

分析目標	對應 Spec 區塊
defineProps() / withDefaults()	Props
defineEmits()	Emits
defineSlots() / <slot> 標籤	Slots
defineExpose()	Expose
defineModel()	Props（備註 v-model）+ Emits（update:modelValue）
useRoute() 取得的參數	路由參數
ref() / shallowRef()	狀態管理 → Refs
computed()	狀態管理 → Computed
reactive()	狀態管理 → Reactive
函式宣告	功能行為
onMounted / watch / watchEffect	功能行為（生命週期與副作用）
import 子元件	依賴元件
import composable	依賴 Composables
import 第三方套件	依賴套件
<style> 區塊	UI 規格

Options API 元件：data() → Refs、methods → 功能行為、computed → Computed、props → Props、emits → Emits、watch → 功能行為。

步驟三：生成 Spec

1. 依照 references/template.md 的模板格式產生內容
2. 依照模板中的「條件規則」決定包含哪些區塊
3. 將 <spec lang="md"> 區塊插入 .vue 檔案的最上方（<script> 之前）
4. 更新操作時，保留使用者手動添加的額外說明 or 備註

步驟四：驗證檢查

生成 or 更新完成後確認：

1. Props 列表與 defineProps 完全一致（名稱、類型、預設值、必填）
2. Emits 列表與 defineEmits 完全一致
3. 所有 ref / computed / reactive 都有列出
4. defineExpose 的項目都列在 Expose 區塊
5. 依賴的元件、composable、套件完整且路徑正確
6. 功能行為涵蓋所有主要函式（含觸發條件和邊界處理）
7. 表格分隔線格式正確（| ------ | 有空格）

---

更新規則

更新已存在的 <spec> 時：

1. 讀取 .vue 檔案，分離現有 <spec> 內容
2. 重新分析元件程式碼（同步驟二）
3. 逐區塊比對差異——新增、移除、更名的項目分別處理
4. 保留使用者手動添加的備註 or 自訂區塊
5. 完成後向使用者報告具體變動內容

---

批次操作

1. 用 Glob 找出目標目錄下所有 .vue 檔案
2. 用 Grep 檢查每個檔案是否已有 <spec 標籤
3. 生成模式跳過已有 <spec> 的檔案；更新模式只處理已有 <spec> 的檔案
4. 逐一完整執行步驟二～四
5. 完成後報告摘要：總檔案數、新增數、更新數、跳過數

---

環境設定

僅在使用者主動要求設定環境時執行（例如「set up spec environment」、「設定 spec 環境」）。

依照 references/setup.md 執行首次專案設定，包含 Vite 外掛、測試環境、ESLint 規則。

---

重要規則

• 只對 .vue 檔案操作，不對 .ts / .js / 測試檔案 / node_modules 操作
• 不修改元件的程式碼邏輯——Spec 只是規格文件
• <spec> 區塊預設放在檔案最上方，與 ESLint vue/block-order 規則一致
• <spec> 會被 Vite 外掛轉成空模組，不影響編譯產出和效能
• 表格分隔線一律用 | ------ | 格式
• 描述要具體：「從 API 取得使用者列表並過濾已停用帳號」而非「處理資料」
• 測試行為的斷言包含具體數值：「應有 7 個 <li>」

---

參考資源

Reference Files

• references/template.md — 完整的 Spec 模板格式、條件規則、defineModel 處理方式。生成 or 更新 Spec 時參考。
• references/setup.md — 首次專案設定流程：偵測 Vite/Nuxt、加入外掛、測試環境設定、ESLint 設定。