《Cursor文檔》-規則

規則爲智能體提供系統級指令，將提示詞、腳本等內容整合在一起，便於在團隊內管理和共享工作流。

Cursor 支持四類規則：

項目規則¶

存儲在 .cursor/rules 中，納入版本控制，且僅適用於您的代碼庫。

用戶規則¶

適用於整個 Cursor 環境，由智能體 (聊天) 使用。

團隊規則¶

在儀表盤中管理的團隊級規則。適用於團隊版和企業版方案。

AGENTS.md¶

採用 Markdown 格式的智能體指令，是 .cursor/rules 的簡易替代方案。

規則的工作方式¶

大語言模型在不同補全之間不會保留記憶。規則在提示級別提供持久、可複用的上下文。

應用規則時，其內容會被添加到模型上下文的起始位置。這爲 AI 在生成代碼、理解編輯或協助處理工作流程時提供一致的指導。

項目規則¶

項目規則以 .mdc 文件的形式存放在 .cursor/rules 中，並納入版本控制。它們可以通過路徑模式限定適用範圍、手動調用，或根據相關性自動包含。

使用項目規則可以：

• 編碼與你的代碼庫相關的領域知識
• 自動化項目特有的工作流或模板
• 統一風格或架構決策

規則文件結構¶

每條規則都是一個 .mdc 文件，文件名可以隨意。項目規則必須使用 .mdc 擴展名。.cursor/rules 中的普通 .md 文件會被規則系統忽略，因爲它沒有用於指定 description、globs 和 alwaysApply 的 frontmatter。如果你更喜歡純 markdown，請改用 AGENTS.md。

.cursor/rules/
  react-patterns.mdc       # 識別爲項目規則
  api-guidelines.md        # 已忽略（擴展名錯誤）
  frontend/                # 可在文件夾中組織規則
    components.mdc

規則結構¶

每條規則都是一個帶有 frontmatter 元數據和內容的 markdown 文件。通過類型下拉菜單控制規則的應用方式，該菜單會更改 description、globs、alwaysApply 屬性。

在底層，這三個 frontmatter 字段會共同決定何時包含某條規則：

• 所有源文件必須包含公司版權聲明頭
• 當您對實現細節不確定時，請在提出更改建議之前閱讀相關源文件
• 切勿修改 dist/ 或 build/ 目錄中的生成文件

```md title="Auto-attached by file pattern"
---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports
- Co-locate styles in a module CSS file next to the component
- Keep components under 200 lines. Extract subcomponents into the same
  directory when a file grows beyond that
- Prefer composition over prop drilling. Pass children or render props
  instead of threading data through multiple layers

```md title=”Agent-selected based on description”¶

description: RPC service conventions and patterns for the backend
alwaysApply: false

• 在 src/services/ 目錄下爲每個服務定義獨立文件
• 在將數據傳遞給內部函數之前，始終在服務邊界處驗證輸入
• 返回包含 code 和 message 字段的結構化錯誤對象，
  切勿拋出原始字符串
• 創建新服務時，添加 @service-template.ts 參考文件以使用標準樣板代碼

