Cursor Agent 为何完全无视你的 .cursorrules？10 分钟硬核迁移指南

你辛辛苦苦写了一篇 .cursorrules，40 多行规范，全是踩坑踩出来的经验。结果一打开 Cursor 的 Agent 模式，它全当没看见。没有报错，没有警告，就是单纯不理你。

这不是你的错，也不是 bug。Cursor 内部有两套完全独立的规则加载系统，而 Agent 模式走的是另一条路。今天这篇内容，用最直白的话告诉你为什么会这样，以及怎么在 10 分钟内彻底修复。

为什么 Agent 模式完全不理你的 .cursorrules

Cursor 加载规则的方式可以简单理解为“两套班子”：

• Ask / Edit 模式：读的是项目根目录下的 .cursorrules 文件
• Agent 模式：读的是 .cursor/rules/ 目录下的 .mdc 文件

当你启动 Agent 模式时，Cursor 会直接跳过 .cursorrules，去寻找带有特定 YAML 前置元数据的 .mdc 文件。如果找不到，它就裸奔——而且完全不告诉你。

这其实是旧版格式（.cursorrules）和新版项目规则（.mdc）的架构分歧。两套系统同时存在，但跑的是不同的逻辑。

最扎心的现实：如果你一直靠 .cursorrules 约束 Agent 的行为，那你的 Agent 模式其实一直在“无护栏驾驶”。

.mdc 格式到底长什么样

.mdc 文件放在 .cursor/rules/ 里，用 YAML 前置元数据声明作用范围。

最基础的全局规则长这样：

---
description: "Core project conventions"
alwaysApply: true
---

# 核心项目规范：以下规则对全局文件生效
Use TypeScript strict mode. Never use `any`.
Prefer named exports over default exports.
# 强制要求：所有异步函数必须显式处理错误，禁止未处理的 Promise
All async functions must handle errors explicitly — no unhandled promise rejections.

把它存为 .cursor/rules/core.mdc。

如果想让规则只对特定文件生效，比如 React 组件：

---
description: "React component conventions"
alwaysApply: true
globs: ["**/*.tsx", "**/*.jsx"]
---

# React 组件规范：仅对 .tsx 和 .jsx 文件生效
Components are function components only — no class components.
Props interfaces are named `<ComponentName>Props`.
# 禁止写法：不要使用 React.FC，改为直接标注返回类型
Never use `React.FC` — annotate the return type instead.
Use `useCallback` for handlers passed as props.

把它存为 .cursor/rules/react.mdc。

这里的 globs 字段很重要。如果不写，虽然 alwaysApply: true 会让规则被加载，但 Cursor 在上下文窗口紧张时可能会降低它的优先级。加了 globs，规则就会被标记为与当前文件“直接相关”，实际命中率会高很多。

手把手迁移：5步走

第一步：创建规则目录

# 创建 .cursor/rules 目录，-p 参数表示如果父目录不存在也一并创建
mkdir -p .cursor/rules

第二步：拆分你的 .cursorrules

千万别把原来的内容一整块复制过去。单文件规则太长，Cursor 反而会“消化不良”。建议按领域拆成多个文件：core.mdc、react.mdc、api.mdc、testing.mdc。

第三步：转换格式

每个 .mdc 文件的基本模板是：

---
description: "<这条规则覆盖什么内容>"
alwaysApply: true
globs: ["<匹配的文件路径>"]  # 如果是全局规则，可以删掉这一行
---

# 在此粘贴原 .cursorrules 的对应内容，每条规则尽量简短独立
<your rules here, one concern per line>

第四步：清理旧文件

把 .cursorrules 删掉或重命名成 .cursorrules.bak。两个文件同时存在会造成混乱。虽然在 Agent 模式下旧文件根本不会被读取，但在 Ask/Edit 模式下可能两边都生效，甚至冲突。

第五步：实测

新开一个 Agent 会话，让它写点你平时会约束的东西，看看它是否遵守了。如果不遵守，通常是两个原因：单文件超过 200 行（会被系统降权），或者漏写了 alwaysApply: true。

