你认真写了一份规则，要求 Cursor 用 TypeScript、不要 any、禁用 inline 样式——结果下一次生成三条全犯。文件就在仓库里，可模型像没看见一样。
最快的修复（截至 2026 年 6 月）： 最常见的元凶是 .cursor/rules/*.mdc 文件的 YAML frontmatter 写错了。只要 frontmatter 有任何错误（缺了结尾的 ---、globs 没写成列表、把 true 写成了 True），Cursor 就会静默跳过整个文件，连个警告都没有。打开规则文件，修好 frontmatter，然后新开一个 Agent chat 重测。如果你还在用旧的单文件 .cursorrules，这个格式已经弃用（从 Cursor 0.43 起），而且只在部分模式下加载。迁移到 .cursor/rules/*.mdc 才是长久的修法。
本文走一遍规则加载顺序、四种规则触发类型及其菜单标签原文、如何确认规则真的到达了模型，以及怎样干净地完成新旧格式迁移。
四种规则类型（以及它们各自的静默失败方式）
Cursor 的规则界面（Cursor Settings > Rules, Commands）在下拉里提供四种触发类型。每种失败的方式都不一样，所以先搞清楚自己写的是哪种，诊断就成功了一半。
| 类型（界面标签） | 何时加载 | frontmatter 形态 | 常见的静默失败原因 |
|---|---|---|---|
| Always Apply | 每个 chat / Agent 会话 | alwaysApply: true | frontmatter 语法错，或文件是 .md 不是 .mdc |
| Apply to Specific Files（Auto Attached） | 匹配 globs 的文件被打开或引用时 | alwaysApply: false + globs: 列表 | glob 没匹配到打开的文件路径 |
| Apply Intelligently（Agent Requested） | Agent 读 description 自己决定 | alwaysApply: false、无 globs、有 description | description 太空泛，Agent 永远挑不中它 |
| Apply Manually | 只有你输入 @rule-name 时 | 无 globs、alwaysApply: false | 你以为它会自动加载；它永远不会 |
常见原因
1. frontmatter YAML 语法错误（第一大原因）
.mdc 文件顶部的 frontmatter 只要有任何 YAML 错误，Cursor 就会整个跳过，没有日志、没有警告、连红波浪线都没有。坑人最多的三种：
- 缺了结尾那行
---，整份文件被当成正文。 globs写成了单个字符串，而不是 YAML 列表。True/False首字母大写。YAML 布尔值必须是小写true/false。
如何判断： 打开 .mdc 文件，确认有干净的开头和结尾 --- 块、globs 是列表、布尔值是小写。一个合法的块长这样：
---
description: General coding conventions for this repo
globs:
- "src/**/*.ts"
alwaysApply: false
---2. 文件是 .md，不是 .mdc
随手丢进 .cursor/rules/ 的纯 .md 文件会被规则系统忽略，因为它没有放 frontmatter 的位置。项目规则必须用 .mdc 扩展名。
如何判断： ls -la .cursor/rules/。任何以 .md（而非 .mdc）结尾的规则都是无效的。
3. 文件位置不对
旧的 .cursorrules 必须放在仓库根目录，和 package.json 同级；放在 src/ 或 apps/web/ 里都会被忽略。新格式的 .mdc 文件必须在某个 .cursor/rules/ 目录下。支持嵌套子目录（比如 .cursor/rules/frontend/components.mdc），但 .cursor/rules 这个根必须存在。
如何判断： 在仓库根执行 ls -la .cursorrules .cursor/rules/ 2>/dev/null。两个都不在根目录就是这个原因。
4. 已弃用的单文件 .cursorrules
仓库根目录的单文件 .cursorrules 从 Cursor 0.43 起已弃用。它目前还能加载，但拿不到按 glob 分片的能力和类型下拉，而且 Cursor 自带的 /create-rule 命令写的是新的 .mdc 格式。如果一个项目里 .cursorrules 和 .cursor/rules/ 都有，两边都会被读取，并以你无法控制的顺序合并。
如何判断： 两个都存在的话，迁移到 .cursor/rules/*.mdc 并删掉 .cursorrules。
5. glob 绑到了当前文件没匹配上的路径
一条 Apply to Specific Files 规则写了 globs: ["src/api/**/*.ts"]，只有在匹配该模式的文件被打开或在 prompt 里被引用时才会挂载。编辑 src/components/Button.tsx，或者问”我该怎么组织组件？“这种没有任何文件在上下文里的泛问题，都不会触发它。
如何判断： 打开一个 glob 应该匹配的文件，看规则有没有出现在 chat 的**上下文面板（context panel）**里。没出现就说明 glob 没匹配上这个路径。
6. 工作区（项目）规则和用户规则打架
规则按固定优先级合并：Team Rules，然后 Project Rules，然后 User Rules，冲突时靠前的来源胜出。Cursor Settings > Rules, Commands 放的是用户级规则，你的仓库放的是项目级规则。如果某条用户级规则和你的项目文件矛盾，合并后的 prompt 可能悄悄丢掉你的项目指引。
如何判断： 打开 Cursor Settings > Rules, Commands，看用户级写了什么。和项目规则冲突的都是嫌疑对象。
7. alwaysApply: true 的规则太多
每条 Always Apply 规则都会被注入到每个请求的 system prompt 里。堆上 10 条以上，它们就会挤掉真正的上下文，模型只会给出平庸的输出，几乎每条规则都被部分违反。这看起来像”规则被无视”，但其实它们全都加载了。
如何判断： 数一下 Always Apply 规则的数量。经验法则：always-on 只留 1-2 条，其余全部用 glob 限定。
8. 在 chat 中途改了规则却没刷新
改完规则后通常要新开一个 chat 才能加载。已经在跑的 chat 会一直带着它开局时的 system prompt。
如何判断： 你是不是在同一个 chat 中途改的规则？新开一个 Agent 线程重测。
动手前先确认
- 确认 Cursor 版本：
Cursor > About。0.43 及以后都把.cursorrules当遗留格式，优先用.cursor/rules/*.mdc。 - 记下你用的是哪个界面（Agent、Composer、Inline Cmd+K）。
.mdc格式在 Chat、Composer、Agent 全都加载；旧的.cursorrules不会触达每个界面；Inline Cmd+K 对文件路径的上下文最少，所以按 glob 分的规则在那里最弱。 - 改规则前先 commit，方便回头二分定位哪条规则导致了哪种行为。
需要收集的信息
find . -maxdepth 4 -name '.cursorrules' -o -path '*/.cursor/rules/*'的输出。- 仓库里每个规则文件的完整内容，含 frontmatter。
Cursor Settings > Rules, Commands里的用户级文本。- 规则本应生效时打开的那个 prompt 和文件路径。
- chat 上下文面板的截图，能看出挂载了哪些规则。
一步步修复
Step 1：确认规则真的到了模型那边
两个检查，先快后慢。
上下文面板： 打开一个规则应该生效的文件，看 chat 的上下文面板。规则若已激活，会出现在那里；不出现就说明文件没加载（直接跳到 Step 2）。
canary 探针： 在规则正文最顶上（frontmatter 下面）加一行 canary：
CANARY: If you read this rule, start your next reply with the word PINEAPPLE.保存，新开一个 Agent chat 随便问一句。回复开头是 PINEAPPLE 就说明规则加载了；不是就别再调行为，先调加载。
Step 2：先验 frontmatter，其他都靠后
打开 .mdc 文件，按顺序确认：
- 开头的
---是文件第一行，且有对应的结尾---。 - 布尔值是小写：
alwaysApply: true或alwaysApply: false。 globs是 YAML 列表，不是裸字符串。- 扩展名是
.mdc，不是.md。
这里只要错一个字符，就是规则”被无视”最常见的原因。改好后新开 chat 重跑 canary。
Step 3：把文件挪到正确位置
新格式（推荐）：
mkdir -p .cursor/rules
git mv .cursorrules .cursor/rules/general.mdc在 general.mdc 最顶上加合法的 frontmatter：
---
description: General coding conventions for this repo
alwaysApply: true
---如果你暂时还要保留旧的单文件格式，它必须在仓库根目录：
git mv src/.cursorrules .cursorrules
git commit -m "move cursorrules to repo root"Step 4：只留一种格式
.cursorrules 和 .cursor/rules/ 同时留着会出现无法预测的合并。迁移到 .cursor/rules/*.mdc 并删掉旧文件。新格式是唯一能用类型下拉、按 glob 分片、且长期受支持的格式，也是 Cursor 的 /create-rule 命令和 Cursor Settings > Rules, Commands > + Add Rule 生成的格式。
Step 5：选对触发类型
让规则的职责和它的 frontmatter 对上：
# Always Apply —— 全局约定，省着用（总共 1-2 条）
---
description: TypeScript and styling conventions
alwaysApply: true
---
- Prefer TypeScript over JavaScript.
- Never use `any`. Use `unknown` and narrow.
- Never inline styles. Use Tailwind classes or CSS modules.# Apply to Specific Files —— 主力；匹配文件在上下文里时加载
---
description: API route conventions
globs:
- "src/api/**/*.ts"
- "src/pages/api/**/*.ts"
alwaysApply: false
---
- API handlers return `Response` objects, not Express-style res.json().
- Wrap handlers in `withErrorHandler` from src/utils/api.ts.
- Validate input with Zod before any DB call.写 Apply Intelligently 规则时，设 alwaysApply: false、省掉 globs，并写一行精准的 description，好让 Agent 自己判断什么时候该用它。
Step 6：开新 chat 重载规则
每次改完规则都要：
- 保存文件。
- 新开一个 Agent / chat 线程（别复用当前那个）。
- 重新跑一次 Step 1 的 canary 探针。
旧 chat 会卡在旧的 system prompt，只有新 chat 能看到更新后的规则。
如何确认已修好
- 新 chat 里 canary 探针（Step 1）回了 PINEAPPLE。
- 打开规则应生效的文件时，它出现在 chat 上下文面板里。
- 重跑最初失败的请求，模型现在会按规则走。
- 队友 clone 仓库后行为一致，说明规则进了版本控制而不是个人设置。
长期预防
- 规则文件放仓库根的
.cursor/rules/下并进版本控制，别只放在用户设置里。 - Always Apply 只留 1-2 条，其余全用 glob 限定，只在相关时加载。
- 按领域（api、frontend、testing）拆成多个
.mdc文件，比一个大文件更好管。 - 加一条 CI 检查：同一分支同时存在
.cursorrules和.cursor/rules/就 fail。 - 在 CI 里 lint frontmatter（结尾
---、globs是列表、布尔值小写），让一个 typo 再也不会静默禁用规则。
常见坑
- frontmatter 里一个 YAML typo 就把文件禁掉，零反馈。
- 把规则存成了
.md而不是.mdc。 - 改了规则但没开新 chat，旧的 system prompt 一直卡着。
- 把规则写得太长（5000+ token），挤掉了真正的上下文。
- 只写”never do X”不写”do Y instead”，模型会退回到默认行为。
- 在 Docker 卷里改规则但卷没同步回 Cursor 读取的宿主路径。
FAQ
Q：.cursorrules 是不是凉了？
A：它已弃用（从 Cursor 0.43 起），但截至 2026 年 6 月仍会被读取。它拿不到类型下拉和按 glob 分片，也不会在每个界面都加载。能迁就迁到 .cursor/rules/*.mdc。
Q：我的规则没有语法错误，可还是不加载，为什么？
A：几乎都是 glob 没匹配上。临时把 alwaysApply: true 打开。如果规则现在生效了，说明内容没问题，是你的 globs 模式没匹配到打开的文件——问题出在 glob，不在规则本身。
Q：规则会占用上下文窗口吗？ A：会。Always Apply 规则在每个请求里都拼到 system prompt 前面；按 glob 分的规则只在匹配文件进上下文时才花 token。always-on 规则保持精简（合计 2000 token 以内），别挤掉真正的代码。
Q：.cursor/rules/*.mdc 会同步到我的 Cursor 账号吗？
A：不会。它们在你的仓库里，跟着 git 走。只有 Cursor Settings > Rules, Commands 里的用户级规则才绑在你账号上。
Q：Inline Cmd+K 能读规则吗？ A：能读一部分。Cmd+K 对 Always Apply 规则比较可靠，但对文件路径的上下文有限，所以按 glob 分的规则在那里很弱。需要 glob 规则就用 Agent 或 Composer 界面。
相关阅读
外部参考：Cursor Rules 官方文档