規則會為 Agent 和 Inline Edit 提供系統層級的指令。可以把它們想成專案的持續性脈絡、偏好或工作流程。 Cursor 支援四種類型的規則:

Project Rules

儲存在 .cursor/rules,受版本控制,且作用範圍限定在你的程式碼庫。

User Rules

全域套用到你的 Cursor 環境。在設定中定義,且會一律生效。

AGENTS.md

以 Markdown 格式撰寫的 Agent 指令,是 .cursor/rules 的簡單替代方案。

.cursorrules (Legacy)

仍受支援,但已淘汰。改用 Project Rules。

規則如何運作

大型語言模型在不同次的完成之間不會保留記憶。規則會在提示層級提供持久、可重用的上下文。 套用後,規則內容會被加入到模型上下文的開頭。這能為 AI 在產生程式碼、解讀編輯內容或協助處理工作流程時提供一致的指引。
在聊天上下文中套用規則
規則適用於 ChatInline Edit。啟用中的規則會顯示在 Agent 側邊欄。

專案規則

專案規則位於 .cursor/rules。每條規則都是獨立檔案並納入版本控制。它們可以用路徑模式限定作用範圍、手動呼叫,或依相關性自動納入。子目錄也可以包含各自的 .cursor/rules 資料夾,其作用範圍僅限於該資料夾。 把專案規則用在:
  • 編碼你程式碼庫的領域知識
  • 自動化專案特定的工作流程或範本
  • 標準化風格或架構決策

規則結構

每個規則檔都使用 MDC.mdc)撰寫,這種格式同時支援中繼資料與內容。透過「類型」下拉選單控制規則的套用方式,會對 descriptionglobsalwaysApply 屬性產生變更。
Rule TypeDescription
Always一律包含在模型上下文中
Auto Attached參照到符合 glob 模式的檔案時會自動包含
Agent Requested提供給 AI 使用,由 AI 決定是否包含。必須提供描述
Manual只有在以 @ruleName 明確提及時才會包含
---
description: RPC 服務樣板
globs:
alwaysApply: false
---

- 定義服務時請採用我們的內部 RPC 模式
- 服務名稱一律使用 snake_case。

@service-template.ts

巢狀規則

把規則放在專案各處的 .cursor/rules 目錄裡來做組織。當引用到該目錄中的檔案時,巢狀規則會自動套用。
project/
  .cursor/rules/        # 專案層級規則
  backend/
    server/
      .cursor/rules/    # 後端專用規則
  frontend/
    .cursor/rules/      # 前端專用規則

建立規則

使用 New Cursor Rule 指令或前往 Cursor Settings > Rules 來建立規則。這會在 .cursor/rules 中新增一個規則檔。你可以在設定中查看所有規則及其狀態。
精簡規則與冗長規則的比較

產生規則

在對話中直接使用 /Generate Cursor Rules 指令來產生規則。當你已經決定好 agent 的行為並想要重複使用時,這會很好用。

最佳實務

好的規則應該聚焦、可操作,且範圍明確。
  • 讓每條規則控制在 500 行以內
  • 把大型規則拆成多個可組合的規則
  • 提供具體範例或參考檔案
  • 避免含糊的指引。把規則寫得像清晰的內部文件
  • 在聊天室中重複使用提示時,重用既有規則

範例

這條規則定義前端元件的標準:在 components 目錄作業時:
  • 樣式一律使用 Tailwind
  • 動畫使用 Framer Motion
  • 遵循元件命名慣例
這條規則也會強制 API 端點進行驗證:在 API 目錄:
  • 所有驗證使用 zod
  • 用 zod schema 定義回傳型別
  • 匯出由 schema 產生的型別
這條規則提供 Express 服務的樣板:建立 Express 服務時請用這個樣板:
  • 遵循 RESTful 原則
  • 加入錯誤處理 middleware
  • 設定適當的記錄
@express-service-template.ts這條規則也定義 React 元件的結構:React 元件應遵循以下結構:
  • 最上方放 Props 介面
  • 元件以具名匯出
  • 樣式置於底部
@component-template.tsx
這條規則會自動化 app 分析:當被要求分析 app 時:
  1. npm run dev 啟動開發伺服器
  2. 從主控台擷取日誌
  3. 提出效能優化建議
這條規則也協助產生文件:協助撰寫文件的方式:
  • 擷取程式碼註解
  • 分析 README.md
  • 產生 Markdown 文件
先在 @reactiveStorageTypes.ts 建立要切換的屬性。@reactiveStorageService.tsxINIT_APPLICATION_USER_PERSISTENT_STORAGE 加上預設值。如果是 beta 功能,在 @settingsBetaTab.tsx 新增切換;否則在 @settingsGeneralTab.tsx 新增。一般核取方塊的切換可用 <SettingsSubSection>。參考檔案其餘部分的範例。
<SettingsSubSection
				label="Your feature name"
				description="Your feature description"
				value={
					vsContext.reactiveStorageService.applicationUserPersistentStorage
						.myNewProperty ?? false
				}
				onChange={(newVal) => {
					vsContext.reactiveStorageService.setApplicationUserPersistentStorage(
						'myNewProperty',
						newVal
					);
				}}
			/>
在 app 中使用時,匯入 reactiveStorageService 並使用這個屬性:
const flagIsEnabled = vsContext.reactiveStorageService.applicationUserPersistentStorage.myNewProperty
有許多來自各供應商與框架的範例。社群貢獻的規則可在眾包的集合與線上儲存庫中找到。

AGENTS.md

AGENTS.md 是一個用來定義代理指令的簡單 Markdown 檔案。把它放在專案根目錄,作為 .cursor/rules 的替代方案,適用於簡單直接的使用情境。 與 Project Rules 不同,AGENTS.md 是沒有中繼資料或複雜設定的純 Markdown 檔。對於需要簡潔、易讀指令、又不想承擔結構化規則額外負擔的專案來說,它再適合不過。
# 專案說明

## 程式碼風格
- 所有新檔一律使用 TypeScript
- React 優先採用函式元件
- 資料庫欄位使用 snake_case

## 系統架構
- 遵循 repository pattern
- 將業務邏輯放在 service layer

使用者規則

使用者規則是定義在 Cursor Settings → Rules 的全域偏好設定,會套用到所有專案。這些規則是純文字格式,超適合用來設定偏好的溝通風格或程式碼慣例:
請用精準精煉的方式回覆,避免不必要的重複或贅詞。

.cursorrules(舊版)

專案根目錄中的 .cursorrules 檔案仍然支援,但將被淘汰。建議遷移到 Project Rules,以獲得更好的控管、彈性與可見性。

常見問題

先檢查規則類型。對於 Agent Requested,請確認已設定描述。對於 Auto Attached,請確認檔案樣式符合被引用的檔案。
可以。使用 @filename.ts 把檔案納入規則的脈絡。
可以,用 /Generate Cursor Rules 指令從聊天產生專案規則。若啟用 Memories,會自動產生對應的記憶。
不會。規則只適用於 Agent 與 Inline Edit