Cursor .cursorrules 优化实战：我踩过的三个坑

COVER_IMAGE_PLACEHOLDER

用 Cursor 写代码有一段时间了，默认的 AI 生成经常"放飞自我"——代码风格和项目格格不入，有时候还会改坏我原本正常的函数。后来我开始配置 .cursorrules 文件，试图让 AI 乖乖听话。过程并不顺利，我踩了三个典型的坑。

第一个坑：规则写得越细越好，AI 却变"死板"了

一开始我天真地以为，把规则写详细一点，AI 生成质量就会更高。于是我写了几十条规则，精确到函数注释格式、变量命名规范、import 顺序……结果 AI 开始"过度谨慎"，遇到稍微特殊一点的业务逻辑就拒绝生成，或者生成的内容极其保守，完全没有实用价值。

教训：.cursorrules 不是写论文，规则太多会让 AI 不敢发挥。保留核心约束就好，给它留足够的灵活空间。

第二个坑：全局规则导致模块间"打架"

规则越积越多，我开始发现一个问题——同一个项目里，前端模块和后端模块的代码风格完全不同，但 AI 用同一套规则生成，结果两边都不讨好。

比如我的 React 前端用 camelCase，Python 后端用 snake_case，但 AI 在后端代码里也给我生成 camelCase 变量名，因为全局规则优先。

教训：用 <match> 前缀限定规则作用域，只在需要的目录下生效。

{
  "match": "src/frontend/**",
  "rules": {
    "naming_convention": "camelCase",
    "quotes": "single"
  }
}

{
  "match": "src/backend/**",
  "rules": {
    "naming_convention": "snake_case",
    "quotes": "double"
  }
}

第三个坑：用了 Markdown 格式，规则被 AI"无视"

我最开始用纯 Markdown 写 .cursorrules，像写文档一样：

## 命名规范
- 变量使用 camelCase
- 常量使用 UPPER_SNAKE_CASE

## 注释要求
- 每个函数必须有 JSDoc 注释

结果 AI 完全不理会这些规则，照样生成它自己习惯的格式。查了半天才发现：Cursor 对 .cursorrules 有特定的格式要求，不是所有写法都能被正确解析。

有效规则怎么写：我的实战模板

经过反复试错，我总结出一套能正常生效的规则写法：

1. 用大白话描述业务规则（比技术术语更有效）

// 不要这样写：
naming_convention: camelCase

// 这样写更有效：
When working with React components, always use PascalCase for component names and camelCase for variables. Functions that handle API calls should be prefixed with "fetch" or "get".

2. 用负面约束告诉 AI 什么不要做

// 在生成任何数据库查询前，必须：
// 1. 使用参数化查询，禁止字符串拼接
// 2. 每个 query 必须有对应的错误处理
// 3. 禁止在查询中使用用户直接输入的变量（必须经过 sanitize）

3. 在规则里加"示例"比描述更直观

// ✅ 这样 AI 能理解：
Always use async/await instead of .then() chains. Example:
// Good:
const data = await fetchUser(id);
// Bad:
fetchUser(id).then(res => {{ console.log(res) }})

4. 用 <match> 控制生效范围

{{
  "match": "**/*.test.js",
  "rules": "禁止在测试文件里使用 setTimeout，如果必须用请用 jest.useFakeTimers()"
}}

{{
  "match": "**/utils/*.py",
  "rules": "工具函数必须带类型注解，复杂函数必须有 docstring"
}}

规则生效的验证方法

写完规则后，不要直接写业务代码。先用一个简单的测试场景验证规则是否生效：

// 在项目中新建一个空文件，然后让 AI 补全一个简单函数
async function fetchUserById(id) {{
  // 让 AI 生成完整函数体，看是否符合你的规则
}}

如果生成的内容不符合预期，再调整规则。这个过程需要迭代，但一旦配置好，后续开发体验会大幅提升。

我现在的 .cursorrules 结构

[
  {{
    "match": "**/*.tsx",
    "rules": "React 组件用 PascalCase，props 接口用 I 开头，事件处理函数用 handle 前缀，CSS-in-JS 用模板字符串"
  }},
  {{
    "match": "**/api/**/*.py",
    "rules": "API 路由必须带类型注解，返回值必须是 Pydantic Model，错误用 HTTPException，禁止直接返回 dict"
  }},
  {{
    "match": "**/*.test.*",
    "rules": "测试文件禁止 setTimeout，禁止 sleep，禁止硬编码时间，必须用 mock"
  }}
]

踩坑总结

坑	原因	解决方案
规则太细 AI 死机	约束超过必要范围	只保留核心约束，其余靠 Code Review
全局规则冲突	没有限定作用域	用 match 字段分目录配置
规则不生效	格式不被 Cursor 识别	用结构化 JSON/对象格式

配置 .cursorrules 不是一个一劳永逸的事，需要根据实际项目不断迭代。我的建议是：先配最核心的3-5条规则，跑一周看效果，再逐步调整。不要一开始就想覆盖所有场景。

你的 .cursorrules 有没有踩过类似的坑？欢迎留言交流。