你在规则里写了 use 4-space indent, never use any，结果 Cursor 的 Agent 给出来的代码还是 2-space、满是 any。问它 “what rules do you see?”，它说没有规则。
截至 2026 年 6 月，最常见的原因是格式问题。Cursor 早在 0.43 就弃用了单文件的旧版 .cursorrules，而在 Cursor 2.x 里 Agent 根本不读 .cursorrules——它只认更新的 Project Rules，也就是 .cursor/rules/ 目录下的 .mdc 文件。所以一个”去年还能用”的 .cursorrules，在某次升级之后可能就悄悄失效了。
最快修法：把规则挪进 .cursor/rules/style.mdc，写好 frontmatter（alwaysApply: true），然后到 Cursor Settings → Rules, Commands 确认它出现在列表里。列出来了就是加载成功；没出现就是 frontmatter 写错了。
你属于哪一种情况
| 现象 | 可能原因 | 跳转 |
|---|---|---|
规则在根目录 .cursorrules，Agent 无视 | 旧格式在 Agent 模式不被读取 | 原因 1 |
文件是 .cursor/rules/foo.md（不是 .mdc） | 扩展名错，被静默忽略 | 原因 2 |
.mdc 存在但 Settings → Rules 里没有 | frontmatter 缺失或有错，被静默丢弃 | 原因 2 |
| 规则在列表里但从不自动应用 | 没有 alwaysApply/globs 触发条件 | 原因 3 |
| 规则在大仓库的子目录里 | 作用域 / 位置不匹配 | 原因 4 |
| 本来能用，改完之后突然失效 | rules 缓存没刷新 | 原因 5 |
| 文件第一行乱码 / 解析失败 | UTF-8 BOM | 原因 6 |
git check-ignore 命中了该文件 | 被 .cursorignore 屏蔽 | 原因 7 |
常见原因
1. 还在用旧版 .cursorrules
.cursorrules（仓库根的单个文件）已被弃用。它在某些模式下还会被解析，但 Cursor 2.x 的 Agent 会直接忽略它——这是 Cursor 有意为之的改动，目的是让 Agent 只走带作用域的 Project Rules 系统。如果团队升级了 Cursor 之后规则悄悄失效，几乎一定是这个原因。
如何判断：你的规则在 .cursorrules 里，你用的是 Agent 模式，而 Cursor Settings → Rules, Commands 里没有列出它们。迁移到 .cursor/rules/*.mdc（见 Step 1）。
2. 扩展名错或 frontmatter 有问题
Project rules 必须是放在 .cursor/rules/ 目录里的 .mdc 文件。两个坑：
- 放在
.cursor/rules/里的普通.md文件会被规则系统忽略——因为它没有规则 frontmatter。 - 如果 YAML frontmatter 有任何错误，Cursor 会静默跳过该文件，没有警告、没有日志、没有弹窗。常见祸根：
- 缺少结尾的
---行。 globs写成了单个字符串，而不是数组。- YAML 区分大小写：
True不等于true，所以alwaysApply: True永远不会被加载。
- 缺少结尾的
如何判断：
ls .cursor/rules/
# 每个规则都必须以 .mdc 结尾，而不是 .md然后打开 Cursor Settings → Rules, Commands。如果磁盘上有这个 .mdc 文件，但这个面板里没有列出它，就说明 frontmatter 写坏了。
3. .mdc 规则没有触发条件
.mdc frontmatter 有三个字段决定规则何时生效。截至 2026 年 6 月，Cursor 把规则分成四种类型：
| 规则类型 | frontmatter | 何时应用 |
|---|---|---|
| Always | alwaysApply: true | 每次 chat / Agent 请求 |
| Auto Attached | alwaysApply: false + globs: [...] | 当编辑 / 附加的文件匹配某个 glob |
| Agent Requested | alwaysApply: false + description（无 globs） | Agent 根据 description 自行判断 |
| Manual | 以上都没有 | 只有你 @ 提及该规则时 |
只写了 description、既没 alwaysApply 也没 globs 的规则属于 Manual 类型——它永远不会自动注入，所以看起来像”没加载”，其实是要你 @ 提及才会生效。
如何判断：
---
description: Use 4-space indent
# 缺 alwaysApply 和 globs → Manual → 不会自动应用
---4. 规则放在了错误的作用域
Cursor 会读取 workspace 根目录的 .cursor/rules/，也会读取子目录里嵌套的 .cursor/rules/（以及就近的 AGENTS.md），更具体 / 更近的规则优先级更高。出问题往往是把错误的目录当成了 workspace 打开：如果你打开的是 ~/code/monorepo，但规则在 packages/web/.cursorrules，那么子目录里的一个旧版单文件不会在整个项目范围生效。
如何判断：标题栏 / 左下角会显示当前 workspace 路径；确认能从那里解析到规则文件。
pwd
ls -la .cursorrules .cursor/rules/ 2>/dev/null在 monorepo 里，把共享规则放在根的 .cursor/rules/，把各个包专属的规则放在 packages/<name>/.cursor/rules/。
5. rules 缓存没刷新
新增或修改规则后，正在运行的窗口可能继续用旧版本，直到窗口重新加载。
如何判断：刚改完规则，没有变化；执行 Developer: Reload Window 后立刻生效 = 缓存。
6. 编码不是 UTF-8 或带 BOM
Windows Notepad 默认存成 UTF-8 with BOM。开头的 BOM 会让 frontmatter 解析失败，从而丢弃整条规则（和原因 2 一样的静默跳过）。
如何判断：
file .cursor/rules/style.mdc
# 期望："...: UTF-8 Unicode text"
# 异常："...: UTF-8 Unicode (with BOM) text"
hexdump -C .cursor/rules/style.mdc | head -1
# 以 ef bb bf 开头 = BOM7. 规则被 .cursorignore 屏蔽
有些团队把 .cursorrules 写进 .gitignore（当个人偏好处理），却顺手也写进了 .cursorignore。Cursor 自己的 ignore 列表会让它跳过这个文件。
如何判断：
git check-ignore .cursorrules .cursor/rules/style.mdc
grep -i cursorrules .cursorignore 2>/dev/null动手前先确认
- 选定一种格式：新的
.cursor/rules/*.mdc（推荐；在所有模式包括 Agent 都生效）。旧版.cursorrules只是为了向后兼容才保留，Cursor 已表示会将其移除。 - 改规则前先 commit 一次，方便在加载失败时对照一个干净的基线排查。
- 记下 Cursor 版本：
Cursor → About（.mdc系统已经做默认很久了，但”Agent 只读.mdc”这个行为正是坑到近期升级用户的关键）。
最短修复路径
格式 → 触发条件 → 缓存。
Step 1：迁移到 .cursor/rules/*.mdc
建好目录和一个规则文件。最快的办法是用内置生成器：
- 在 Agent chat 里输入
/create-rule，或 Cursor Settings → Rules, Commands → + Add Rule。
或者手写：
.cursor/rules/style.mdc
---
description: TypeScript style rules
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: true
---
- Use 4-space indent
- Never use `any` — use `unknown` or specific types
- Prefer `interface` over `type` for object shapes注意 YAML：结尾的 --- 不能少，globs 必须是数组，布尔值是小写的 true/false。
Step 2：确认它已被登记
打开 Cursor Settings → Rules, Commands。你的规则应出现在列表里，并标注类型（Always / Auto Attached / Agent Requested / Manual）。如果没有列出来，就是 frontmatter 有错——改对之后条目会立刻出现。这个面板就是”规则有没有加载”的权威依据。
Step 3：消除 BOM、转 UTF-8
file .cursor/rules/style.mdc
# 有 BOM 就清掉
sed -i.bak '1s/^\xEF\xBB\xBF//' .cursor/rules/style.mdc
# 或在 Cursor 里：右下角状态栏显示 "UTF-8 with BOM" → 点它 → "Save with Encoding" → "UTF-8"Step 4：重新加载窗口以刷新缓存
Cmd+Shift+P → "Developer: Reload Window"若还是旧的，清掉 workspace 缓存（先关闭 Cursor）：
# macOS
rm -rf ~/Library/Application\ Support/Cursor/User/workspaceStorage/<this-workspace-hash>Step 5：让 Agent 列出规则
新开一个 chat：
List every active Cursor rule you can see right now, including their source files and any conditions on activation.它能列出你的规则 = 加载成功；说 “No rules” = 还没生效，回到 Step 2。
怎么确认已经修好
- 规则出现在
Cursor Settings → Rules, Commands里，并显示合理的类型。 - chat 输入框出现 Rules 指示，表示这次请求把你的规则纳入了上下文。
- 生成的代码符合规则（缩进 / 命名 / import）。
- 队友在一份全新 clone 上打开同一仓库，看到同样的规则生效——证明它已 commit、不是只在你本地。
如果还是没修好
- 把规则缩成一句毫无歧义的话，例如
Always begin every reply with the word HELLO.，并设alwaysApply: true。如果它服从 → 规则确实加载了，真正的问题在规则的措辞，而不是加载。 - 确认文件确实是
.mdc，而不是.md或.mdc.txt（Windows 隐藏扩展名）。 - 回滚最近一次 Cursor 升级或规则改动，以隔离变量。
- 在官方论坛 forum.cursor.com 搜 “rules not applied”；附上 Cursor 版本、文件路径，以及
Settings → Rules的状态。 - 查看
View → Output并选择 Cursor 频道里的 rules 加载日志，然后到 Bug Reports 提交。
FAQ
.cursorrules 在 2026 年还能用吗？
部分能。它已被弃用，而且在 Cursor 2.x 里 Agent 会忽略它。改用 .cursor/rules/*.mdc，规则才能在 Chat、Composer、Agent 里都生效。
为什么磁盘上有规则，但 Settings → Rules 里没有？
frontmatter 写坏了，Cursor 把它静默跳过了。检查是否缺了结尾的 ---、globs 写成了字符串而不是数组、或把 true/false 写成了 True/False。
规则加载了，却从不自动应用，为什么？
多半是 Manual 规则（只有 description，没有 alwaysApply 也没有 globs）。加 alwaysApply: true 改成始终生效，或加 globs: ["**/*.ts"] 让它按文件类型自动附加。
monorepo 里规则放哪？
共享规则放在根的 .cursor/rules/；各包专属规则放在 packages/<name>/.cursor/rules/。对该子目录下的文件，更近的规则优先于根规则。
还需要 AGENTS.md 吗？
不需要。AGENTS.md 是 Cursor 同样支持的另一种方式（按目录就近优先）。要 glob / 始终生效这类作用域控制就用 .cursor/rules/*.mdc；只要简单的纯文本指引就用 AGENTS.md。同一套规则别两边都维护。
预防建议
- 加完规则立刻打开
Settings → Rules, Commands，并在 chat 里问 “what rules do you see?”，不要等下次才发现没生效。 - 统一用
.cursor/rules/*.mdc+ 显式alwaysApply: true；淘汰.cursorrules。 - 用 Cursor / VS Code 编辑规则，绝不用 Notepad——避免 BOM。
- 团队规则 commit 到 git，不要写进
.gitignore；个人偏好用设置里的 User Rules。 - 每改一次规则都
Cmd+Shift+P → Developer: Reload Window，避免缓存假象。