Cursor Rules 怎么写？.mdc 规则配置完全指南（2026）

用 Cursor 写代码久了，几乎每个人都会遇到同一个问题：明明只让它改一个函数，它顺手把周边代码重构了一遍；明明项目用的是 pnpm，它张口就是 npm install；明明约定好用具名导出，它每次都给你写 export default。这些不是模型笨，而是它根本不知道你的项目规矩。Cursor Rules 就是用来把「项目规矩」固化下来的机制——把规则写进 .cursor/rules 目录，Cursor 在合适的时机自动把它塞进上下文，AI 就不会每次都从零猜。这篇讲清 Cursor Rules 怎么写：目录结构、.mdc 文件的三个字段、四种触发方式、能直接抄的模板，以及 2026 年的新变化（Skills 迁移、旧版 .cursorrules 怎么办）。

Cursor Rules 是什么：给 AI 的常驻项目说明书

本质上，Rules 就是一段会被自动拼进提示词的文本。你写好一条规则，当它被触发时，Cursor 会把规则内容附加到你这次对话的上下文里，AI 读到之后再干活。它和你每次手动在聊天框里复制粘贴「记住：本项目用 TypeScript strict 模式、用 pnpm、组件放 src/components」的效果是一样的，区别只在于规则是持久化、可版本控制、可按文件类型自动生效的。

所以判断一条内容该不该写成规则，标准很简单：如果这件事你已经在聊天里重复说过三次以上，它就该进规则文件。反过来，只在这一次任务里成立的临时要求，直接在对话里说就行，别污染规则。

三种写法怎么选：项目规则 / 用户规则 / AGENTS.md

推荐组合：AGENTS.md 写「这个项目是什么、怎么跑起来、有哪些硬性约定」这类所有 AI 工具都该知道的通用信息；.cursor/rules 写需要按文件类型精确生效、或者需要 Cursor 特有触发机制的规则；User Rules 只写你的个人习惯。这样换工具的时候，AGENTS.md 那份资产不会作废——我们在 AGENTS.md 那篇文章里详细讲过这个跨工具标准。

.mdc 文件怎么写：三个字段决定一切

项目规则存放在 .cursor/rules 目录下，文件扩展名必须是 .mdc，普通的 .md 文件会被直接忽略——这是新手第一个大坑。.mdc 本身就是带 YAML frontmatter 的 Markdown，frontmatter 只有三个字段：

三个字段的不同组合，就构成了四种触发方式：

官方文档里给的最小示例长这样，注意 frontmatter 用三个减号包起来，正文就是普通 Markdown：

---
alwaysApply: true
---

- 所有源文件必须包含公司版权头
- 对实现细节没把握时，先读相关源文件再提改动方案
- 绝不修改 dist/ 或 build/ 目录下的生成文件

创建规则有两个入口：在 Agent 对话框里输入 /create-rule，或者从设置里走 Customize → Rules → Add Rule。当然直接在 .cursor/rules 目录手动新建一个 .mdc 文件也完全可以，Cursor 会自动扫描。

三个能直接抄的规则模板

下面三个是最常用、性价比最高的场景。按需改成你自己项目的实际情况即可。

第一个：项目基础约定（总是生效）。放 .cursor/rules/project.mdc：

---
alwaysApply: true
---

# 项目约定

- 包管理器用 pnpm，不要用 npm 或 yarn
- TypeScript strict 模式，禁止 any，不确定就用 unknown 再收窄
- 一律使用具名导出，不用 default export
- 新增组件放 src/components，页面放 src/app
- 不要主动重构我没让你改的代码
- 改动前先读相关文件，别凭猜测写

第二个：只在写 React 组件时生效（按文件匹配）。放 .cursor/rules/react.mdc：

---
description: React 组件编写规范
globs: src/components/**/*.tsx
---

- 组件用函数式写法 + TypeScript 接口定义 props
- 客户端组件必须在文件首行写 'use client'
- 样式只用 Tailwind 原子类，不写 CSS Module、不写内联 style
- 状态优先用 props 传递，跨层级才考虑全局 store
- 参考现有实现：src/components/ui/button.tsx

第三个：只在写数据库相关代码时按需加载（智能判断）。放 .cursor/rules/database.mdc：

