告別 AI 亂碼！Vue3+TS 專案的 AI 編碼助手規範實踐

大家好，作為前端開發者，我們都在享受 AI 編碼助手（如 Cursor、OpenCode）帶來的效率提升。但你是否也遇到過：AI 生成的程式碼風格混亂、命名不一致、TypeScript 型別缺失，甚至引入專案中從未用過的依賴？這些問題不僅沒有提升效率，反而增加了大量的 Code Review 成本。

今天，我就分享一套經過實戰打磨的Vue 3 + TypeScript 專案 AI 編碼助手規則集，它能幫你從源頭約束 AI 行為，讓 AI 生成的程式碼從第一行就符合團隊規範，真正做到「拿來就能用」。

一、為什麼需要給 AI 制定「員工手冊」？

AI 編碼助手就像一個新入職的實習生：它能力很強，但完全不了解你的專案約定。如果不給它明確的規則，它就會按照自己的「通用常識」寫程式碼，結果往往是：

• 風格不一致：一下子 PascalCase，一下子 camelCase
• 依賴滿天飛：不管專案用的 UI 函式庫，強行引入新元件
• 型別 any 泛濫：把 TypeScript 寫成了 AnyScript
• 架構混亂：無視專案目錄結構，到處建立檔案

解決這些問題的根本方法，就是給 AI 制定一套清晰、可執行的「行為準則」，讓它在你的專案裡也能像老員工一樣「守規矩」。

二、我的 Vue 專案 AI 規則集全景

我將規則分為 4 個核心檔案，涵蓋了從通用行為到具體編碼細節的所有場景：

1. .agents/rules/common.md：通用編碼規範（Vue3+TS 基礎約定）
2. .agents/rules/vue.md：Vue 3 元件專屬規範
3. .agents/rules/css.md：樣式撰寫規範（BEM 命名等）
4. .agents/rules/agent.md：AI 助手通用行為準則

下面我為你逐一拆解每個檔案的核心內容與設計思路。

📄 1. 通用編碼規範 (common.md)

這是整個規則集的基礎，定義了所有程式碼都必須遵守的「憲法級」約定。

核心規則概覽

表格

模組關鍵約定基礎規範路徑別名遵循tsconfig設定；單一檔案不超過 400 行；註解清晰命名規範元件名PascalCase；函式camelCase；常數UPPER_SNAKE_CASETypeScript優先interface；禁止濫用any；props預設值用withDefaults匯入與排序按「型別匯入 → 第三方函式庫 → Vue 官方函式庫 → 專案內部」分組目錄組織遵循components/views/composables/stores約定最佳實踐元件優先重用 UI 函式庫；響應式優先用ref/computed；重複邏輯下沉#### 關鍵設計亮點

• 強約束的命名規則：AI 對命名的理解往往很模糊，這裡直接規定死：

  • 元件名必須是PascalCase（如UserCard.vue）
  • 事件處理函式必須帶handle前綴（如handleSubmit）
  • 組合式函式必須帶use前綴（如useUserList）
• TypeScript 安全鎖：明確禁止濫用any，並強制使用withDefaults定義props預設值，從源頭杜絕型別安全問題。
• 防重複造輪子：要求 AI 優先重用專案內既有元件、工具函式，避免引入新依賴。

📄 2. Vue 3 元件專屬規範 (vue.md)

這是針對 Vue 單檔元件（SFC）的「專項約束」，解決 AI 生成 Vue 程式碼時最容易出錯的問題。

核心規則概覽

• 強制 Composition API：新元件必須使用<script setup lang="ts">，禁止 Options API
• 固定程式碼區塊順序：template → script setup → style

• Script 內部順序約定：

  1. 型別匯入 import type
  2. 第三方函式庫 / UI 元件
  3. Vue API（ref/reactive/computed等）
  4. 專案內模組匯入
  5. defineProps/defineEmits等編譯器巨集
  6. 響應式資料、方法、生命週期鉤子

