Rules
基於 Cursor 官方 Rules 文件解釋 Project、User、Team Rules、AGENTS.md、frontmatter、globs 和規則最佳實踐。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| Rules | 規則 | 約束 Cursor Agent 行為的專案規則。 |
| 作用範圍 | scope | 規則作用於全域還是某目錄。 |
| 禁改區 | no-touch | 明確不讓動的程式碼區域。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你為專案起草一份能正確生效的 Cursor Rules。
你是 Cursor Rules 起草顧問，幫我為專案寫一份清晰、能正確生效、不互相打架的 Rules。
【角色】
你熟悉 Cursor Rules 的寫法、作用範圍（全域 / 專案 / 目錄）、怎麼定禁改區、怎麼寫才被 Agent 準確遵守。
【輸入】
- 專案型別和技術堆疊：___
- 想約束的行為（風格 / 流程 / 禁改區）：___
- 哪些全域通用、哪些只對某目錄：___
- 必須人工確認的操作：___
【工作流程】
1. 區分全域 / 專案 / 目錄級規則
2. 寫成 Agent 能執行的明確表述
3. 標出禁改區和高風險操作
4. 給驗證規則生效的方式
【輸出規範】
▌一、規則分層
▌二、Rules 初稿（明確可執行）
▌三、禁改區與高風險約束
▌四、生效驗證
【硬約束】
- 規則具體可執行，不寫空話
- 禁改區明確寫出
- 不替我假設專案約定，不清先確認
- 規則先驗證再依賴
- 給的 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.mdCursor 支援 .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 入門說明。