这个教程解决什么问题

每个新会话都要重复交代一遍项目约定——“我们用 pnpm 不用 npm""组件一律函数式""错误统一走 AppError”——说多了烦，忘了说就返工。Rules 就是把这些约定写成文件，让 Cursor 每次对话自动带着走。这篇按”全局偏好 → 项目规则 → 触发方式 → 写法打磨”的顺序，给你一套能直接抄进仓库的配置实践。

环境与机制速览

Cursor 的规则分两级，各管一摊：

级别位置作用范围
User RulesSettings 里的 Rules 设置项你的所有项目，全局生效
Project Rules仓库内 .cursor/rules/ 目录只作用于该项目，随 git 共享

早期社区通行做法是在项目根放一个 .cursorrules 文件；现在官方主推 .cursor/rules/ 目录结构，旧文件仍被兼容读取，但建议尽早迁移。版本号在 Help → About 查看【待补：你的 Cursor 实际版本号】。

第一级：User Rules，写跨项目偏好

在 Settings 的 Rules 设置项里用自然语言写，适合放”对任何项目都成立”的偏好：

- 始终用中文回复和解释代码
- 修改前先给方案，确认后再动手
- 不确定的 API 直接问我，禁止编造不存在的函数
- 生成的代码补上必要注释

注意 User Rules 是全局的：别把某个项目特有的约定写进来，否则换项目时它会拿错误的上下文污染对话。项目特有的事，交给下一级。

第二级：Project Rules，随仓库走

项目根建 .cursor/rules/ 目录，一个关注点一个 .mdc 文件：

.cursor/
└── rules/
    ├── general.mdc        # 全项目通用约定，always 生效
    ├── python.mdc         # 只对后端 Python 文件生效
    └── frontend.mdc       # 只对前端文件生效

每个 .mdc 文件用 frontmatter 声明何时生效，正文写具体指令。一个可直接抄的后端示例：

---
description: 后端 Python 代码规范
globs:
  - "app/**/*.py"
alwaysApply: false
---

- 数据库操作统一走 app/db/session.py 的 get_session()，禁止直接建连接
- 业务异常抛 app/errors.py 定义的 AppError 子类，禁止裸抛 Exception
- 新增接口必须带 pytest 用例，命名 test_<函数名>
- 提交信息格式：类型: 中文摘要（如 feat: 增加订单导出）

全项目都要生效的约定（提交规范、目录结构说明）单独放一个文件，alwaysApply 置为 true、globs 留空。建议单条规则十行上下、1 KB 以内（经验口径），长了必然没人遵守，模型也一样。

四种触发方式怎么选

frontmatter 的写法决定规则何时注入对话：

frontmatter 写法行为适合放什么
alwaysApply: true每次对话都注入提交规范、架构总览
globs: ["app/**/*.py"]命中对应文件时自动注入各技术栈的编码规范
只写 description模型判断相关时自行取用大块头的架构与领域说明
都不写仅手动 @ 引用时生效偶尔才用的流程说明

判断标准一句话：这个约定是不是只在碰到某类文件时才有意义。是，就用 globs；不是，才考虑 always。所有 always 规则都会进每一次请求的上下文，体积直接换算成额度和注意力成本——多份 always 规则叠加到 50 KB（示例规模，发布前替换为你的实测）这个量级时，模型对每条规则的服从度会肉眼可见地下降。

写规则的实践：像写代码规范一样写

写”必须做什么”，不写”不要写烂代码”。 “代码要简洁”是废话，模型无从执行；“禁止超过 3 层嵌套，超出必须提取函数”才是一条规则。

一条管一件事，超出就拆文件。 按关注点拆分，命名即文档：python.mdc、frontend.mdc、git.mdc。

长文档用 @file 引用。 已有的详细设计文档不必塞进规则，规则里写摘要加 @docs/architecture.md 引用，模型需要时自己去读。

子目录可以有独立规则。 大仓里在子包下再建 .cursor/rules/，只管那棵子树，monorepo 友好。

AI 能帮你起稿，但你必须修剪。 对话里可以让模型根据当前项目生成规则草稿，但生成物往往又长又虚，逐条删到只剩可验证的指令为止。

常见坑与解法

坑 1：新旧机制并存，团队改错了文件

仓库根还留着 .cursorrules，有人往新目录加规则，有人还在改旧文件，两边说法还不一致。处理：把旧文件内容合并进 .cursor/rules/general.mdc，删掉旧文件（git 历史随时可找回），在 README 写明”改规则请去 rules 目录”。

坑 2：globs 写错，规则永远不触发

globs 匹配的是相对仓库根的路径，用正斜杠 /，Windows 上写反斜杠不生效；*.py 只匹配根目录，子目录要写 **/*.py。验证方法：让 Cursor 新建一个命中路径的文件并故意违反一条规则，看它是否自我纠正。

坑 3：规则写成感想散文

“我们团队注重代码质量和可维护性”这类句子没有信息量。每条规则改写成编号指令：动词开头、有明确对象、能判断违反与否。

坑 4：两条规则打架

frontend.mdc 说样式用方案 A，legacy.mdc 说用方案 B，模型只能随机站队。拆分时给每个文件划清管辖边界，同一类文件只归一条规则管；实在重叠，在 description 里写清优先关系。

最终效果与验证

配置完成后做一次验收：新开对话，让它在项目里新增一个符合规范的接口，检查三件事——是否主动用了 get_session()、是否带了 pytest 用例、给出的提交信息是否符合格式。三个都对，规则就算立住了；有偏差，回头检查对应规则是不是被写成了散文。

Cursor Rules 生效前后生成结果对比

【待补：规则生效前后生成结果对比截图】

高频问答

  • 规则会消耗额度吗：会。always 类规则随每次请求发送，token 计入上下文，所以只放真正的全局约定；
  • 团队怎么共享：.cursor/rules/ 随 git 提交，全组自动统一；User Rules 是个人的，不进仓库；
  • 和 CLAUDE.md、AGENTS.md 这类文件什么关系：都是”给 AI 的项目说明书”，思路相通，内容可以互相搬运，但文件位置和语法不通用，别混着放；
  • 规则越多越好吗：不是。总量超过模型上下文的一定比例（示例阈值，发布前按官方当期建议修正）后服从度下降，宁少而精；
  • 官方对规则长度的建议是多少：以官方文档当期口径为准【待补：当期建议数字】。

相关阅读