# Cursor Rules 是什么？怎么写

> Cursor 规则（Rules）是存下来的指令，Agent 在每次对话开始时读取，你不用一遍遍重复交代。随代码一起提交的那种，是 `.cursor/rules` 里的 `.mdc` 文件。文件开头几行元数据决定它怎么生效：始终生效、匹配文件时生效、Agent 觉得相关时生效，或者只在你点名时生效。

Mindket 编辑部 · 发布于 2026-11-03 · 更新于 2026-11-03 · https://mindket.com/cn/blog/cursor-rules

## 要点

- 规则文件的扩展名用 `.mdc`，别用 `.md`，写好后和代码一起提交。
- 旧的 `.cursorrules` 文件，趁 Cursor 还没弃用，改成一条 Always Apply 规则。
- 公开仓库里的规则，照抄前先读一遍：它会左右 Agent 在你项目里的行为。

## 创建一条规则

最快的办法是在 Agent 对话里输入 `/create-rule`，说清这条规则要管什么，Agent 会写好带正确元数据的文件，存进 `.cursor/rules`。在 Customize 里打开 Rules，点 Add Rule，建出来的是同一种文件。想每个字段都自己定，就走命令面板：

1. 按 Ctrl+Shift+P（Mac 上是 Cmd+Shift+P）打开命令面板，运行“New Cursor Rule”。
2. 给它起个名字，一个名字只管一件事，比如 `react-patterns` 或 `api-validation`。
3. 用纯 markdown 写说明，开头先写几行短的就行。
4. 从下拉菜单里选类型。选 Apply to Specific Files，就再写匹配模式，比如 `*.tsx`。选 Apply Intelligently，就写好描述。
5. 保存。文件会落在 `.cursor/rules/` 里，可以直接提交。