迁移后最容易翻车的 3 类规则

很多人格式写对了，但发现 Agent 还是不听劝。问题往往出在这三类规则上：

1. “一定要用某某库做某事”

比如“所有校验都用 Zod”。如果这条规则放在没有 globs 的全局文件里，Agent 处理非校验文件时，可能觉得“这跟我没关系”，直接跳过。

• 解决办法：把这类规则放到带 globs 的文件里。例如把 Zod 的规则放进 zod.mdc，并配上 globs: ["**/*.ts", "**/*.tsx"]，命中率远高于放在 core.mdc 里。

2. 否定式规则（“永远不要做某事”）

像“不要用 var”、“不要用 any”这类否定句，Agent 的理解效果不如肯定句。因为大模型处理“禁止做某事”需要多一步推理。

• 解决办法：改成肯定句。比如把“不要用 var”改成“只使用 const 和 let”；把“不要用 any”改成“所有类型必须显式声明”。

3. 长篇大论的规则

如果你在 .cursorrules 里写了很多“之所以这样规定，是因为……”的解释性文字，这些内容会白白吃掉上下文额度，对遵守规则没有帮助。

• 解决办法：删掉解释，只保留指令。一行一条，动词开头。省下来的上下文额度，Cursor 会用来更好地执行规则。

alwaysApply 的隐形陷阱

alwaysApply: true 的意思是“每次 Agent 运行都加载这条规则”，但“加载”不等于“遵守”。

Cursor 0.16 版本之后有个“静默降权”机制：如果单条规则文件太长（超过 200 行），或者写得太过宽泛，系统在上下文压缩时会悄悄降低它的优先级。没有任何日志提示，规则看似加载了，实则没效果。

真正靠谱的组合是：

---
description: "TypeScript conventions"
alwaysApply: true
globs: ["**/*.ts", "**/*.tsx"]  # 只有匹配到这些文件时，规则才会被高优先级加载
---

alwaysApply: true 保证它被加载，globs 保证它在相关文件中被视为高优先级。两者缺一不可。

什么样的规则才算“真正通过 Agent 验证”

一条规则要真正在 Agent 模式下生效，必须同时满足这 5 点：

• 它必须放在 .cursor/rules/ 目录下，且是 .mdc 后缀
• 前置元数据里必须有 alwaysApply: true
• 必须带有 globs，匹配它要管辖的文件
• 单个文件不超过 50 行
• 每条规则都是一句简单的祈使句

满足这 5 条的规则，在 Agent 会话中的命中率非常稳定。只要缺一条，效果就是随缘。

快速验收脚本

迁移完成后，跑一遍这个脚本，检查每个 .mdc 文件的前置元数据是否齐全：

# 遍历 .cursor/rules/ 目录下所有 .mdc 文件，检查头部格式是否正确
for f in .cursor/rules/*.mdc; do
  # 打印当前文件名，方便对照检查
  echo "=== $f ==="
  # 输出文件前 6 行，确认包含 alwaysApply 和 description
  head -6 "$f"
  echo ""
done

如果输出结果里每个文件都显示了 alwaysApply: true 和 description 字段，说明格式没问题。如果哪个文件开头没有 --- 分隔符，那它就不会被正确加载。

一句话总结

• .cursorrules 只在 Ask/Edit 模式下生效，Agent 模式直接无视
• Agent 模式只认 .cursor/rules/ 下的 .mdc 文件，且需要 alwaysApply: true
• 迁移的核心就是“拆分”：按领域拆成多个小文件，一个文件管一件事
• 给每个文件加上 globs，告诉 Cursor 它该管哪些文件
• 每个文件控制在 50 行以内，规则写成短句

这个坑在 Cursor 论坛里已经被问了无数次。好消息是，一旦你明白背后的机制，修复它完全就是个体力活。

如果你懒得自己折腾，也可以直接入手现成的规则包。直达网址：https://oliviacraftlat.gumroad.com/l/wyaeil