---
description: 数据库 schema 改动、Prisma 迁移、SQL 查询相关的规范
---

- 改 schema.prisma 后必须生成迁移文件，不要直接 db push 到生产
- 查询一律走 src/lib/prisma.ts 导出的单例，不要新建 PrismaClient
- 列表查询必须带分页，禁止无条件 findMany
- 涉及多表写入用 $transaction 包起来

旧版 .cursorrules 还能用吗

能用，但不建议继续用。.cursorrules 是放在项目根目录的单个纯文本文件，是 Cursor 早期的规则格式，2024 年底起官方转向 .cursor/rules 目录，不过至今仍然兼容读取，所以老项目不会突然崩。

问题在于它的能力被冻结了：单文件无条件全量加载，没有 globs 作用域、没有触发模式、也没有 Agent 智能判断，不管你这次是在改样式还是在写迁移脚本，整份规则都要占掉一块上下文。Cursor 后来加的所有规则能力都只在 .mdc 上生效。迁移成本其实很低——把原来那个文件的内容按主题拆成几份，加上 frontmatter，扔进 .cursor/rules 就完事了。

2026 新变化：Skills 与 /migrate-to-skills

2026 年 Cursor 支持了 Skills（技能）机制——这套东西最早由 Claude Code 推起来，现在成了跨工具的事实标准。Skill 是一个文件夹，里面放一个 SKILL.md，描述「什么时候用这个技能、用了之后按什么流程干活」，比规则更像一份可复用的操作手册。

Cursor 启动时会自动扫描这些目录加载技能：

• 项目级：.cursor/skills/ 和 .agents/skills/
• 用户级（全局）：~/.cursor/skills/ 和 ~/.agents/skills/
• 兼容目录：.claude/skills/、.codex/skills/ 以及对应的家目录版本

注意最后一条：Cursor 会读 .claude/skills/。也就是说你为 Claude Code 写的技能，Cursor 能直接复用，反过来也一样，这对同时用多个工具的人是实打实的便利。

官方还内置了一个 /migrate-to-skills 命令，可以把现有规则和斜杠命令转成技能。但它有明确的边界：带 alwaysApply: true 或者带具体 globs 的规则不会被迁移，因为这两类有明确的触发条件，和技能的按需调用逻辑不是一回事。

官方给的写规则最佳实践

• 单条规则控制在 500 行以内，超了就拆
• 一条规则只管一件事，拆成多个可组合的小规则，别搞一个巨型文件
• 给具体例子或引用项目里的真实文件，别只写抽象原则
• 用祈使句写：「一律使用具名导出」比「具名导出是更好的选择」有效得多
• 指向项目里的标准实现，而不是把代码复制进规则——复制的代码会过期，指路不会
• 别把整份团队代码规范原样粘进去，也别把所有可用命令列一遍，那只会烧掉上下文

最后这条尤其重要。规则不是越多越好，每一条都在占用上下文预算。真正有效的规则集通常出奇地短：一份 30 行的 alwaysApply 基础约定，加上两三份按 globs 生效的专项规则，覆盖率就足够高了。

规则不生效？按这个顺序排查

1. 1文件扩展名是不是 .mdc？写成 .md 会被静默忽略，这是最常见的原因
2. 2文件是不是在 .cursor/rules 目录下？放错目录不会有任何报错提示
3. 3frontmatter 的三个减号是不是写全了、位置是不是在文件最开头？格式错了整个 frontmatter 会失效
4. 4如果依赖 globs：模式写对了吗？注意用 src/*/.tsx 这种相对项目根的写法，别写绝对路径
5. 5如果依赖 description 智能触发：描述是不是太笼统？写清楚「什么场景下该用」，Agent 才判断得准
6. 6确认一下是不是用了旧的 .cursorrules 单文件，如果是，迁到 .mdc 再试

写好 Rules 之后你会发现，AI 编程的效率瓶颈很少在模型能力上，更多在于你有没有把项目上下文准确、经济地喂给它——这正是上下文工程要解决的问题。规则文件、AGENTS.md、Skills 都是这套方法论的具体载体。想系统学习怎么用 Cursor、Claude Code 这类工具真正做出可交付的产品，而不是停留在「能跑就行」，欢迎来 IMAI 看看我们的体系化实战课程。