• 關鍵 API 使用規範：

  • defineEmits必須使用基於型別的函式呼叫簽章，禁止陣列 / tuple 形式
  • 取得元件實例優先使用useTemplateRef（Vue3.3+）
  • defineExpose僅暴露父元件必須呼叫的方法 / 屬性

關鍵設計亮點

• SFC 結構標準化：很多 AI 生成的 Vue 檔案結構混亂，這裡直接規定了程式碼區塊和內部邏輯的順序，保證所有元件結構一致。
• 響應式規則：明確約定「原始值用ref，物件用reactive，衍生狀態用computed」，避免 AI 寫出低效的響應式程式碼。
• 禁止項明確：列出了 AI 最容易犯的錯誤，如重複匯入已自動註冊的元件、用JSON.parse(JSON.stringify())做深拷貝等。

📄 3. 樣式撰寫規範 (css.md)

AI 寫 CSS 時最容易放飛自我，比如隨便命名 class、濫用!important、寫出巢狀過深的選擇器。這個檔案就是用來「馴服」AI 的樣式程式碼。

核心規則概覽

• BEM 命名強制約定：

  • Block：user-card（雙連字號連接，禁止駝峰）
  • Element：user-card__avatar（雙底線連接）
  • Modifier：user-card--compact（雙連字號表示狀態）
• SFC 樣式區塊規範：預設使用scoped，必須覆蓋第三方樣式時需註解說明
• 撰寫原則：優先使用專案 CSS 變數；避免魔法數字；禁止濫用!important

• 禁止項：

  • class 使用camelCase命名
  • BEM 元素鏈式巢狀（如block_a__b）
  • 在scoped樣式中依賴深度選擇器穿透多層級

關鍵設計亮點

• BEM 命名可執行化：不僅介紹 BEM，還直接給出了scoped中結合 SCSS 巢狀的寫法示例，讓 AI 知道怎麼寫才對。
• 防汙染控制：強制使用scoped，並對穿透樣式做嚴格限制，避免全域樣式汙染。
• 反模式清單：明確列出了 AI 寫 CSS 的常見錯誤，讓它從一開始就避開這些坑。

📄 4. AI 助手行為準則 (agent.md)

這是給 AI 助手本身制定的「元規則」，控制它的行為邊界，防止它越權操作。

核心規則概覽

• 通用要求：始終使用繁體中文溝通；未經允許不建立文件、不執行 Git 操作
• 應當做的：改程式碼前閱讀專案約定；優先重用既有抽象；修改後執行 lint/typecheck
• 不應當做的：擅自新增說明文件；為已自動匯入的 API 寫冗餘 import；猜測不存在的 API 路徑

關鍵設計亮點

• 邊界控制：明確禁止 AI 執行 Git 操作、修改設定檔等危險行為，保證開發者對專案的絕對控制權。
• 效率優先：禁止 AI 做「多餘的事」，比如在沒有要求的情況下新增測試、註解或文件，避免干擾開發者的節奏。

三、如何在專案中落地這套規則？

步驟 1：建立規則檔案目錄

在專案根目錄建立.agents/rules/資料夾，將上面 4 個檔案放入其中。

plaintext

erlang 體驗AI程式碼助手 程式碼解讀複製程式碼.
├── .agents/
│   └── rules/
│       ├── common.md
│       ├── vue.md
│       ├── css.md
│       └── agent.md

步驟 2：設定 Cursor Rules

在專案根目錄建立.cursorrules檔案，將所有規則檔串聯起來：

markdown

yaml 體驗AI程式碼助手 程式碼解讀複製程式碼---
applyTo: "**"
---

# 專案編碼規範

以下規則適用於本專案所有程式碼，請嚴格遵守：

## 通用編碼規範
@./.agents/rules/common.md

## Vue 3 元件規範
@./.agents/rules/vue.md

## CSS 樣式規範
@./.agents/rules/css.md

## AI 助手行為準則
@./.agents/rules/agent.md

步驟 3：讓 AI「看見」規則

