Cursor 从 .cursorrules 迁移到 .cursor/rules：四种 Rule Type 怎么用

Cursor Rules 是给 AI 编程助手的”项目规约”——它告诉 Cursor 在生成代码时该遵守哪些约定（技术栈、命名、目录结构、禁用项），让 AI 不用你每次都在对话里反复交代。 早期大家把这些规则塞在项目根目录的单个 .cursorrules 文件里；现在 Cursor 已经把它渐渐弃用，主推 .cursor/rules/ 目录下的多个 .mdc 规则文件。这篇带你看懂为什么要迁移、四种 Rule Type 各管什么、以及怎么把一坨大规则拆成好用的小规则。

如果你还没把 Cursor 跑起来，建议先看 Cursor 入门教程；想控制 AI 能读哪些文件，配套看 .cursorignore 怎么写。

为什么要从 .cursorrules 迁移

老的 .cursorrules 是单文件、全局生效：不管你在改哪个文件，整份规则都会被塞进上下文。项目一大，这种做法就有几个硬伤：

• 规则越堆越长，前端、后端、测试、文档的约定全挤在一个文件里，AI 抓不住重点。
• 无差别注入上下文，写一个样式文件时也要带上一堆后端规则，浪费 token、稀释注意力。
• 无法按文件类型生效，你没法说”只有改 .tsx 时才套用 React 规约”。

.cursor/rules/ 的新机制解决的就是这些：一条规则一个文件，还能按需触发。.cursorrules 目前仍能用（向后兼容），但属于过渡状态，新项目建议直接上新写法。

举个真实的例子：我接手过一个中型 React + Node 项目，老的 .cursorrules 有 180 多行，前端命名规范、后端错误处理、数据库迁移约定、Git 提交格式全堆在一起。团队里有人改一个 CSS 样式文件，Cursor 也会把整份 180 行规则塞进上下文——里面九成内容跟当前任务毫无关系。结果是：上下文窗口被无关信息占掉一截，AI 生成代码时该守的 API 层约定反而被稀释到不起眼的位置，偶尔就漏掉了。拆成 .mdc 之后，改样式文件只触发十几行的 styles.mdc，改 API 文件才触发 api.mdc，上下文干净了，AI 也更容易抓住这次任务真正相关的约定。这就是拆分带来的实际收益，不是形式上的整理。

新写法：.cursor/rules 与 .mdc 文件

新规则放在项目根的 .cursor/rules/ 目录里，每个文件是一个 .mdc（Markdown with frontmatter）。一个典型的 .mdc 长这样：

---
description: 项目的 API 请求层约定
globs: src/api/**/*.ts
alwaysApply: false
---

- 所有请求统一走 src/api/client.ts 的封装，不直接调用 fetch
- 接口返回类型必须显式声明，禁止用 any
- 错误用 Result 包装，不在请求层直接 throw

文件由两部分组成：

• frontmatter（顶部 --- 之间）：用 description、globs、alwaysApply 三个字段决定这条规则什么时候被触发。
• 正文（Markdown）：写给 AI 看的具体约定，越具体越好，最好给正反例。

提示：.mdc 的具体字段名和支持的语法以官方文档为准，Cursor 的 UI（Settings → Rules）也能可视化创建和切换 Rule Type，不一定要手写 frontmatter。

四种 Rule Type 怎么用

这是迁移的核心。同样一份规则正文，靠 frontmatter 的组合，可以表现为四种触发方式：

Rule Type	触发时机	关键字段	典型用途
Always	每次请求都注入	alwaysApply: true	全局铁律：语言、技术栈、绝对禁用项
Auto Attached	改到匹配 glob 的文件时注入	配 globs	某目录/某类型文件的专属规约
Agent Requested	AI 自己判断要不要拉取	配 description，alwaysApply: false	偶尔用得上的规则，靠描述被检索
Manual	你 @ 提及时才生效	不配 globs、无 alwaysApply	临时/低频规约，手动挂载

Always（始终生效）

设 alwaysApply: true，这条规则每次对话都进上下文。适合放全项目通吃的硬约束——比如”本项目用 TypeScript + pnpm，不要引入新依赖前先问”。Always 规则要短而狠，别把细节都堆这里，否则又回到老 .cursorrules 的老路。

Auto Attached（按文件自动挂载）

配 globs（如 src/components/**/*.tsx），只有当你正在编辑匹配的文件时，这条规则才被注入。这是新机制最大的价值：让规则跟着文件走。前端组件规约只在改组件时生效，数据库迁移规约只在改 migration 时生效，互不打扰。

Agent Requested（AI 按需检索）

alwaysApply: false 且不靠 glob 强绑，而是写一句清晰的 description。Cursor 的 Agent 会根据当前任务和这句描述，自行决定要不要把规则拉进来。所以这里的 description 要写得像”检索关键词”——直接说清”这条规则在什么情况下有用”。

Manual（手动 @ 引用）

什么都不自动触发，只有你在对话里用 @规则名 主动提及时才生效。适合低频、特定场景的规约，比如”发布前的 checklist""某次重构的临时约定”。

拆分规则的最佳实践

迁移不是把老 .cursorrules 整段复制进一个 .mdc 就完事——那只是换了层皮。真正的收益来自拆小：

