Skip to content

建立 2026-09-19 更新 2026-09-19

Cursor：Project Rules（.mdc）

Cursor 是一個以 AI 為核心重新打造的程式編輯器（VS Code 的分支）。它用 Rules（規則） 這個機制取代其他工具常見的「技能包」：規則是一份 Markdown 檔，透過 YAML frontmatter 決定「什麼時候要套用」。

檔案放哪裡

  • Project Rules（推薦、需版控）：.cursor/rules/ 資料夾下的每個 .mdc 檔就是一條規則，可以依需要建立多個檔案，也能在子資料夾各自放一份，方便 monorepo 內每個套件有自己的規則。
  • User Rules（全域，只在你自己的機器生效）：在 Cursor 設定的 Customize → Rules 介面輸入，不會進 Git，只套用到 Chat（Agent），不影響 Inline Edit。
  • 舊格式 .cursorrules：放在專案根目錄的單一純文字檔，是 Cursor 最早的做法，目前仍可運作，但官方已標示為 legacy——不會再有新功能，也無法使用 globs、alwaysApply 等進階控制。新專案請直接用 .cursor/rules/*.mdc，不要再建立 .cursorrules。
  • 跨工具通用格式：Cursor 也會讀取專案根目錄或子資料夾中的 AGENTS.md，適合想讓同一份說明同時給 Cursor、Codex 等多個工具共用的情境。

優先順序（前者蓋過後者）：Team Rules → Project Rules → User Rules。

撰寫格式

.mdc 檔開頭是一段 YAML frontmatter，接著是一般 Markdown 內容：

---
description: 說明這條規則在處理什麼、什麼情況該套用
globs: "src/**/*.ts,src/**/*.tsx"
alwaysApply: false
---

- 元件一律使用具名匯出（named export），不要用 default export。
- 所有非同步函式都要用 try/catch 包起來，並記錄錯誤到 logger。

三個欄位決定規則屬於哪一種類型：

類型 設定方式 何時套用
Always Apply alwaysApply: true 每一次對話都自動套用，適合團隊共同的硬性規範
Apply Intelligently 只填 description，不填 globs Agent 自行判斷目前任務是否相關，相關才載入
Apply to Specific Files 填 globs 編輯到符合路徑的檔案時自動套用
Apply Manually description／globs 都留空 只能在對話裡用 @規則名 手動叫出來

實際應用

一個中型專案常見的規則資料夾長這樣：

.cursor/
└── rules/
    ├── general.mdc        # alwaysApply: true，團隊共同規範
    ├── frontend.mdc        # globs: src/components/**/*.tsx
    ├── api-error.mdc       # description 觸發，講如何處理 API 錯誤
    └── db-migration.mdc    # 只能手動 @db-migration 叫出來

拆成多個小檔案而不是一個大檔案，好處是 Agent 只會載入跟目前任務相關的規則，不會把整包規範都塞進上下文。

官方文件

完整規格與更多範例：Cursor Docs：Rules

推薦影音

快速上手 .mdc 規則

簡述：15 分鐘內示範如何建立 .cursor/rules 資料夾、寫出第一條 .mdc 規則，並解釋 globs／alwaysApply 的差異，適合完全沒寫過 Cursor 規則的人。

實務撰寫技巧

簡述：分享實際專案中怎麼組織多個規則檔、如何避免規則互相打架，適合已經寫過幾條規則、想進一步優化的讀者。

相關資料