• 在 Cursor 中，AI 會自動讀取.cursorrules檔案
• 在其他工具中，可以在每次對話時手動引用這些檔案，或設定專案級別的全域指令

四、效果實測：AI 寫程式碼的變化

在應用這套規則前後，AI 生成的程式碼品質有了質的變化：

表格

場景規則前規則後元件命名userCard.vue（駝峰）UserCard.vue（PascalCase）Props 定義const props = defineProps({ id: Number })``const props = withDefaults(defineProps<{ id?: number }>(), { id: 0 })Class 命名.headerTitle/.btn-primary``.user-card__title/.user-card__btn--primaryAPI 呼叫直接在元件中寫 fetch呼叫專案已封裝的useApi組合式函式---

五、總結與擴充

給 AI 制定編碼規範，不是為了限制它的能力，而是為了讓它的能力更好地服務於你的專案。這套規則集的核心價值在於：

1. 統一團隊程式碼風格：無論誰用 AI 寫程式碼，輸出的結果都能保持一致
2. 降低 Code Review 成本：AI 生成的程式碼天然符合規範，減少不必要的風格爭論
3. 提升專案可維護性：TypeScript 型別更安全、架構更清晰、樣式更可控
4. 解放開發者精力：你不用再花時間修正 AI 的低級錯誤，可以專注於業務邏輯

💡 後續優化建議

• 按需擴充：根據你的專案特性，新增更多專案特定規則，比如狀態管理（Pinia）、路由、權限等
• 定期更新：隨著專案迭代，不斷完善規則集，將團隊的最佳實踐沉澱進去
• 團隊共享：將這套規則同步給團隊所有人，讓 AI 成為統一的「程式碼風格監督員」

如果你需要，我可以把這 4 個規則檔案的完整 Markdown 內容整理出來，方便你直接複製使用。

覺得有用的話，歡迎按讚收藏，也歡迎在留言區分享你的 AI 編碼規範實踐！

附：規則檔案完整模板（可直接複製）

.agents/rules/common.md

markdown

markdown 體驗AI程式碼助手 程式碼解讀複製程式碼# 編碼規範 (Vue 3 + TypeScript)

適用於 Vue 3 + TypeScript 前端專案的通用編碼約定。Vue SFC 細節見 `vue.md`，樣式見 `css.md`。

## 基礎規範
- 路徑別名、目錄結構遵循**專案既有設定**（如 `tsconfig`、`vite.config`）；避免 `../../../../` 式相對路徑穿越。
- `.vue` 檔案與模板中的元件使用 **PascalCase**（`UserCard.vue` / `<UserCard />`）。
- 樣式 class 建議使用 **kebab-case**；元件內自訂 class 建議使用 BEM（見 `css.md`）。
- 單一檔案建議不超過 400 行，超出應拆分元件或模組。
- 註解語言、識別符語言遵循專案約定；程式碼識別符使用英文，含義清晰。

## 命名規範
- **元件名**: PascalCase。
- **變數 / 函式**: camelCase；事件處理函式建議 `handle` 前綴（如 `handleSubmit`）。
- **常數**: 需要時使用 UPPER_SNAKE_CASE。
- **Props / Emits**: props 用 camelCase；模板事件名與 emits 定義用 kebab-case。
- **Composables**: 建議 `use` 前綴（如 `useUserList`）。
- **全域元件前綴**（如有）: 遵循專案統一前綴，不要自創多套命名。

## TypeScript 規範
- `import type` 與值匯入分離。
- 物件結構優先 `interface`；聯集型別、工具型別用 `type`。
- 元件 props 預設值使用 `withDefaults(defineProps<Type>(), { ... })`。
- 避免 `any`；確實需要時使用顯式型別或窄化。
- Composables、工具函式適當使用泛型提升型別安全。
- 公共型別集中管理；領域型別靠近業務模組，按專案目錄約定放置。

## Vue 相關（摘要）
以下細則見 `vue.md`，此處不重複：
- Composition API + `<script setup>`
- `defineOptions` / `defineProps` / `defineEmits` / `defineExpose`
- 模板 ref、`v-model`、事件與插槽命名

