Cursor Rules 怎么写:项目规则、.mdc 格式、AGENTS.md 与团队规则
Cursor Rules 是给 Agent 的持久指令。本文按官方文档讲解 .cursor/rules 的 .mdc 格式、alwaysApply 与 globs 四种触发方式、AGENTS.md、团队规则优先级和规则不生效的排查。
Cursor Rules 是写给 Cursor Agent 的持久指令:规则被应用时,内容会放在模型上下文的开头,让 Agent 在每次对话里都遵守同样的约定。项目规则放在 .cursor/rules 目录,必须用 .mdc 扩展名并带 frontmatter;只想写一份简单说明时,可以在项目根目录放一个 AGENTS.md。下面按官方文档把四类规则、触发方式和写法讲清楚,帮你判断该把一条要求放在哪里。
先理解规则解决什么问题
Cursor 官方文档开头就说明了原因:大语言模型在两次补全之间不会保留记忆,规则就是在提示层面提供持久、可复用的上下文。你每次都要提醒 Agent 的事情,比如“组件用具名导出”“不要改 dist 目录”“迁移必须能回滚”,适合写成规则。
规则只影响 Agent(Chat)。官方 FAQ 写明,规则不会影响 Cursor Tab 或其他 AI 功能。如果你发现自动补全没有遵守规则,这是预期行为,不是规则没生效。
四类规则分别放在哪里
官方把规则分成四类。项目规则存放在 .cursor/rules,随代码一起进版本控制,作用范围是当前代码库。用户规则在 Customize 的 Rules 里设置,对你所有项目生效,适合写回答风格这类个人偏好。团队规则在 Cursor 控制台统一管理,只在 Team 和 Enterprise 计划可用。AGENTS.md 是纯 Markdown 文件,是项目规则的简化替代方案。
判断标准很直接:和这个代码库有关、希望同事也遵守的,写成项目规则或 AGENTS.md;只和你个人习惯有关的,写进用户规则;公司层面必须统一的要求,由管理员写成团队规则。
.mdc 文件格式和四种触发方式
项目规则的每个文件都是带 frontmatter 的 Markdown,扩展名必须是 .mdc。官方特别提醒,放在 .cursor/rules 里的普通 .md 文件会被规则系统忽略,因为它没有 frontmatter 来指定 description、globs 和 alwaysApply。你可以用子文件夹组织规则,比如 frontend/components.mdc。
frontmatter 里的三个字段决定规则何时进入上下文。alwaysApply 为 true 时,规则在每次对话都生效,此时 globs 和 description 都会被忽略。alwaysApply 为 false 且填写了 globs 时,只要匹配的文件出现在上下文中就自动附加。alwaysApply 为 false、只写 description 不写 globs 时,由 Agent 读取描述并在它认为相关时引入。三个都不写时,只有你在聊天里用 @规则名 手动提及才会生效。界面上对应的名字分别是 Always Apply、Apply to Specific Files、Apply Intelligently 和 Apply Manually。
这四种方式的取舍在于上下文成本和可靠性。每条 Always Apply 规则都会占用每次对话的上下文,适合放少量真正全局的约束。按 globs 触发最可控,适合“src/components 下的 tsx 文件”这类明确范围。按描述触发依赖 Agent 判断,描述要写得具体,否则可能不被调用。手动触发适合偶尔使用的模板或流程。
globs 写法示例
globs 用来把规则限定到特定文件或目录,多个模式用逗号分隔。官方给出的例子包括:**/*.ts 匹配任意目录下的 ts 文件,src/** 匹配 src 下的所有文件,src/**/*.tsx 匹配 src 下任意层级的 tsx 文件,docs/**/*.md, docs/**/*.mdx 同时匹配 docs 下的 md 和 mdx 文件,tailwind.config.* 匹配任意扩展名的 tailwind 配置。
如果规则按文件生效却没有被应用,官方 FAQ 给的排查方向是:确认 globs 能匹配到当前上下文里的文件;如果是按描述生效的规则,确认 description 已经填写。
在规则里引用文件
规则可以用 @service-template.ts 这种方式提到文件。官方说明,被提到的文件不会被直接塞进提示,而是告诉 Agent 去哪里找,需要时它会用工具读取,编辑器、CLI 和 Cloud Agents 都是这样处理。所以必须每次都在上下文里的内容,要直接写进规则正文;只是参考用的模板,用文件引用更好,因为代码变化时规则不会过时。
创建规则的两种方法
一种是在 Agent 聊天里输入 /create-rule,描述你想要的规则,Agent 会生成带正确 frontmatter 的文件并保存到 .cursor/rules。另一种是在侧边栏打开 Customize,进入 Rules,点击 Add Rule。Customize 里也能看到所有规则和它们的状态。
AGENTS.md 什么时候更合适
AGENTS.md 没有元数据,就是一份可读的 Markdown 说明,适合不需要复杂触发条件的项目。Cursor 支持把它放在项目根目录和任意子目录。子目录里的 AGENTS.md 会在处理该目录及其子目录的文件时自动应用,并与上级目录的说明合并,越具体的说明优先级越高。
一个实用的分工是:通用约定写在根目录 AGENTS.md,前端和后端的差异写在各自目录的 AGENTS.md;需要按文件类型精确触发或手动调用的流程,再写成 .mdc 项目规则。
团队规则和优先级
团队规则是自由文本,不使用项目规则的目录结构,但支持 glob 模式;不设 glob 的团队规则会应用到每次对话。管理员可以选择创建后立即启用,也可以先存为草稿;勾选强制执行后,成员无法在 Customize 里关闭它,未强制的团队规则成员可以自行关闭。
多种规则同时存在时,官方给出的顺序是团队规则、项目规则、用户规则。所有适用的规则会合并,指令冲突时排在前面的来源优先。官方也提醒,AI 指引不应该是你唯一的安全控制手段,合规要求仍然需要代码审查和其他机制兜底。
写好规则的判断标准
官方最佳实践建议:单条规则控制在 500 行以内,大规则拆成多个可组合的小规则,给出具体示例或引用文件,像写内部文档一样清楚,避免空泛指令。也有明确的反例:不要把整份代码风格指南复制进去,用 linter 处理;不要罗列 npm、git、pytest 这类常用命令;不要为很少发生的边缘情况写规则;不要复制代码库里已有的内容。
最省事的起点是先不写,等你发现 Agent 反复犯同一个错误时再加一条规则,并把规则提交到 git,让整个团队受益。
Cursor Rules 用 .md 还是 .mdc
.cursor/rules 目录里的项目规则必须用 .mdc,普通 .md 会被忽略。想写纯 Markdown 就用 AGENTS.md。
规则为什么没有生效
先看规则类型:按描述触发的要填写 description,按文件触发的要确认 globs 能匹配到上下文里的文件。另外规则只作用于 Agent,不影响 Cursor Tab。
团队规则和项目规则冲突听谁的
官方顺序是团队规则、项目规则、用户规则,冲突时前者优先。
AGENTS.md 可以放在子目录吗
可以。子目录里的 AGENTS.md 会在处理该目录下文件时应用,并和上级说明合并,更具体的说明优先。