• 一条规则只管一件事：react.mdc、api.mdc、testing.mdc、commit.mdc 分开，别合并。
• Always 规则保持精简：只放真正全局的铁律（≤10 条），其余都下放成 Auto Attached。
• 用 glob 精准绑定：能用 Auto Attached 就别用 Always，按需注入才省 token、提准确率。
• description 写成”被检索的话”：给 Agent Requested 规则的描述要具体，写清适用场景。
• 正文给正反例：与其说”代码要规范”，不如给一段”该这样写 / 不该这样写”的对照，AI 照着抄。
• 规则纳入版本管理：.cursor/rules/ 提交进 Git，团队共享同一套约定。

一个好用的起步结构：

.cursor/rules/
  00-global.mdc      # Always：技术栈、语言、总禁用项
  react.mdc          # Auto Attached：globs: **/*.tsx
  api.mdc            # Auto Attached：globs: src/api/**
  testing.mdc        # Auto Attached：globs: **/*.test.ts
  release.mdc        # Manual：发布前手动 @

怎么验证规则真的生效了

写完规则别假设它在工作，验一下：

1. 在 Settings → Rules 里确认规则被识别、Rule Type 显示正确。
2. 打开一个匹配 glob 的文件，发一个会触发该规约的请求，看 AI 是否遵守。
3. 故意写一段违反规则的代码让它改，看它会不会按规约纠正。
4. 看请求的上下文里规则是否被引用（Cursor 部分版本会显示已应用的 rules）。

如果规则没生效，优先排查：glob 写错（路径没匹配上）、alwaysApply 字段拼错、规则正文太模糊 AI 没法执行。

几个我踩过的具体坑，直接对号入座：

• glob 路径基准搞混：globs 是相对项目根目录写的，很多人习惯性写成相对当前文件的相对路径，结果一条都匹配不上。写完先在 Settings → Rules 里点开这条规则，看它列出来命中了哪些文件，别靠猜。
• 一个 glob 写太宽：比如图省事写 **/*.ts，本意是想管 API 层，结果把测试文件、类型声明文件全牵连进去，AI 拿着 API 规约去改测试代码。宁可多写几条精确的 glob（src/api/**/*.ts、src/api/**/*.test.ts 分开），也别图一条包打天下。
• alwaysApply 和 globs 同时配错优先级：alwaysApply: true 时 globs 字段会被忽略，如果你想要的其实是”只在某类文件生效”，记得把 alwaysApply 改成 false，不然规则会变成不分场合的全局注入，效果跟 Always 一样，但你以为它是按需触发的。
• description 写得太笼统：Agent Requested 规则靠这句话被检索到，写”项目规范""代码约定”这种空话，AI 大概率检索不到、也就用不上。要写成”这条规则适用于……场景，用于约束……”，越具体越容易被命中。

从旧 .cursorrules 迁移的三步实操

如果你手上已经有一份几十上百行的老 .cursorrules，别整段复制粘贴进一个新文件，那等于白迁移。按这个顺序拆：

1. 先按”关注点”切段落：把老文件通读一遍，用高亮标出哪几段是讲前端组件的、哪几段讲 API、哪几段讲测试、哪几段是纯项目背景（技术栈、语言这类）。这一步不写代码，先在脑子里（或者一张草稿纸上）分好类。
2. 背景类进 Always，其余按目录/文件类型拆 Auto Attached：技术栈、语言、总禁用项这几条通常十条以内，放进 00-global.mdc 并设 alwaysApply: true；其余每个关注点开一个新文件，配上对应的 globs，比如组件规约配 globs: src/components/**/*.tsx。
3. 低频内容降级成 Manual 或 Agent Requested：像”发布前 checklist""某次专项重构的临时约定”这种不是每天都用得上的，别硬塞进 Always 或 Auto Attached，配成 Manual（不设 alwaysApply、不设 globs），需要时手动 @ 出来；如果是”偶尔用得上但希望 AI 自己判断”的，就写清楚 description 走 Agent Requested。

拆完之后删掉老的 .cursorrules（或者留一行注释指向新目录），避免两套规则同时生效造成冲突。整个过程建议一次只迁一个项目练熟，再推广到团队其他仓库，别指望一次性写出完美的拆分方案——规则和代码一样，是需要迭代打磨的。

常见问题

.cursorrules 还能用吗？ 还能用，Cursor 保留了向后兼容。但它正被渐渐弃用，官方主推 .cursor/rules/。新项目建议直接用新写法，老项目可以慢慢迁。

.mdc 和普通 .md 有什么区别？ .mdc 是带 frontmatter 的 Markdown，多出顶部 --- 之间的元信息（description / globs / alwaysApply），用来控制规则的触发方式。正文部分和普通 Markdown 一样。

Always 规则会不会太占上下文？ 会，所以要克制。Always 每次都注入，写太多会挤占其他上下文、稀释注意力。只把真正全局的铁律放 Always，其余下放成 Auto Attached，按需触发。

一个项目能放几条规则？最多多少？ 没有硬性”必须几条”的说法，具体上限以官方文档为准。实践上是宁可多拆小，不要少而臃肿——十几个各管一摊的小规则，比一个大文件好用得多。

团队怎么共享这些规则？ 把 .cursor/rules/ 目录提交进 Git 即可，所有人 clone 后自动拥有同一套约定。这也是相比写在个人配置里的优势——规则跟着仓库走。

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。