你在仓库根放了 .cursorrules，里面明确写了 “use 4-space indent, never use any”，结果 Composer 给出来的代码还是 2-space、满是 any。问 Composer “what rules do you see?” 它说不知道有规则。问题通常是文件没在 Cursor 认的位置（旧 .cursorrules vs 新 .cursor/rules/*.mdc）、编码不是 UTF-8、客户端版本不识别新格式、或 rules 缓存没刷新。
修法是先排除位置和格式问题，再确认 Cursor 实际加载了哪些 rules。
常见原因
1. 文件不在 workspace 根
Cursor 只在 workspace 根目录找 .cursorrules。如果你 Cursor 打开的是 ~/code/monorepo，但 rules 放在 ~/code/monorepo/packages/web/.cursorrules，只有打开 packages/web 当 workspace 时才会加载。
如何判断：左下角看当前 workspace 路径；ls .cursorrules 必须在 workspace 根能列出。
2. 用了新 .cursor/rules/*.mdc 格式但客户端旧
Cursor 后期推 .cursor/rules/ 目录 + .mdc 文件，支持 frontmatter (globs / always / agent_requested)。客户端版本太老不识别这种结构。
如何判断：
ls .cursor/rules/有文件但 Composer 不认 → 客户端旧。
3. 文件编码不是 UTF-8 或带 BOM
Windows Notepad 默认存 UTF-8 with BOM；Cursor 读到 BOM 可能整文件 parse 失败、回退到无 rules。
如何判断：
file .cursorrules
# 期望：".cursorrules: UTF-8 Unicode text"
# 异常：".cursorrules: UTF-8 Unicode (with BOM) text"
# 或 hexdump 前 3 字节
hexdump -C .cursorrules | head -1
# 看是不是 ef bb bf 开头 = BOM4. rules 缓存没刷新
新加 / 改了 rules 后，Cursor 客户端可能继续用旧版本 5-30 分钟。
如何判断：刚改完没生效；重启 Cursor 后立刻生效 = 缓存。
5. .cursor/rules/*.mdc frontmatter 没设触发条件
.mdc 文件可以设 alwaysApply: true / globs: ["**/*.ts"] / description: ...。如果你只写了 description 而没 alwaysApply 也没 globs 匹配当前文件，rules 不会自动注入。
如何判断：
---
description: Use 4-space indent
# 缺 alwaysApply 和 globs → 不会注入
---6. Rules 在 .gitignore / .cursorignore 里
某些团队把 .cursorrules 写在 .gitignore 里（因为它是个人偏好），但顺手也写进 .cursorignore——这是错误，Cursor 的 ignore 也会让自己跳过它。
如何判断：git check-ignore .cursorrules / cat .cursorignore | grep cursorrules。
动手前先确认
- 确认你期望的 rules 是
.cursorrules（旧格式）还是.cursor/rules/*.mdc（新格式），不要混。 - 改 rules 前 commit 一次，避免改完没效果时分不清是哪条改动。
- 记下 Cursor 版本；新格式需要相对较新的客户端。
需要收集的信息
- Cursor 版本（Cursor → About）。
.cursorrules或.cursor/rules/全部文件路径 + 内容。file .cursorrules输出（编码 + BOM 状态）。- Composer 问 “what rules are active?” 的回复。
.cursorignore是否包含cursorrules字样。
最短修复路径
按”先排查位置 → 格式 → 缓存”。
Step 1：确认文件在 workspace 根
# 找当前 workspace 的根
pwd # 或左下角看 Cursor 显示的路径
ls -la .cursorrules .cursor/rules/ 2>/dev/null如果 rules 在 packages 子目录，要么换成打开那个子目录当 workspace，要么把 rules 移到顶层根。
Step 2：消除 BOM、转 UTF-8
# macOS / Linux
file .cursorrules
# 有 BOM 就清掉
sed -i.bak '1s/^\xEF\xBB\xBF//' .cursorrules
# 或重存：用 VS Code 打开 → 右下角点 UTF-8 with BOM → 选 "Save with Encoding" → "UTF-8" (不带 BOM)Step 3：确认 Cursor 版本支持新格式
新 .cursor/rules/*.mdc 至少要 Cursor 0.42+。Cursor → Check for Updates。若卡在旧版：
# macOS
brew upgrade --cask cursor
# 或 https://cursor.com/downloadStep 4：给 .mdc rules 加触发条件
.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 shapesalwaysApply: true 强制每次都注入；globs 让模型按文件类型自动激活。
Step 5：强制刷新 rules 缓存
Cmd+Shift+P → "Developer: Reload Window"或更彻底：清 workspace 缓存：
rm -rf ~/Library/Application\ Support/Cursor/User/workspaceStorage/<this-workspace-hash>Step 6：让 Composer 验证
打开 chat 问：
List every active cursor rule you can see right now, including their source files and any conditions on activation.如果它列出来了 = 加载成功；如果说”no rules” = 还没生效。
怎么确认已经修好
- Composer 自己列出 rules 内容，且按规则生成代码（缩进 / 命名 / import 风格符合）。
- 切到另一台机器同步同仓库，rules 同样被识别。
- 让队友打开同一 workspace 问”what rules are active”，得到一致回答。
如果还是没修好
- 把 rules 缩到一句话，例如 “Always start every reply with the word HELLO.”，看模型是否服从——能服从就是 rules 已加载，行为问题在 prompt。
- 回滚最近一次 Cursor 升级或 rules 改动。
- 在 forum.cursor.com 搜 “cursorrules not loaded”；附 Cursor 版本 + 文件路径 + 编码。
- 抓 View → Output → Cursor 的 rules 加载日志贴 Bug Reports。
预防建议
- 加完 rules 立刻在 chat 里问 “what rules do you see?” 验证，不要等下次再发现没生效。
- 用新
.cursor/rules/*.mdc格式 + 显式alwaysApply: true，比旧.cursorrules更可控。 - 用 VS Code/Cursor 而不是 Notepad 编辑 rules，避免 BOM。
- 团队仓库的 rules commit 到 git，不要写在
.gitignore；个人偏好用 user-level 配置。 - 每改一次 rules 都 Cmd+Shift+P → Reload Window，避免缓存假象。