Rules

Rules 是 Cursor 給 Agent 的系統級長期指令。官方文件說明，Rules 可以把 prompts、scripts 等打包在一起，方便團隊管理和共享 workflow。它解決的是“每次都要重複告訴 Agent 的專案約定”。

閱讀目標：讀完本章，你應該能判斷一條指令應該放 Project Rule、User Rule、Team Rule、AGENTS.md，還是不要寫成長期規則。

1. 四類 Rules

官方文件列出四類規則。

型別	落點 / 範圍	適合
Project Rules	`.cursor/rules`，進版本控制，作用於程式碼庫	專案架構、目錄、測試、生成檔案禁區
User Rules	全域性 Cursor 環境，用於 Agent Chat	個人偏好，不適合團隊約束
Team Rules	Dashboard 管理，Team / Enterprise 可用	團隊統一規範
AGENTS.md	markdown agent instructions，`.cursor/rules` 的簡單替代	簡單專案、跨 agent 相容入口

真實專案優先 Project Rules，因為它隨儲存庫走，能 code review，也能讓團隊看到同一套約束。

2. Rules 怎麼生效

官方說明，LLM 不會在 completions 之間保留記憶。Rules 提供 prompt-level 的 persistent reusable context。規則被應用時，其內容會放到 model context 開頭。

flowchart TD
  Task["Agent task"] --> RuleMatch["Rule matching"]
  RuleMatch --> Context["Included at start of model context"]
  Context --> Agent["Agent follows guidance"]
  Agent --> Diff["Code / command / answer"]

所以 Rule 不應該寫廢話。它會佔上下文，也會影響每次任務判斷。

3. Project Rule 檔案結構

官方示例：

.cursor/rules/
  react-patterns.mdc
  api-guidelines.md
  frontend/
    components.md

Cursor 支援 .md 和 .mdc。如果需要 frontmatter 控制 description、globs、alwaysApply，用 .mdc 更清晰。

4. Rule 型別和 frontmatter

官方 Rule Type 對應這些行為：

Rule Type	行為
Always Apply	每個 chat session 都應用
Apply Intelligently	Agent 根據 description 判斷是否相關
Apply to Specific Files	檔案匹配 globs（檔案路徑模式，如 `src/*/.ts`）時應用
Apply Manually	在 chat 中 `@my-rule` 手動提及才應用

frontmatter 組合：

`alwaysApply`	`description`	`globs`	行為
`true`	任意	任意	總是 included
`false`	空	provided	匹配檔案時 auto-attached
`false`	provided	空	Agent 根據 description 拉取
`false`	空	空	只能 `@` mention

5. 寫 rule 的尺度

官方最佳實踐：good rules are focused, actionable, and scoped。

應該做：

保持 rule 低於 500 行。
大規則拆成多個可組合 rules。
提供具體例子或引用檔案。
避免 vague guidance。
當同一個 prompt 重複出現時複用 rule。
引用 canonical files，而不是複製全文。

不要做：

複製整份 style guide，交給 linter 更合適。
記錄所有常見命令，Agent 已經知道 npm、git、pytest 等常用工具。
為少見 edge case 寫長期規則。
複製程式碼庫裡已經存在的內容。

從簡單開始。只有當你發現 Agent 反覆犯同一個錯誤時，再更新 rule。

深讀：為什麼 Rule 應該進 Git

Project Rules 進入 .cursor/rules 並版本控制後，它們會變成團隊工程資產：可以 review、可以追溯、可以和程式碼一起演進。個人 User Rules 不適合承載團隊規範，因為別人看不到，也無法保證 CI、review 和 onboarding 一致。

如果一個規則影響程式碼結構、測試要求、目錄邊界或釋出流程，它應該是 Project Rule 或 Team Rule，而不是個人口頭經驗。

本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

Project Rule 和 User Rule 的邊界是什麼？
alwaysApply、description、globs 如何決定 rule 是否被 included？
為什麼不要把整份 style guide 複製進 Rule？

透過標準：你能為一個專案寫出 2-3 條 focused Project Rules，並解釋每條規則的觸發方式。

官方來源

Cursor Rules —— 官方說明 Rules 型別、檔案結構、frontmatter、globs、建立方式和最佳實踐。
Cursor Rules Help —— Help Center Rules 入門說明。