## 匯入與排序
建議分組（同組內按字母序）：
1.  型別匯入
2.  第三方函式庫
3.  Vue / 官方函式庫
4.  專案內部（composables、元件、utils、樣式、資源）

- 不要重複 import 已由自動匯入註冊的符號（型別除外）。
- 靜態資源、樣式按專案約定引入，避免大段內聯樣式。

## 目錄與組織
- 遵循專案現有目錄劃分（如 `components`、`views`、`composables`、`stores` 等）。
- 可重用 UI 放元件目錄；頁面級邏輯解放 views 或路由對應模組。
- 跨頁面邏輯抽到 composables；純函式抽到 utils。
- 常數、列舉集中管理，避免魔法字串散落。

## 程式碼品質與 Lint
- 遵循專案 **ESLint**、**Stylelint**、**tsconfig** 設定，不擅自關閉規則。
- 必要的 `eslint-disable` / `@ts-expect-error` 須註解說明原因。
- Vue 相關 lint（block 順序、巨集順序、事件命名等）以專案 ESLint 設定為準。

## 最佳實踐
- **元件封裝**: 優先重用專案 UI 函式庫與既有封裝；透傳 props / attrs 時保持 API 一致。
- **型別安全**: 介面、props、emits、composables 回傳值均提供型別。
- **響應式**: 原始值用 `ref`，物件用 `reactive`，衍生用 `computed`（詳見 `vue.md`）。
- **效能**: 模板避免複雜計算；大列表考慮分頁、虛擬捲動或拆分；按需載入路由與元件。
- **程式碼重用**: 重複邏輯下沉 composable 或 utils，不要複製貼上。

## 提交流程與檢查
- 套件管理器與鎖定檔以倉庫為準；變更依賴時同步更新 lockfile。
- 提交前按專案腳本執行檢查（如 `lint`、`typecheck`、`test`、`build`）。
- 新檔案預設帶型別，避免無型別的 `any` 擴散。

.agents/rules/vue.md

markdown

markdown 體驗AI程式碼助手 程式碼解讀複製程式碼# Vue 規範 (Vue 3)

適用於 Vue 3 + Composition API + `<script setup>` 的元件開發約定。

## 基礎要求
- 新元件一律使用 **Composition API** + `<script setup lang="ts">`，禁止 Options API。
- 需要元件名時（除錯、keep-alive、路由快取等）使用 `defineOptions({ name: 'ComponentName' })`。
- 路由級頁面元件的 `name` 建議與路由配置保持一致。

## 组件塊順序
- `<template>` → `<script setup lang="ts">` → `<style>`（樣式見 `.agents/rules/css.md`）
- 遵循專案 ESLint/Vue block-order 規則。

## Script 內建議順序
1.  型別匯入 `import type ...`
2.  第三方函式庫 / UI 元件
3.  Vue API（`ref`、`reactive`、`computed`、`watch` 等）
4.  專案內模組（composables、utils、components 等）
5.  `defineOptions`（如有）
6.  `defineModel`（如有）
7.  `defineProps` + `withDefaults`
8.  `defineEmits`（事件名 kebab-case）
9.  `defineSlots`（如有）
10. 常數 / 工具函式 / composables 解構
11. 響應式資料 `ref` / `reactive`
12. `computed` 衍生資料
13. 方法（建議 `handle` 前綴，如 `handleSubmit`）
14. 生命週期 / 副作用（`onMounted`、`watch` 等）
15. `defineExpose` 放最後（如需要）

## 自動匯入
若專案配置了 `unplugin-auto-import`、`unplugin-vue-components` 等，**遵循專案既有約定**:
- 已自動註冊的 API / 元件不要重複手寫 import。
- 僅需**型別**時使用 `import type`。
- 不確定是否自動匯入時，以專案 `vite.config` 與現有程式碼為準。

