每个开发者都应该偷学的 10 条 Cursor 规则 (.mdc)
我曾以为 AI 编码助手的水平上限受限于模型本身。直到我看到一位队友用 Cursor 完成同样的任务、用同样的模型，产出的代码却比我的更干净。差异在于他的 .cursor/rules/ 文件夹。他的助手有契约，而我的只是在即兴发挥。
一条好的 Cursor 规则不是励志标语（比如“写干净的代码”）。它是一条具体、可强制执行、且仅在必要时才生效的检查。下面是我偷学、打磨、现在每个仓库都会复制进去的十条规则。偷走那些适合你技术栈的。每条都是一个真实的 .mdc 文件，你可以直接粘贴到 .cursor/rules/ 中。
快速回顾 .mdc 的 frontmatter
Cursor 的项目规则存放在 .cursor/rules/*.mdc。三个 frontmatter 字段决定规则何时加载：
alwaysApply: true—— 每次请求都生效。保持简短且通用。globs: "**/*.tsx"—— 仅当匹配的文件被触及时才自动附加。- 两者都不设置 —— Cursor 会在描述看起来相关时拉入该规则。
范围限定才是关键。十条规则在每次请求时都加载会稀释上下文，直到模型忽略所有的规则。十条限定范围的规则保持精准，因为每次只有相关的两三条同时存在。
1. 不可妥协的全局规则
这是唯一一条我设置为 alwaysApply: true 的规则。里面的每一条都是模型可以应用于 diff 的检查，而不是空头愿望。
---
description: "全局工程护栏 —— 始终应用"
globs: alwaysApply: true
---
- 在边界处验证并类型化所有外部输入（请求体、查询参数、环境变量）。
- 代码中无密钥。从环境变量读取。绝不记录令牌、密码或完整的 PII。
- 可能失败的函数返回类型化的错误或抛出异常 —— 绝不静默返回 null。
- 当你修改函数签名时，在同一个编辑中更新所有调用者。
- 优先删除代码而不是添加标志。最好的修复是移除复杂性。
2. 在它扩散前消灭 any (TypeScript)
如果不加约束，Cursor 会不断使用 any —— 这是阻力最小的路径。这条 glob 限定的规则迫使它思考真正的类型。
3. SQL 安全，按需加载
不使用 alwaysApply——它不会在你的 CSS 工作中占用上下文，但描述让 Cursor 在你编写查询时自动引入该规则。
---
description: Database and SQL safety — apply when writing queries or migrations
globs: alwaysApply: false
---
- 始终使用参数化查询/预编译语句。绝不要将输入直接拼接到 SQL 中。
- 任何可能返回多行的查询都必须分页或使用 LIMIT 限制。
- 注意 N+1 问题：先获取列表再逐条查询每个项目是 bug，而非编码风格。
- 迁移操作可逆，且绝不自动执行——生成迁移文件，交由人工执行。
- 在应用查询中，选择具名列而非 `SELECT *`。
4. 针对边界而非快乐路径的测试
---
description: Test-writing conventions — apply when adding or editing tests
globs: "**/*.test.*, **/*.spec.*"
alwaysApply: false
---
- 优先覆盖边界情况：空输入、null、边界值、重复值和错误路径。
- 每条测试只测试一个行为。测试名称描述的是期望的行为，而非函数名。
- 不测试私有内部实现——只测试公开契约，以便重构时不破坏测试。
- 不要 mock 你不拥有的对象，除非在其外围添加薄层包装。
“优先覆盖边界情况”这一行能显著改变输出。没有它，Cursor 只会写一条测试来证明函数能跑通，然后就不写了。
5. 人类可快速浏览的提交信息
6. 无障碍性，限定在前端
---
description: Accessibility rules for UI
globs: "**/*.tsx, **/*.jsx, **/*.vue"
alwaysApply: false
---
- Every interactive element is keyboard-reachable and has an accessible name (label, aria-label, or text).
- Images have alt text; decorative images use alt="".
- Don't rely on color alone to convey state — pair it with text or an icon.
- Focus is visible and never trapped. Modals return focus to the trigger on close.
7. 错误处理：暴露而非吞没
---
description: Error handling
globs: alwaysApply: false
---
- Never catch an error just to log it and continue — either handle it meaningfully or rethrow.
- Error messages include enough context to debug without a repro (id, operation, input shape).
- User-facing errors are friendly; internal errors keep the stack. Never leak internals to the client.
- No empty catch blocks. Ever.
8. 注释说明“为什么”
---
description: Comment discipline
globs: alwaysApply: false
---
- Comment *why*, not *what*. If a comment restates the code, delete it and rename instead.
- Flag non-obvious decisions, workarounds, and "do not change this because…" with a reason.
- No commented-out code in commits. That's what git history is for.
9. 依赖克制
---
description: Dependency policy
globs: alwaysApply: false
---
- Don't add a dependency to solve what 15 lines of code can. State the tradeoff if you do add one.
- Prefer the platform/standard library before reaching for a package.
- No new dependency without checking it's maintained (recent commits) and has no known critical CVEs.
10. “坚守范围”规则
---
description: The "stay in scope" rule
globs: alwaysApply: false
---
- If you open a file, you must make changes that are strictly related to the task at hand.
- The model should not fix unrelated linting errors, refactor adjacent code, or add comments to files not relevant to the task.
- When working on tests, don't modify source files unless the fix requires it.
- Any deviation from scope must be explicitly approved by the user.
最能节省清理时间的一条。Cursor 总是「热心」地重构你根本没要求的三个文件。
---
description: 范围纪律——始终应用
globs: alwaysApply: true
---
- 只修改任务要求的内容。不要在同一个编辑中格式化或重构无关代码。
- 如果你发现一个无关的 bug，提出来——不要未经询问就修复它。
- 保持 diff 可审查。一个两行修复却产生 400 行 diff 就是失败。
如何实际采用这些规则
不要今天就把十条全贴上——你会稀释上下文，并因维护它们而精疲力尽。从三条开始：规则 #1（全局护栏）、一条栈规则（如果你用 TypeScript 就用 #2）、以及规则 #10（范围纪律）。先按这些规则工作一周。只有当发现 Cursor 重复犯同一个错误时，才添加另一条规则。一条规则的价值在于它能防止一个真实、反复出现的错误——而不是因为它在博客文章里听起来不错。
现在就复制规则 #1 和 #10 到你的仓库里——光这两条就会让你下一次使用 Cursor 时明显更紧凑。