[![eric zakariasson（@ericzakariasson）2025 年 4 月 18 日在 X 上的帖子。在一条介绍 Cursor 0.49 发布的串里，他说现在可以用 /Generate Cursor Rules 命令从对话生成规则，是把来回聊天里的决定记下来、以后复用的好办法](https://mindket.com/blog/shots/x-ericzakariasson-generate-cursor-rules.webp?v=48c04ae8019e)](https://x.com/ericzakariasson/status/1913291812762210454)

eric zakariasson 在 X 上，2025 年 4 月 18 日

> Cursor 的帮助页建议 `.cursor/rules` 用扁平的文件夹，更好管理，参考页的示例却把规则分进了子文件夹，两种都能用。截图是 X 官方嵌入的一条回复和它上面的帖子，发于 2025 年 4 月，那时 Cursor 0.49 管生成规则的命令叫“/Generate Cursor Rules”，文档现在写的是 `/create-rule`。

## 项目规则的四种生效方式

在下拉菜单里选的类型，会存成 `.mdc` 文件开头的一小段元数据（frontmatter），共三个字段：`alwaysApply`、`description` 和 `globs`。

Always Apply 的规则每次对话都会加载，旁边即使写了 globs 和描述，Cursor 也不看。按文件生效的规则，要等匹配 `globs` 模式的文件进了上下文才加载。Apply Intelligently 交给 Agent 读描述，由它判断和手头的任务相不相关。手动规则则要你在对话里输入 `@` 加规则名，才起作用。

生效的规则会放在[模型上下文的开头](https://cursor.com/docs/rules)。常驻规则每次对话都要消耗 token，在 Cursor 的[环形图](https://cursor.com/docs/agent/prompting)里和技能、MCP 各占一块，规则一多，[开销就上去了](https://cursor.com/learn/customizing-agents)。测试命令这类每个任务都要的几行，才值得设成 `alwaysApply: true`。`react-patterns` 之类的规则用 `*.tsx` 模式限定，相关文件进入上下文时再加载。

## 规则里该写什么，附一条可以照抄的示例

Cursor 的[最佳实践文章](https://cursor.com/blog/agent-best-practices)建议，先一条规则都不写，等 Agent 同一个错犯了不止一次再加。假设它在 API 处理函数里总是直接抛出字符串，下面这条示例规则要求它改用 `{ code, message }` 错误对象。

文件存为 `.cursor/rules/api-handlers.mdc`。想让它在每次对话里都生效，把 `alwaysApply` 设成 `true`。

规则是写进提示词的持久上下文，不会在代码里执行检查，同样的错仍可能出现。出现时，先确认规则有没有加载，再改写 Agent 忽略的那一句。也可以在 GitHub 的 issue 或拉取请求里 @cursor，让 Agent 来改。涉及安全的部分，Cursor 的文档提醒不要只靠 AI 的指引把关。

````markdown
---
globs: src/api/**/*.ts
alwaysApply: false
---

- Validate every request body with the zod schema in `src/api/schemas/` before it reaches a service.
- Return errors as `{ code, message }` objects from `src/lib/errors.ts`. Never throw a raw string.
- Put a test beside each handler. Copy the layout of @src/api/handlers/users.test.ts.
- Never edit `src/generated/`. Change the schema and run `npm run generate`.

````

- Cursor 自己列过哪些不必写，头一条就是整本风格指南。那是 linter 的事，常见的编码规范 Agent 本来就懂。
- 不必把命令列全。npm、git、pytest 这些 Agent 都认识，只写你们项目自己的。
- 很少碰到的边缘情况，也省掉。
- 仓库里已有的代码别再贴一遍，指向一个典型的例子就好。

## 规则不生效时怎么查

先看扩展名。`.cursor/rules` 里的 `.md` 文件没有元数据，Cursor 会直接跳过，改成 `.mdc` 才会生效。扩展名没错，就检查规则的类型设置：

- 类型是 Apply Intelligently，描述却空着。Agent 只凭这一句判断相关不相关，所以要写清规则在什么情况下有用，而不是规则里写了什么。
- 类型是 Apply to Specific Files，模式没匹配上。拿一条 Agent 正在处理的真实路径去核对。`*.ts` 匹配不到任何子文件夹里的文件。
- 类型是 Apply Manually。不在对话里输入 `@` 和规则名，它就一直不起作用。

## Cursor 规则和 AGENTS.md、CLAUDE.md、技能的区别

AGENTS.md 可以看成不带元数据、也不分类型的规则，就是一份纯 markdown。Cursor 会读项目根目录和各级子文件夹里的 AGENTS.md，嵌套文件的内容和上一级合并，冲突时以更具体的为准。

Claude Code 用的 [CLAUDE.md](https://mindket.com/cn/blog/claude-md-file)，Cursor 也会读，而且不管 `alwaysApply` 怎么设，每次对话都带上它。

从 2.1.277 版起，工作文件夹及其上级都没有 CLAUDE.md 时，[Claude Code 会改读 AGENTS.md](https://code.claude.com/docs/en/memory)。已有 CLAUDE.md 的，在里面写一行 `@AGENTS.md` 引入它，两个工具就共用一份 AGENTS.md。只有需要 glob、描述或手动开关的说明，才单独写成 `.cursor/rules` 里的规则。

[技能](https://mindket.com/cn/blog/what-are-agent-skills)平时不加载。描述和任务对得上，或者你输入 `/技能名`，Agent 才去读。照 2.4 版[更新日志](https://cursor.com/changelog/2-4)的建议，随任务变化的上下文和操作步骤，放进技能比写成常驻规则合适。现成的规则能用 `/migrate-to-skills` 转成技能，但只限 Apply Intelligently 类型。给 Claude Code 或 Codex 准备的技能文件夹不用再复制一份，Cursor [能直接读](https://cursor.com/docs/skills)。

> **什么时候规则该改成技能**
>
> 规则要少而精，质量要高。它们应该是团队不断更新的共同成果。如果只是偶尔才需要某件事，就把它放进技能里。原文为英文。
>
> Cursor Learn, [Cursor Learn：自定义智能体](https://cursor.com/learn/customizing-agents) (2026-11-03 查阅)

|  | 项目规则 | AGENTS.md 或 CLAUDE.md | 技能 |
| --- | --- | --- | --- |
| 文件 | `.cursor/rules/name.mdc`，带元数据 | `AGENTS.md` 或 `CLAUDE.md`，纯 markdown | `.cursor/skills/name/SKILL.md`，带 `name` 和 `description` |
| 生效方式 | 始终、按文件模式、按描述或按点名 | 从项目根目录自动读取。嵌套的 AGENTS.md 管它所在的文件夹。CLAUDE.md 用于每一次对话 | Agent 按描述挑选，或你输入 `/名称`。可选的 `paths` 字段把它限定在匹配的文件 |
| 适合 | 简短的准则和约束 | 简单、易读的说明 | 多步骤的工作流和流程 |

**哪个工具读哪种说明文件**

| | Cursor | Claude Code | Codex |
| --- | --- | --- | --- |
| `AGENTS.md` | ✓ 是 | ◐ 部分 | ✓ 是 |
| `CLAUDE.md` | ✓ 是 | ✓ 是 | ◐ 部分 |
| 带 `SKILL.md` 的技能文件夹 | ✓ 是 | ✓ 是 | ✓ 是 |

来源：[Cursor 文档：规则](https://cursor.com/docs/rules) (2026-11-03 查阅)；[Cursor 帮助页：规则](https://cursor.com/help/customization/rules) (2026-11-03 查阅)；[Cursor 文档：Agent Skills](https://cursor.com/docs/skills) (2026-11-03 查阅)；[Claude Code 文档：Claude 如何记住你的项目](https://code.claude.com/docs/en/memory) (2026-11-03 查阅)；[Claude Code 文档：用技能扩展 Claude](https://code.claude.com/docs/en/skills) (2026-11-03 查阅)；[ChatGPT Learn：用 AGENTS.md 自定义指令](https://learn.chatgpt.com/docs/agent-configuration/agents-md) (2026-11-03 查阅)；[ChatGPT Learn：构建技能](https://learn.chatgpt.com/docs/build-skills) (2026-11-03 查阅)

[![Cursor（@cursor_ai）2026 年 1 月 23 日在 X 上的帖子：Agent Skills 现已在 Cursor 中推出，技能让智能体能发现并运行专门的提示词和代码](https://mindket.com/blog/shots/x-cursorai-agent-skills.webp?v=4c607ce97c0b)](https://x.com/cursor_ai/status/2014753596223770841)

Cursor 在 X 上，2026 年 1 月 23 日

> Codex 只有在你把 `CLAUDE.md` 这个名字写进 `project_doc_fallback_filenames` 时才读它。截图里的 Cursor 帖子去掉了视频。

## 项目规则、用户规则、团队规则：谁能用到哪种

同一次对话里，管理员定的团队规则、仓库里的项目规则和你自己的用户规则可能同时生效。说法不一致时，Cursor 把生效的规则合并，排在前面的优先：先团队，再项目，最后才是用户。

不同文件夹里的两条规则即使文件名相同，也不会冲突。Cursor 靠完整路径区分规则，条件满足时两条都会生效。

**规则在 Cursor 里是怎样成形的**

1. **2025年1月23日** 规则搬进 `.cursor/rules`。0.45 版允许把多条仓库级规则写到这个文件夹里，由 Agent 自己选择该遵守哪一条。
2. **2025年4月15日** 从对话生成规则。0.49 版加入一个命令，能从对话生成规则。带路径模式的规则，在 Agent 读写匹配的文件时会自动生效。
3. **2025年9月29日** 团队规则。1.7 版让团队可以在控制台里定义规则，应用到团队的所有项目。
4. **2026年1月22日** 技能。2.4 版加入 Agent Skills，任务对得上时，智能体可以发现并使用它们。
5. **2026年2月17日** 插件带上规则。2.5 版加入插件，把技能、子智能体、MCP 服务器、钩子和规则打包成一次安装。

来源：[Cursor 更新日志 0.45.x](https://cursor.com/changelog/0-45-x) (2026-11-03 查阅)；[Cursor 更新日志 0.49](https://cursor.com/changelog/0-49) (2026-11-03 查阅)；[Cursor 更新日志 1.7](https://cursor.com/changelog/1-7) (2026-11-03 查阅)；[Cursor 更新日志 2.4](https://cursor.com/changelog/2-4) (2026-11-03 查阅)；[Cursor 更新日志 2.5](https://cursor.com/changelog/2-5) (2026-11-03 查阅)

| 种类 | 存放位置 | 谁能用到 |
| --- | --- | --- |
| 项目规则 | 仓库里的 `.cursor/rules/*.mdc` | 文件提交之后，每个拉取仓库的人都有。 |
| 用户规则 | Customize 里的 Rules，存在你的 Cursor 账号上 | 你本人，所有项目都生效。换一台机器登录就会同步。 |
| 用户规则文件 | `~/.cursor/rules`（Windows 上是 `%USERPROFILE%\.cursor\rules`） | 你本人，只在这台机器上，不会同步。 |
| 团队规则 | Cursor 控制台，需要 Team 或 Enterprise 套餐 | 团队里的每个成员。管理员可以强制启用，成员就关不掉。 |
| AGENTS.md | 项目根目录和各级子文件夹 | 纯 markdown，没有元数据。嵌套的文件会叠加在上一级的内容之上。 |

> 项目根目录里的旧文件 `.cursorrules` 已是遗留写法，Cursor 的[帮助页](https://cursor.com/help/customization/rules)说它将被弃用。迁移的办法是：新建一条规则，把旧文件的内容粘进去，类型选 Always Apply，这和旧行为一致，再删掉 `.cursorrules`。

## 和团队或其他项目共享规则

别的 GitHub 仓库里的规则，不会自己导入。Cursor 给的办法是打包成[插件](https://cursor.com/docs/plugins)：`.mdc` 文件放进插件的 `rules/` 文件夹，再通过插件市场发布。只要仓库里有 `.cursor-plugin/marketplace.json`，在 Customize 里选 From GitHub Repository 就能导入。

也有人把规则放进公开仓库。11 月 3 日在 GitHub 的[仓库搜索](https://github.com/search?q=cursorrules&type=repositories&s=stars&o=desc)里搜“cursorrules”并按星标排序，第一名是 `PatrickJS/awesome-cursorrules`，第二名是 `grapeot/devin.cursorrules`。

**GitHub 上搜“cursorrules”排前两名的仓库的星标数**

- **41,092** 颗星标：`PatrickJS/awesome-cursorrules`，一个给 Cursor 用的配置文件合集 (来源：[GitHub 仓库：PatrickJS/awesome-cursorrules](https://github.com/PatrickJS/awesome-cursorrules), 2026-11-03 查阅)
- **5,956** 颗星标：`grapeot/devin.cursorrules`，一套给 Cursor 和 Windsurf 用的规则 (来源：[GitHub 仓库：grapeot/devin.cursorrules](https://github.com/grapeot/devin.cursorrules), 2026-11-03 查阅)

> 文中引用的页面都是我们 11 月 3 日读的。我们没有上手试过任何规则，上面的示例也没试过。

## 参考：每种规则类型的元数据，以及 glob 模式

`globs` 可以写多个模式，用逗号隔开，两个星号可以跨越文件夹：

````text
*.ts                           只匹配根目录里的 .ts 文件
**/*.ts                        任意文件夹里的 .ts 文件
src/**                         src 下的所有文件
docs/**/*.md, docs/**/*.mdx    两种扩展名，用逗号隔开
````

| 下拉菜单 | `alwaysApply` | `description` | `globs` | 结果 |
| --- | --- | --- | --- | --- |
| Always Apply | `true` | 忽略 | 忽略 | 每次对话都会带上。 |
| Apply to Specific Files | `false` | 不需要 | 写一个匹配模式 | 匹配的文件进入上下文时自动附加。 |
| Apply Intelligently | `false` | 写一句话 | 留空 | Agent 读描述，觉得合适就把规则拉进来。 |
| Apply Manually | `false` | 留空 | 留空 | 只有你用 @ 点名，例如 `@my-rule`，才会带上。 |

## 常见问题

### Cursor 规则能用在命令行版和云端 Agent 里吗？

能。[命令行版](https://cursor.com/docs/cli/using)用的规则系统和编辑器一样，还会读项目根目录里的 `AGENTS.md` 和 `CLAUDE.md`。Cursor 的[云端 Agent 指南](https://cursor.com/docs/cloud-agent/best-practices)说，这类 Agent 遵循三个层级的规则：用户规则、控制台里的团队规则，以及提交在仓库里的 `.mdc` 文件。

### Cursor 的一条规则最多能写多长？

Cursor 建议控制在 500 行以内，但这不是硬性上限。一条规则要是既管样式又管测试，最好拆成两个文件，各设各的类型和 glob。

### 一条规则能引用另一个文件吗？

只能指向它。在规则里写 `@service-template.ts`，是告诉 Agent 去哪里看，需要内容时 Agent 会用自己的工具打开这个文件。文件并不会被贴进提示词，所以每次都必须在上下文里的内容，要直接写进规则正文。

### Cursor 规则会影响 Tab 补全或 Bugbot 吗？

不会，规则只管 Agent 对话，Tab 补全和 Cursor 的其他 AI 功能都不受影响。[Bugbot](https://cursor.com/docs/bugbot) 审查拉取请求另有一套规则：Bugbot Automations 里的团队规则，加上仓库里的 `.cursor/BUGBOT.md` 文件。

## 资料来源

- [Cursor 文档：规则](https://cursor.com/docs/rules) (2026-11-03 查阅)
- [Cursor 帮助页：规则](https://cursor.com/help/customization/rules) (2026-11-03 查阅)
- [Cursor 文档：Agent Skills](https://cursor.com/docs/skills) (2026-11-03 查阅)
- [Cursor 帮助页：技能](https://cursor.com/help/customization/skills) (2026-11-03 查阅)
- [Cursor 文档：在命令行中使用 Agent](https://cursor.com/docs/cli/using) (2026-11-03 查阅)
- [Cursor 文档：插件](https://cursor.com/docs/plugins) (2026-11-03 查阅)
- [Cursor 文档：云端 Agent 最佳实践](https://cursor.com/docs/cloud-agent/best-practices) (2026-11-03 查阅)
- [Cursor 文档：给 Agent 写提示词](https://cursor.com/docs/agent/prompting) (2026-11-03 查阅)
- [Cursor 文档：Bugbot](https://cursor.com/docs/bugbot) (2026-11-03 查阅)
- [Cursor 博客：用智能体编程的最佳实践](https://cursor.com/blog/agent-best-practices) (2026-11-03 查阅)
- [Cursor Learn：自定义智能体](https://cursor.com/learn/customizing-agents) (2026-11-03 查阅)
- [Cursor 更新日志：2.4，子智能体、技能和图像生成](https://cursor.com/changelog/2-4) (2026-11-03 查阅)
- [Claude Code 文档：Claude 如何记住你的项目](https://code.claude.com/docs/en/memory) (2026-11-03 查阅)
- [Cursor 更新日志：0.45.x，.cursor/rules、更好的代码库理解、新的 Tab 模型](https://cursor.com/changelog/0-45-x) (2026-11-03 查阅)
- [Cursor 更新日志：0.49，规则生成、改进的 Agent 终端和 MCP 图片](https://cursor.com/changelog/0-49) (2026-11-03 查阅)
- [Cursor 更新日志：1.7，浏览器控制、规划模式和钩子](https://cursor.com/changelog/1-7) (2026-11-03 查阅)
- [Cursor 更新日志：2.5，插件、沙盒访问控制和异步子智能体](https://cursor.com/changelog/2-5) (2026-11-03 查阅)
- [Claude Code 文档：用技能扩展 Claude](https://code.claude.com/docs/en/skills) (2026-11-03 查阅)
- [ChatGPT Learn：用 AGENTS.md 自定义指令](https://learn.chatgpt.com/docs/agent-configuration/agents-md) (2026-11-03 查阅)
- [ChatGPT Learn：构建技能](https://learn.chatgpt.com/docs/build-skills) (2026-11-03 查阅)
- [GitHub：按星标排序的 cursorrules 仓库搜索](https://github.com/search?q=cursorrules&type=repositories&s=stars&o=desc) (2026-11-03 查阅)
- [GitHub 仓库：PatrickJS/awesome-cursorrules](https://github.com/PatrickJS/awesome-cursorrules) (2026-11-03 查阅)
- [GitHub 仓库：grapeot/devin.cursorrules](https://github.com/grapeot/devin.cursorrules) (2026-11-03 查阅)
- [eric zakariasson 在 X 上：从对话生成规则](https://x.com/ericzakariasson/status/1913291812762210454) (2026-11-03 查阅)
- [Cursor 在 X 上：Agent Skills 现已在 Cursor 中推出](https://x.com/cursor_ai/status/2014753596223770841) (2026-11-03 查阅)

[浏览套件](https://mindket.com/cn/kits)