wbstorm

如何寫 Cursor Rules：專案規則檔要寫什麼、Agent 怎麼用

在 .cursor/rules 寫 .mdc：選掛載方式、寫可執行正文，Agent 會在符合時把規則放進上下文開頭。

Cursor Agent 不會在兩次對話之間記住你的口頭約束。同一句「別改路由」貼第三次時，就該寫進專案規則，讓下一場對話開場就帶著它。

官方文件把這套機制叫 Cursor Rules。專案規則放在 .cursor/rules，檔案必須是 .mdc。同目錄裡的普通 .md 會被忽略。這是編輯器教學，不是腦力激盪產品說明書。

建 .mdc寫 frontmatterAgent 注入

專案規則是什麼

對照 cursor.com/docs/context/rules。四類來源裡，入門只需要倉庫裡的專案檔。規則生效時，正文出現在模型上下文開頭。

.mdc
專案規則副檔名
4 種
掛載方式
開頭
注入位置
來源放哪裡何時進上下文
Project Rules.cursor/rules/*.mdc按 frontmatter
User RulesCustomize → RulesAgent（Chat），全域
Team Rules控制台（Team / Enterprise）全倉庫；可強制
AGENTS.md根目錄或子目錄純 Markdown，無 frontmatter

四步寫出第一條規則

  1. 1

    建檔

    在倉庫建 .cursor/rules/your-name.mdc。也可在 Agent 裡輸入 /create-rule，或打開側欄 Customize → Rules → Add Rule。子資料夾可以，副檔名必須是 .mdc。

  2. 2

    選掛載方式

    alwaysApply: true 每場都帶。globs 在符合檔案進入上下文時帶。只寫 description 時由 Agent 判斷。三者都空則只在聊天裡 @規則名 時帶上。

  3. 3

    寫可執行正文

    寫成內部文件：禁止項、命名、目錄邊界。用 @filename.ts 指向範例，不要把整份檔案貼進規則。官方建議單條不超過 500 行。

  4. 4

    提交並核對

    把規則推進 git，團隊才共享同一套約束。在 Customize 裡看狀態。Agent 仍漏讀時，在對話裡 @ 這條規則。

正文裡該寫什麼

01

linter 管不到的約定

例如「產生檔不准改」「新服務必須帶結構化錯誤」。常見風格交給 ESLint / rustfmt，不要把整本風格指南塞進規則。

02

架構邊界

哪一層能碰資料庫、哪條目錄禁止跨引。Agent 已經會用 git 和 npm，不必羅列日常命令。

03

指向倉庫裡的範例

用 @ 引用既有範本。程式一變，規則不會過期。發現 Agent 反覆犯同一錯，再補一條，而不是開場就堆二十份。

---
description: TypeScript conventions for this repo
globs: **/*.{ts,tsx}
alwaysApply: false
---

# TypeScript
- Prefer named exports
- Do not edit files under dist/
- New API clients follow @src/api/client.ts

Agent 怎麼用這條規則

符合成功後，規則正文出現在上下文開頭，用來產生程式、解釋改動、走工作流程。衝突時官方順序是 Team Rules → Project Rules → User Rules，先出現的優先。Rules 不影響 Cursor Tab。User Rules 不作用於 Inline Edit（Cmd/Ctrl+K）。

和 AGENTS.md 怎麼選

只想放一段人人能讀的說明，用倉庫根或子目錄的 AGENTS.md。巢狀檔案在處理該目錄及其子目錄時自動合併，更具體的優先。需要按 glob 或手動 @ 的精細控制，繼續用 .mdc。

規則寫完、要攤開草圖時，回 wbstorm 用房間號即可，另見 建立或加入房間 和 白板基礎。

為什麼規則沒有生效？

先對掛載類型。Apply Intelligently 必須有 description。按檔案必須讓 glob 命中目前上下文裡的路徑。普通 .md 放在 .cursor/rules 會被忽略。

規則會影響 Tab 補全嗎？

官方 FAQ 寫：Rules 不影響 Cursor Tab 或其他非 Agent 功能。User Rules 也不作用於 Inline Edit。

可以引用其他檔案嗎？

可以。在規則正文裡寫 @filename.ts。也可以在聊天裡 @ 規則名做手動掛載。

這是 wbstorm 的功能說明嗎？

不是。本文只講 Cursor 編輯器的專案規則。wbstorm 是瀏覽器腦力激盪房間，和規則檔無關。

建立房間