Cursor Rules 怎麼寫：.cursor/rules 配置、四種生效方式、範例與最佳實踐

本文根據 Cursor 官方文檔《Rules》整理，資料核對於 2026-10-11。文中的規則範例是照官方格式重新寫的中文示例，不是官方原文。

適用於誰

• 每次開新對話都要重複交代「用 TypeScript」「別動 dist 目錄」的人；
• 搜「cursor rules 配置」「cursor rules 最佳實踐」「cursor rules 範例」的人；
• 把規則寫成了 .md 文件，發現完全不生效的人。

結論先說

1. Cursor 有四種規則：Project Rules（項目裏的 .cursor/rules）、User Rules（你個人的全局偏好）、Team Rules（團隊後台統一下發）、AGENTS.md（項目根目錄的純 Markdown 說明）。
2. 項目規則必須是 .mdc 後綴。放在 .cursor/rules 裏的普通 .md 文件會被規則系統忽略——這是「寫了不生效」最常見的原因。
3. 每條規則靠 frontmatter 的三個字段決定何時進入上下文：alwaysApply、description、globs。
4. 官方建議：單條規則不超過 500 行、拆成多個小規則、引用文件而不是把內容抄進規則；Agent 反覆犯同一個錯時再加規則，不要一開始就寫一大堆。
5. 規則隻影響 Agent（聊天），不影響 Tab 補全；User Rules 也不作用於行內編輯（Ctrl+K）。

規則是怎麼起作用的

大模型在兩次回答之間沒有記憶。規則的作用就是把一段固定的說明，在需要的時候放到模型上下文的最前面。所以規則寫得越長、越多條同時生效，佔用的上下文就越多——這也是官方強調「聚焦、可執行、有範圍」的原因。

文件放哪、叫什麼

bash
.cursor/rules/
  react-patterns.mdc       # 會被識別
  api-guidelines.md        # 被忽略（後綴不對）
  frontend/                # 可以用文件夾分類
    components.mdc

文件名隨意。創建方式有兩種：在 Agent 裏輸入 /create-rule 並描述你要的規則，它會生成帶 frontmatter 的文件；或者在側邊欄 Customize → Rules → Add Rule 裏新建，那裏也能看到所有規則和它們的狀態。

四種生效方式

介面上的類型下拉對應 frontmatter 裏三個字段的組合：

範例一：始終生效（項目總則）

md
---
alwaysApply: true
---
- 本項目用 pnpm，不要用 npm 或 yarn 安裝依賴
- 不要修改 dist/ 和 build/ 裏的生成文件
- 拿不準實現細節時，先讀相關源碼再提方案

範例二：按文件路徑自動附加

md
---
globs: src/components/**/*.tsx
alwaysApply: false
---
- 組件用具名導出，不用預設導出
- 單個組件不超過 200 行，超了就在同目錄拆子組件
- 新組件先讀 @component-template.tsx，照它的結構寫

範例三：由 Agent 按描述判斷

md
---
description: 後端 RPC 服務的約定與寫法
alwaysApply: false
---
- 每個服務單獨放在 src/services/ 下的一個文件裏
- 入參在服務邊界處校驗
- 返回帶 code 和 message 的錯誤對象，不要直接拋字符串

範例四：只在 @ 提到時生效

md
---
alwaysApply: false
---
- 每個數據庫遷移必須同時有 up 和 down
- 不要原地修改列類型：新增列、回填、再在另一次遷移裏刪舊列

globs 的寫法：**/.ts 匹配任意目錄下的 ts 文件，src/ 匹配 src 下所有文件，多個模式用逗號分隔，如 docs//.md, docs/**/*.mdx。

規則裏引用文件

在規則裏寫 @migration-template.sql 這樣的路徑，是告訴 Agent「去哪看」。官方說明：文件內容不會被塞進提示詞，而是 Agent 需要時用工具去讀；編輯器、命令行和雲端 Agent 都是這樣。所以必須始終在上下文裏的東西，要直接寫在規則正文裏。

官方最佳實踐

該做的：

• 規則保持在 500 行以內，大規則拆成幾條可組合的小規則；
• 給具體例子，或指向項目裏的標準寫法；
• 像寫內部文檔一樣寫清楚，避免空泛的要求；
• 把規則提交進 Git，讓全隊共用；發現 Agent 犯錯就更新規則。

別做的：

• 照抄整份代碼規範——交給 linter，常見規範 Agent 本來就懂；
• 羅列所有命令——npm、git、pytest 這些它都會；
• 為很少出現的邊角情況寫規則；
• 把代碼庫裏已有的東西再抄一遍——指向那份代碼就行。

和 User Rules、Team Rules、AGENTS.md 的關係

• User Rules：在 Customize → Rules 裏填，對你所有項目生效，適合寫「用中文簡潔回答」這類個人偏好。
• Team Rules：Teams / Enterprise 管理員在後台創建，可設為強制（成員無法關閉）。
• AGENTS.md：放在項目根目錄的純 Markdown，沒有 frontmatter，適合規則不多的項目；子目錄裏也可以放，處理該目錄下的文件時自動生效，越具體的越優先。跨工具共用的寫法見《AGENTS.md 怎麼寫》。
• 優先級：Team Rules → Project Rules → User Rules，全部合併，衝突時前者優先。

常見問題

Q：規則為什麼沒生效？

先看後綴是不是 .mdc；再看類型：Apply Intelligently 必須有 description，Apply to Specific Files 要確認 glob 真的匹配到了當前涉及的文件。

Q：能從別人的倉庫導入規則嗎？

規則不能單獨導入。官方的做法是把規則打包成插件（plugin），通過 marketplace 發佈後安裝，規則隨插件一起到位。

Q：規則能當安全措施用嗎？

不能只靠它。官方原話的意思是：有團隊把強制規則納入合規流程，這可以，但 AI 指引不應是唯一的安全控制。

參考資料

• Rules（官方）：https://cursor.com/docs/rules
• Agent troubleshooting（官方幫助中心）：https://cursor.com/help/troubleshooting/agent-issues