## 模板約定
- 模板保持單根節點（或遵循 Vue 3.3+ 多根節點的專案約定）。
- 事件名、插槽名使用 **kebab-case**。
- 受控表單優先 `v-model`；修飾符與命名參數按 Vue 3 語法撰寫。
- 布林 prop / 雙向綁定使用顯式寫法（如 `:visible="visible"`、`v-model:visible="visible"`）。
- 複雜列表/表格渲染可使用 `lang="tsx"` 或 render 函式，按專案既有模式選用。

## 元件註冊與引用
- 全域 / 區域元件在模板中使用 **PascalCase**（如 `<UserCard />`）。
- 不要手動 import 已由自動匯入註冊的元件（型別匯入除外）。
- 子元件透過 props / emits 通訊，避免隨意存取父元件實例。

## defineEmits
- 使用**基於型別的函式呼叫簽章**，禁止陣列 / tuple 形式。
- 無參事件: `(e: 'event-name'): void`；有參事件將參數寫在 `e` 之後。

```typescript
// ✅
const emit = defineEmits<{
  (e: 'submit'): void
  (e: 'change', value: string): void
}>()

// ❌
const emit = defineEmits({ submit: [] })()
const emit = defineEmits<{ change: [value: string] }>()

模板 Ref

• 取得子元件實例或 DOM 元素時，優先使用 useTemplateRef（Vue 3.5+）；低版本可用 ref + 同名模板 ref，與專案約定保持一致。
• 模板上的 ref 屬性值與 useTemplateRef('...') 參數字串一致。

vue

xml 體驗AI程式碼助手 程式碼解讀複製程式碼<script setup lang="ts">
import type { FormInstance } from './types'
const formRef = useTemplateRef<FormInstance>('formRef')

function submit() {
  formRef.value?.validate()
}
</script>

<template>
  <form ref="formRef" @submit.prevent="submit">
    <!-- ... -->
  </form>
</template>

defineExpose

• 僅暴露父元件確實需要呼叫的方法或屬性。
• 彈窗、表單等封裝元件常用 defineExpose({ open, close, reset }) 模式。

響應式

• 原始值用 ref，物件用 reactive；衍生狀態用 computed。
• 避免不必要的大物件 reactive；從 composable 回傳時保持結構清晰。
• 解構 reactive 物件時注意響應式遺失，必要時用 toRefs。

禁止事項

• 使用 Options API 編寫新元件
• 重複 import 已自動註冊的 API / 元件（型別除外）
• 用無關的 ref() 命名綁定模板 ref 導致語義混亂（優先 useTemplateRef）
• defineEmits 使用陣列 / tuple 形式
• 在模板中寫複雜業務邏輯，應抽到 computed 或方法
• 使用 JSON.parse(JSON.stringify()) 做深拷貝（優先 structuredClone 或專案提供的工具）

樣式相關約定見 .agents/rules/css.md。

plaintext

javascript 體驗AI程式碼助手 程式碼解讀複製程式碼
#### `.agents/rules/css.md`
```markdown
# CSS 規範 (Vue 3)

適用於 Vue 3 單檔元件（SFC）的樣式撰寫約定。

## SFC 樣式塊
- 樣式塊位於 `<script>` 之後：`<style lang="scss|less|css" scoped>`。
- 遵循專案的 ESLint/Vue block-order 規則（通常為 template → script → style）。
- 預設使用 **`scoped`**，避免汙染全域；需要全域樣式時須在註解中說明原因。
- 預處理器（SCSS/LESS）與純 CSS 按專案既有約定選用，同一元件內保持一致。

## 命名約定
- 自訂 class 使用 **kebab-case**。
- 元件內自訂 class 建議使用 **BEM**（Block Element Modifier）。
- 第三方 UI 函式庫自帶類名、專案全域工具類不在 BEM 約束範圍內；僅約束本元件新增的 class。

## BEM 結構
| 類型 | 格式 | 範例 |
| :--- | :--- | :--- |
| Block（區塊） | `block` | `user-card`、`search-form` |
| Element（元素） | `block__element` | `user-card__avatar`、`search-form__input` |
| Modifier（修飾符） | `block--modifier` 或 `block__element--modifier` | `user-card--compact`、`search-form__btn--disabled` |

