如果你已經每天用 Cursor、Copilot 或 Claude Code 寫程式,卻還三不五時碰到這種情況——AI 生出來的元件沒照專案的寫法、明明定義好的 TypeScript 型別它又改回 any、規定要用 v-auth 它偏要自己刻一段 if (role === ...)——先別急著怪模型不夠強。問題多半不在它不會寫,而在它根本不知道你們專案的規矩。這篇就來談「規則檔與上下文工程」:把團隊裡那些「老人才知道」的隱性共識,寫成 AI 每次開工都會讀到的顯性規則。
一、先講清楚痛點:不是不懂,是「沒被告訴」
編碼助手每次開一個新對話,基本上是無狀態的:它看不見你整個 repo 的來龍去脈,只能靠「這次對話放進來的內容」來判斷。而上下文視窗有限,你不可能把幾萬行程式碼全貼進去。於是就出現一個很實際的落差——你腦中有一整套規範(用什麼框架、權限怎麼控、型別放哪、時間格式用哪個工具),但 AI 只看得到你剛選取的那幾個檔案。
規則檔要解決的就是這件事:把「每次都要重講一次」的規矩,變成「開工前就自動載入」的背景知識。差別很像帶新人:與其每交代一件事就補一句「喔對了我們不用 Options API」,不如第一天就給他一份寫好的開發手冊。
二、步驟 1:建立「分層」的規則檔
別把所有規則塞進一個超長檔案。比較好維護的做法是分兩層:AGENTS.md 放跨工具通用的鐵律(Cursor、Copilot、Claude Code 都認得,放 repo 根目錄),工具專屬的細節再交給 .cursor/rules/*.mdc 依路徑觸發(舊版則是 .cursorrules)。
# AGENTS.md(放在 repo 根目錄,進版控)
## 專案棧
Vue 3 + TypeScript + Pinia + Ant Design Vue(Vben Admin)
## 寫碼規則
- 元件一律 <script setup lang="ts">,禁止 Options API
- 權限用 v-auth 指令,不要自己寫 if (role === ...)
- 所有對外文字進 i18n,template 裡禁止寫死中文字串
- 列表用 Table、表單用 ApiSelect、部門用 TreeSelect
- API 型別放 src/api/**/types.ts,禁止 any
- 時間格式一律呼叫共用工具 ToDateTime()
## 禁止事項
- 不要新增依賴套件,除非我先同意
- 不要改動 src/router 的路由守衛
## 提交前
npm run type-check && npm run lint
重點:「不要新增依賴套件」這類規則特別值得寫進去,因為 AI 很常為了解一個小需求就順手裝一個包,而這正是套件幻覺與供應鏈風險最容易溜進來的地方。
第二層用 globs 限定範圍,只有動到對應目錄才載入,避免每次都佔用上下文:
---
# .cursor/rules/vue.mdc
description: Vue 元件產出規則
globs: ["src/views/**/*.vue"]
alwaysApply: false
---
1. 用 <script setup lang="ts">,props 用 defineProps<T>()
2. 表格對齊:內容用 align,表頭用 customHeaderCell
3. 新增的 .vue 都要補上對應的 i18n key
三、步驟 2:把規則寫成「可驗證」的句子
規則檔最常見的失敗,是寫了一堆正確但沒用的形容詞。對比一下就很清楚:
- ❌「請寫出乾淨、高品質、符合最佳實踐的程式碼」→ AI 無從判斷,等於沒寫。
- ✅「元件一律
<script setup lang="ts">;禁止any;對外文字進 i18n」→ 一眼就能檢查有沒有做到。 - ✅「附上一個反例」也很有效:直接貼一段被退過的寫法,註明「不要照這個寫」,比正向描述更能壓住模型的慣性。
判斷標準很簡單:這條規則能不能用 grep、型別檢查或 code review 的一句話判定通過與否?不能,就再改寫一次。另外規則別貪多,十條以內、彼此不衝突,效果通常比三十條互相打架好得多。
四、步驟 3:任務級的「上下文打包」
規則檔管的是長期背景,單次任務還是要靠你精準餵料。與其丟一句「幫我加個資產編輯視窗」,不如組一個明確的上下文包:任務 + 參考檔 + 約束 + 驗收條件。
[任務] 在 src/views/assetManagement 新增「資產編輯」Modal
[參考] @src/views/userManagement/index.vue (表單版型)
@src/api/asset/types.ts (欄位型別)
@AGENTS.md
[約束] 抽屜改 Modal;沿用 ApiSelect;不要動路由與 store
[驗收] npm run type-check 通過;欄位與 types.ts 一比一
這裏有三個小技巧:先給型別定義再叫它寫 UI(型別是最濃縮的規格,比自然語言描述省 token 又不易誤解);明確列出「不要動」的範圍(AI 最常過度热心地順手重構隔壁檔案);給可執行的驗收條件,讓它自己跑一次型別檢查再回報。
特別注意:上下文不是越多越好。把整個 src/ 都 @ 進來,反而會讓關鍵規則被稀釋,這就是俗稱的「上下文污染」。一個任務開一個乾淨會話、一次只做一件事,長對話走到歪路時果斷重開,比一路追加更正更省時間。
五、步驟 4:讓規則檔跟著專案一起演進
規則檔不是寫一次就萬年有效,它必須被當成程式碼對待:進版控、進 PR、定期回顧。框架升級、換了元件庫、新增一條權限規範,都要同步改 AGENTS.md,否則 AI 會很忠實地照著過期規則產出「合法但已淘汰」的寫法。
# CI:確保規則檔存在且被納入版本控管
test -f AGENTS.md || { echo "AGENTS.md 缺失"; exit 1; }
git ls-files --error-unmatch AGENTS.md > /dev/null
還有一個很划算的習慣:每次 code review 發現 AI 又犯同一個錯,就補一條規則。與其在對話裡罵它第三次,不如花三十秒把教訓沉澱成規則檔的一行。幾週下來,這份檔案會變成團隊最值錢的資產之一——它不只約束 AI,也順手把新人培訓文件補齊了。
六、三條特別注意
- 規則衝突要優先處理:根目錄
AGENTS.md、子目錄規則、工具內建指令三者打架時,多數工具以「越靠近檔案、越後載入」為準;發現 AI 忽悠某條規則,先檢查是不是被別處覆蓋了。 - 別把密鑰寫進規則檔:它會進 git、會被打包、也可能被整段貼進模型請求。金鑰一律走環境變數與後端代理,規則檔只寫「去哪裡讀」,不寫值。
- 規則檔取代不了審查:它提高的是「一次到位率」,不是正確性保證。型別檢查、測試、人工看 diff 仍然要跑,尤其是牽涉權限與金流的地方。
說到底,上下文工程不是什麼玄學,而是把「你以為大家都懂」的事情寫清楚。當 AI 每次開工都先讀到同一份開發手冊,它就不再是一個每次都要重新調教的外援,而比較像一位真的待過這個專案的同事。
互動話題:你的專案裡有沒有一條「講過一百次、AI 還是照犯」的規矩?歡迎在留言貼出來,我們一起把它改寫成一條能被驗證的規則 👇