```md title="Manual — only via @-mention"
---
alwaysApply: false
---

- 每次數據庫遷移必須同時包含 `up` 和 `down` 函數，以便完全回滾
- 切勿原地修改列類型。請添加新列、回填數據，然後在單獨的遷移中刪除舊列
- 參考模板瞭解預期的文件結構

@migration-template.sql

Glob 模式示例¶

使用 globs 可將規則限定爲僅適用於特定文件或目錄。多個模式之間用逗號分隔。

創建規則¶

創建規則有兩種方式：

• 在對話中使用 /create-rule：在 智能體 中輸入 /create-rule 並描述你的需求。智能體 會生成帶有正確 frontmatter 的規則文件，並將其保存到 .cursor/rules。
• 從自定義中創建：在側邊欄中打開 自定義，前往 規則，然後點擊 添加規則。這會在 .cursor/rules 中創建一個新的規則文件。你可以在自定義中查看所有規則及其狀態。

最佳實踐¶

好的規則應當聚焦、可操作且範圍清晰。

• 將規則控制在 500 行以內
• 將大型規則拆分成多個可組合的規則
• 提供具體示例或引用的文件
• 避免含糊其辭；像寫清晰的內部文檔那樣來寫規則
• 在聊天中重複提示時複用規則
• 引用文件而不是複製其內容——這可以讓規則保持簡短，並避免因代碼變更而變得過時

規則中應避免的做法¶

• 整份複製風格指南：這類工作交給 linter 更合適。Agent 已經瞭解常見的風格約定。
• 試圖窮舉所有可能的命令：Agent 已經熟悉 npm、git、pytest 等常用工具。
• 爲極少出現的邊緣情況添加說明：讓規則聚焦在你經常使用的模式上。
• 重複你代碼庫中已有的內容：引用規範示例，而不是複製代碼。

先從簡單的規則開始。只有當你發現 Agent 一再犯同樣的錯誤時，再新增規則。在真正理解你的模式之前，不要過度優化。

把規則提交到 git，讓整個團隊都能受益。當你看到 Agent 出錯時，就更新對應規則。你甚至可以在 GitHub 的 issue 或 PR 中 @cursor，讓 Agent 幫你更新規則。

規則文件格式¶

每條規則都保存在一個包含 frontmatter 元數據和正文內容的 Markdown 文件中。frontmatter 元數據用於控制規則的應用方式，正文內容則是規則本身。

---
description: "此規則提供前端組件和 API 驗證的標準"
alwaysApply: false
---

...rest of the rule content

如果 alwaysApply 爲 true，則該規則會應用於每個會話。否則，將把該規則的描述發送給 Cursor Agent，由其決定是否需要應用該規則。

示例¶

前端組件和 API 校驗規範¶

此規則爲前端組件提供規範：

在 components 目錄工作時：

• 一律使用 Tailwind 編寫樣式
• 使用 Framer Motion 實現動畫
• 遵循組件命名約定

此規則對 API 端點強制進行校驗：

在 API 目錄中：

• 所有校驗都使用 zod
• 使用 zod schema 定義返回類型
• 導出由 schema 生成的類型

Express 服務和 React 組件模板¶

此規則提供 Express 服務模板：

創建 Express 服務時使用此模板：

• 遵循 RESTful 原則
• 包含錯誤處理中間件
• 配置合適的日誌記錄

@express-service-template.ts

此規則定義 React 組件結構：

React 組件應遵循以下佈局：

• 頂部爲 Props 接口
• 組件使用命名導出
• 樣式放在底部

@component-template.tsx

自動化開發工作流與文檔生成¶

此規則自動化應用分析：

在被要求分析應用時：

1. 使用 npm run dev 啓動開發服務器
2. 從控制檯獲取日誌
3. 提出性能優化建議

此規則幫助生成文檔：

通過以下方式輔助起草文檔：

• 提取代碼註釋
• 分析 README.md
• 生成 markdown 文檔

在 Cursor 中添加新設置¶

首先在 @reactiveStorageTypes.ts 中創建一個需要切換的屬性。

在 @reactiveStorageService.tsx 中的 INIT_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,
    );
  }}
/>

在應用中使用時，引入 reactiveStorageService 並使用該屬性：

const flagIsEnabled =
  vsContext.reactiveStorageService.applicationUserPersistentStorage
    .myNewProperty;

不同的提供方和框架都提供了示例。社區貢獻的規則可以在各類衆包集合和線上代碼倉庫中找到。

團隊規則¶

Team 和 Enterprise 計劃可以通過 Cursor 儀表盤 在整個組織範圍內創建和實施規則。管理員可以配置每條規則對團隊成員是否爲必選。

團隊規則與其他規則類型協同工作，並優先生效，以確保組織標準在所有項目中得到貫徹。它們提供了一種強大的方式，在無需逐個單獨設置或配置的情況下，確保整個團隊在編碼規範、實踐和工作流方面保持一致。

管理團隊規則¶

團隊管理員可以直接在 Cursor 儀表板上創建和管理團隊規則：

創建團隊規則後，這些規則會自動對所有團隊成員生效，並在儀表板中顯示：

激活與強制執行¶

• 立即啓用此規則：選中後，此規則在創建後會立即生效。未選中時，此規則將作爲草稿保存，在你稍後啓用前不會生效。
• 強制執行此規則：啓用後，此規則對所有團隊成員一律生效，且無法在 自定義 中被關閉。未強制執行時，團隊成員可以在 自定義 的 Team Rules 下將此規則關閉。

默認情況下，未強制執行的 Team Rules 可以被用戶關閉。使用 強制執行此規則 來阻止用戶關閉該規則。

團隊規則 的格式及其應用方式¶

• 內容：團隊規則 是自由格式文本，不使用 項目規則 的文件夾結構。
• Glob 模式：團隊規則 支持 glob 模式 按文件範圍生效。當設置了 glob 模式時 (例如 **/*.py) ，只有當匹配文件在上下文中時纔會應用該規則。沒有 glob 模式的規則會應用於每一次對話。
• 適用範圍：當 團隊規則 被啓用 (且未被用戶禁用，除非被設爲強制執行) 時，它會被包含在該團隊所有代碼倉庫和項目中的 智能體 (Chat) 模型上下文中。
• 優先級：規則按以下順序應用：團隊規則 → 項目規則 → 用戶規則。所有適用規則會被合併；當指導衝突時，較前的來源優先。

一些團隊將強制規則作爲內部合規流程的一部分。雖然
這是受支持的用法，但 AI 指導不應成爲你唯一的安全控制措施。

導入規則¶

可以從外部來源導入規則，以複用現有配置或引入其他工具的規則。

遠程規則 (通過 GitHub)¶

從你有訪問權限的任何 GitHub 倉庫 (公共或私有) 直接導入規則。

1. 在側邊欄中打開 自定義
2. 前往 Rules，然後點擊 Add Rule
3. 選擇 Remote Rule (Github)
4. 粘貼包含這些規則的 GitHub 倉庫 URL。Cursor 會掃描倉庫中的所有 .mdc 文件。
5. Cursor 會拉取這些規則並將其同步到你的項目中

規則將放置在 .cursor/rules/imported/<repoName> 中。規則也會保留其相對路徑，因此 dir/rule.mdc 將被導入爲 .cursor/rule/imported/<repoName>/dir/rule.mdc。

AGENTS.md¶

AGENTS.md 是一個用於定義 Agent 指令的簡單 markdown 文件。你可以將它放在項目根目錄中，作爲 .cursor/rules 的替代方案，適用於簡單直接的用例。

與 Project Rules 不同，AGENTS.md 是一個不帶元數據或複雜配置的純 markdown 文件。它非常適合只需要簡單、易讀指令，而無需承受結構化規則開銷的項目。

Cursor 在項目根目錄和子目錄中都支持 AGENTS.md。

# Project Instructions

## Code Style

- Use TypeScript for all new files
- Prefer functional components in React
- Use snake_case for database columns

## Architecture

- Follow the repository pattern
- Keep business logic in service layers

改進¶

嵌套 AGENTS.md 支持¶

現在支持在子目錄中使用嵌套的 AGENTS.md 文件。你可以在項目的任意子目錄中放置 AGENTS.md 文件，在處理該目錄或其子目錄中的文件時，它們會自動生效。

這可以讓你根據當前正在處理的代碼庫部分，更精細地控制 agent 指令：

project/
  AGENTS.md              # 全局指令
  frontend/
    AGENTS.md            # 前端專用指令
    components/
      AGENTS.md          # 組件專用指令
  backend/
    AGENTS.md            # 後端專用指令

來自嵌套 AGENTS.md 文件的指令會與父目錄中的指令合併，更具體的指令會優先生效。

用戶規則¶

用戶規則是在 自定義 → 規則 中定義的全局首選項，適用於所有項目。它們會被 智能體 (Chat) 使用，非常適合用來設定偏好的溝通風格或編碼規範：

Please reply in a concise style. Avoid unnecessary repetition or filler language.

常見問題¶

爲什麼我的規則沒有被應用？¶

檢查規則類型。對於 Apply Intelligently，確保已設置描述。對於 Apply to Specific Files，確保文件模式與被引用的文件匹配。

規則可以引用其他規則或文件嗎？¶

可以。使用 @filename.ts 將文件包含到規則的上下文中。你也可以
在聊天中 @提及規則以手動應用它們。

我可以從聊天中創建規則嗎？¶

可以，你可以讓 智能體 爲你創建一個新規則。

規則會影響 Cursor Tab 或其他 AI 功能嗎？¶

不會。規則不會影響 Cursor Tab 或其他 AI 功能。

用戶規則 會應用到 Inline Edit（Cmd/Ctrl+K）嗎？¶

不會。用戶規則 不會應用到 Inline Edit (Cmd/Ctrl+K) 。它們只會被 智能體 (Chat) 使用。

相關內容¶

• 規則幫助信息