約定：
- **Block** 對應目前元件語義，一個 SFC 通常只設一個 Block。
- **Element** 用雙底線 `__` 連接 Block；多級語義用 `-` 連接，**禁止** `block__a__b` 鏈式元素寫法。
- **Modifier** 用雙連字號 `--` 表示狀態或變體（如 `--active`、`--disabled`、`--compact`）。
- 在 `<style scoped>` 中優先用預處理器巢狀表達 BEM（`&__element`、`&--modifier`）。

```vue
<template>
  <div class="user-card">
    <img class="user-card__avatar" :src="avatar" alt="">
    <div class="user-card__body">
      <h3 class="user-card__name">{{ name }}</h3>
      <span class="user-card__badge user-card__badge--vip">VIP</span>
    </div>
  </div>
</template>

<style lang="scss" scoped>
.user-card {
  display: flex;
  gap: 12px;

  &__avatar {
    width: 48px;
    height: 48px;
    border-radius: 50%;
  }

  &__name {
    margin: 0;
    font-size: 16px;
  }

  &__badge {
    font-size: 12px;

    &--vip {
      color: var(--color-warning, #faad14);
    }
  }
}
</style>

撰寫原則

• 顏色、間距、字級優先重用專案 CSS 變數或設計代幣，避免魔法數字。
• 動畫與過渡可重用的，抽到公共樣式；元件內只寫與佈局 / 狀態相關的差異。
• 避免內聯 style；動態樣式（如寬高、座標）等場景除外。
• 盡量避免 !important；確需覆蓋第三方樣式時註明原因。

Stylelint

• 遵循專案已配置的 Stylelint 規則（如 standard、scss、recommended-vue、recess-order 等）。
• 屬性順序以 Stylelint 輸出為準；class 命名建議 BEM/kebab-case。
• 樣式改動後按專案腳本執行 lint（如 lint:style）。

禁止事項

• ❌ 自訂 class 使用 camelCase 或非語義命名（如 .headerTitle、.activeBtn）
• ❌ BEM 元素鏈式巢狀（如 block__a__b，應扁平為 block__a-b）
• ❌ 濫用 !important 覆蓋樣式
• ❌ 在元件內寫大段內聯 style（特殊動態樣式除外）
• ❌ 在 scoped 樣式中依賴未宣告的深度選擇器穿透（:deep() 等）堆疊過多層級

plaintext

diff 體驗AI程式碼助手 程式碼解讀複製程式碼
#### `.agents/rules/agent.md`
```markdown
# Agent 行為準則

適用於 Cursor、OpenCode、Codex 等 AI 編碼助手。

## 通用要求
- 始終使用**簡體中文**與使用者溝通。
- 未經使用者明確要求，**不要**建立說明文件（README、*.md 等）。
- 未經使用者明確要求，**不要**執行 git commit / push / 修改 git 設定。
- 改動範圍最小化：只改與任務直接相關的程式碼，不順手重構無關模組。
- 優先重用專案既有抽象與約定，禁止憑空引入新架構或重複造輪子。

## 應當
- 改程式碼前先閱讀專案既有實作與目錄約定，保持風格一致。
- 優先重用專案內既有元件、composables、工具函式與 API 封裝。
- 任務完成後，在合適時執行專案設定的 lint / typecheck / test 腳本（若與改動相關）。
- 存在分層文件或 skills 時，**按需讀取**與目前任務相關的部分，不要預載全部。

## 不應
- 擅自新增說明性 Markdown 文件（除非使用者明確要求）。
- 為已自動匯入的 API / 元件寫冗餘 import。
- 引入與專案技術棧不符的 UI 函式庫或全新抽象層。
- 猜測不存在的 API 路徑、回應結構或設定項；以專案程式碼與型別定義為準。
- 在使用者未要求時新增測試、文件或無關註解。

---

原文出處：https://juejin.cn/post/7650089863866286115