配了.cursorrules之后，Cursor代码补全准确率提升了近4成
用了3个月的 Cursor，我总算把 .cursorrules 玩明白了
上周三下午，新来的实习生凑过来问我：“哥，你每次敲两行代码，Cursor 补全出来跟我想要的库一模一样。我那个怎么跟没睡醒似的？”
我瞄了眼他的项目根目录。
没有 .cursorrules。
啧，跟我三个月前一模一样。今天把这几个月踩的坑整理一下，能帮一个是一个。
为什么你的 Cursor 总是猜不透你
先说个数据。Cursor 官方论坛 2024 年 11 月有个统计，配了 .cursorrules 的开发者，代码补全接受率平均高了 37%，拒绝 AI 建议后手动改代码的比例降了 52%。
我自己体感更明显。配之前，十次补全大概有四五次能用；配完之后，七八次是准的。
这玩意儿本质上就是给 Cursor 的模型（现在底层跑的是 Claude 3.5 Sonnet 和 GPT-4o）塞一段项目级的 System Prompt。你可以把它理解成：每次 AI 给你出主意之前，都得先读一遍这个文件，搞清楚你们项目的规矩。
没配之前，AI 老给我推荐些我们根本不用的库，或者写出跟团队规范打架的代码。配了之后，这种情况少了大概七成。
先看看我写的反面教材
我第一个项目里的 .cursorrules 长这样：
你是一个Python专家，请写出高质量的代码。就这一行。我当时还觉得自己挺聪明。
结果呢？AI 给我生成了一堆用 asyncio 的异步代码——但我们项目跑的是 Flask 同步框架。它还推荐我用 black 格式化，然而团队统一用的是 autopep8。
这就好比你找人外包，只说“你是程序员，给我写代码”。他能写出你想要的东西才有鬼。
一个通用模板，拿走直接用
经过反复改，我整了一套模板结构。先说清楚，这个适合中大型项目。你如果只是写个几十行的脚本，可能用不着这么折腾。
项目名称: [填你的项目名]
技术栈: [比如 Python 3.11 + FastAPI + PostgreSQL]
架构模式: [分层架构 / 微服务 / 单体]
代码风格:
格式化工具: [black / prettier]
行宽: [100]
引号风格: [单引号 / 双引号]
缩进: [2空格 / 4空格]
命名:
变量: [snake_case / camelCase]
常量: [UPPER_SNAKE_CASE]
类名: [PascalCase]
文件名: [kebab-case / snake_case]
技术约束:
禁止的库: [列出你们不用的]
必须用的库: [比如 ORM 强制用 SQLAlchemy]
框架版本: [React 18+]
数据库: [PostgreSQL 15]
项目规则:
错误处理: [统一用自定义异常类]
日志: [强制用 structlog]
类型注解: [必须 / 可选]
测试框架: [pytest / jest]
覆盖率要求: [80%以上]
AI偏好:
回复语言: [中文 / English]
优先建议: [性能 / 可读性 / 安全性]
避免建议: [过度设计 / 过早优化]把这个保存成 .cursorrules 丢在项目根目录，Cursor 会自动读。
实战：一个电商后端的完整配置
说个具体的。我最近在做的电商后端，.cursorrules 长这样：
你正在开发一个电商后端服务，技术栈 Python 3.11 + FastAPI + SQLAlchemy 2.0 + PostgreSQL 15。
## 代码风格
- black 格式化，行宽 100
- 所有函数必须有类型注解
- Pydantic v2 做数据验证
- 数据库操作用 async session
## 项目结构
- routes/ 放路由处理
- services/ 放业务逻辑
- models/ 放 SQLAlchemy 模型
- schemas/ 放 Pydantic 模型
## 重要规则
1. 所有 DB 查询必须带 limit，防止全表扫描
2. 敏感操作（扣款、发货）必须记审计日志
3. API 返回统一用 {"code": 0, "data": {}, "message": "success"}
4. 禁止在路由里直接写 SQL，必须过 service 层
5. 用 structlog 记日志，别用 print
## 测试要求
- pytest + pytest-asyncio
- 每个 service 函数必须有单测
- DB 测试用测试容器，别 mock session
## 性能
- API 响应 P99 < 200ms
- 热点数据优先用 Redis 缓存
- 避免 N+1，用 joinedload配完之后效果怎么样？
昨天下午我写订单查询接口，刚敲完 async def get_order，Cursor 自动补全了：
async def get_order(
order_id: str,
db: AsyncSession = Depends(get_db),
cache: Redis = Depends(get_redis)
) -> OrderResponse:
"""获取订单详情，优先从缓存读取"""
logger = structlog.get_logger()
cache_key = f"order:{order_id}"
if cached := await cache.get(cache_key):
logger.info("order_cache_hit", order_id=order_id)
return OrderResponse.model_validate_json(cached)
query = (
select(Order)
.options(joinedload(Order.items))
.where(Order.id == order_id)
.limit(1)
)
result = await db.execute(query)
order = result.scalar_one_or_none()
if not order:
raise OrderNotFoundError(order_id)
response = OrderResponse.model_validate(order)
await cache.set(cache_key, response.model_dump_json(), ex=300)
logger.info("order_db_hit", order_id=order_id)
return response你仔细看，它自动加了缓存逻辑、用了 joinedload 防 N+1、加了 limit(1)、用了 structlog、还抛了我们自定义的异常类。
这就是 .cursorrules 的威力。不是玄学。
前端项目怎么配
前端配好了也很爽。我有个 Next.js 项目的配置片段：
## 组件规范
- 函数组件 + TypeScript
- Props 必须定义 interface，别用 type
- 用 named export，禁止 default export
- Tailwind CSS，别写内联样式
## 状态管理
- 全局状态 Zustand
- 服务端数据 TanStack Query
- 表单 React Hook Form + Zod
## 文件命名
- 组件：PascalCase.tsx (UserProfile.tsx)
- 工具：camelCase.ts (formatDate.ts)配完之后，AI 再也没给我生成过 export default function，也不会推荐 Redux——我们项目早迁到 Zustand 了。
等等，这里我要更正一下。后来发现 Zustand 在某些场景下不太好使，我们又混用了 Jotai 处理原子化状态。规则文件里得标注清楚哪些场景用哪个，不然 AI 还是会乱推荐。
我踩过的三个坑
坑1：规则写太死
一开始我把规则写到巨细无遗，“if 语句必须带花括号”、“函数体不能超过 20 行”都写进去了。结果 AI 变得特别保守，生成的代码虽然规范，但很僵硬。
后来学乖了。规则抓大放小，重点写项目特有的约定。通用的代码风格让 linter 管。
坑2：忘了更新规则
2024 年 12 月我们把项目从 Flask 迁到 FastAPI，我忘了更新 .cursorrules。那周 AI 还在给我生成 Flask 风格的 decorator，我一度以为 Cursor 出了 bug，还跑去 Discord 上问。
后来才反应过来。
现在 .cursorrules 放在版本控制里，跟代码一起 review。技术栈变更，第一件事就改它。
坑3：规则冲突
有次我同时写了“优先考虑性能”和“优先考虑可读性”。
嗯...这个比较难描述。AI 直接懵了，生成的代码在这两者之间反复横跳——一行写得很优化，下一行又写得很啰嗦。看着特别别扭。
教训：优先级必须明确，别既要又要。
进阶玩法：按目录设不同规则
monorepo 项目可以在不同目录放不同的 .cursorrules。Cursor 会优先读离当前文件最近的规则文件。
my-monorepo/
├── .cursorrules # 全局
├── frontend/
│ └── .cursorrules # 前端专用
├── backend/
│ └── .cursorrules # 后端专用
└── shared/
└── .cursorrules # 共享库这个特性官方文档里没怎么提，但实测有效。我大概是在 2025 年 1 月份试出来的，当时还挺兴奋。
怎么验证规则生效了没
教个土办法。
在规则文件里加一条很特殊的约束，然后故意触发它。
比如我写过“所有错误消息以‘卧槽’开头”。然后写个会报错的代码，看 AI 补全的错误消息是不是“卧槽”开头。如果是，规则生效了。
记得测完删掉。
不然 code review 的时候同事会以为你疯了。别问我怎么知道的。
最后
.cursorrules 不是什么银弹。它只是帮你跟 AI 建立一套共同语言。
配得好，Cursor 像个跟了你三年的徒弟，一个眼神就知道你要干啥。配得不好，它就是个只会背八股文的实习生。
我的建议：花 30 分钟认真写一份，然后根据实际使用持续改。别想着一次写完美，这东西跟代码一样，需要不断重构。
你们项目里怎么配的 .cursorrules？有没有什么特别好用或者特别坑的规则？评论区聊聊，我最近在收集各种项目的配置案例，打算整理个最佳实践合集。
#Cursor #AI编程 #开发工具 #效率提升
读者评论 2