去年开始重度用 Cursor，前三个月我是边用边骂的。

明明已经告诉它"用 TypeScript"，它写完给我来一段 any；我刚强调"不要在 React 组件里直接请求接口"，它转头就在 useEffect 里 fetch；最离谱的一次，让它重构一个老模块，改完之后十个单测全红了。

后来我才意识到，问题不在 AI，是我没把规则立起来。Cursor 给的 .cursorrules 文件根本没用上，等于让一个不熟项目的新人直接上手写代码。

这篇文章把我后来沉淀下来的三套模板（前端、Python 后端、Node 全栈）整理出来，附带我踩过的几个坑。文末也给了一个我自己常用的"自查清单"。

.cursorrules 到底是什么

就是一个放在项目根目录的纯文本文件，Cursor 启动时会自动读取，作为系统级上下文喂给 AI。相当于给新员工发的那本《开发手册》。

注意几个关键点：

• 文件名固定是 .cursorrules（带点），不是 .cursor-rules 也不是 cursorrules.md
• 从 Cursor 0.45 版本开始支持项目级，从 0.48 开始又多了 .cursor/rules/ 目录式规则（MDC 文件，可以按 glob 匹配生效范围）
• 优先读取项目级，全局兜底读 ~/.cursor/rules/
• 写多写少都行，但千万别写废话，AI 会真的去"遵守"

第一套：前端 React + TypeScript 项目

# 项目：xxx 管理系统前端
# 技术栈
- React 18 + TypeScript 5.x
- 状态管理：Zustand（不要 Redux）
- UI 组件：Ant Design 5
- HTTP：axios，统一封装在 src/utils/request.ts
- 路由：react-router v6

# 代码风格
- 函数组件 + Hooks，禁止 class 组件
- 任何 props 必须定义 interface，不允许 inline 类型
- 命名：组件 PascalCase，函数 camelCase，常量 UPPER_SNAKE_CASE
- 文件：组件用 .tsx，工具函数用 .ts
- 禁止使用 any，实在不知道类型用 unknown

# 目录约定
- 页面放 src/pages，组件放 src/components
- 业务 Hook 放 src/hooks，以 use 开头
- 接口请求按模块放 src/api/<module>/

# 必须遵守
- 所有接口调用必须走 request.ts，不允许直接 axios
- 表单统一用 react-hook-form + zod
- 提交前先跑 typecheck 和 lint
- 涉及修改多个文件时，先列改动清单再动手

这套用在我最常用的后台管理项目里。两条必须展开说一下：

第一条，"禁止使用 any"这句一定要写。我之前没写，AI 一偷懒就是 const data: any = ...，TypeScript 直接白搭。

第二条，“涉及修改多个文件时，先列改动清单再动手”。这一条能极大减少 AI 一次改十处然后整段崩的情况。

第二套：Python 后端（FastAPI）

# 项目：xxx API 服务
# 技术栈
- Python 3.11+
- FastAPI + Pydantic v2
- ORM：SQLAlchemy 2.0（async 模式）
- 数据库：PostgreSQL
- 任务队列：Celery + Redis

# 代码风格
- 遵循 PEP 8，行宽 100
- 类型注解必须写全，函数签名不允许裸参数
- 用 dataclass 或 Pydantic model 做数据结构
- 异步函数统一加 async def，I/O 操作禁止用同步

# 错误处理
- 业务异常抛自定义异常类，定义在 app/exceptions.py
- 接口层用统一异常处理中间件捕获，禁止在路由里 try/except Exception
- 日志用 structlog，不允许 print

# 测试
- 每个新接口必须带 pytest 用例
- 覆盖率不允许低于 80%
- 涉及数据库的测试用 testcontainers，不允许 mock 数据库

# 绝对不要
- 不要在业务代码里写 SQL 字符串，全部走 ORM
- 不要用全局变量保存状态
- 不要 import *，必须显式 import

Python 这套里我重点想提的是测试要求。早期我没要求"必须带测试用例"，结果 AI 写完一个接口就跑，提交后我自己再补单测，又得重新读一遍代码找上下文，效率反而更低。把测试要求写进规则后，AI 一次就会把测试代码也写出来，省下我来回切上下文的时间。

第三套：Node 全栈（Next.js）

# 项目：xxx 全栈应用
# 技术栈
- Next.js 14（App Router）
- TypeScript 5.x
- 数据库：Prisma + PostgreSQL
- 鉴权：NextAuth.js
- 样式：Tailwind CSS

# 路由和组件
- 页面组件默认是 Server Component
- 客户端组件必须在文件顶部加 'use client'
- 数据获取在 Server Component 里完成，客户端组件不直接请求
- API Route 放 app/api/<resource>/route.ts

# Prisma 规范
- model 命名单数，表名复数（@map）
- 软删除字段：deletedAt DateTime?
- 时间字段统一用 @updatedAt / @createdAt
- 不允许在生产代码里用 prisma.$queryRaw

# 安全
- 用户输入必须用 zod 校验
- 任何外部请求必须走 server-side
- 密钥不允许出现在客户端代码里

Next.js 这套里"Server Component 默认"这条要单独说一下。新人或者 AI 经常无脑加 'use client'，整个组件树就都跑到客户端，bundle 体积直接暴涨。每次我看见不假思索加 'use client' 的 PR，心里都会咯噔一下。

我踩过的三个坑

坑一：规则太多，反而限制了 AI

有一段时间我写了 200 多行规则，覆盖了所有我能想到的细节。结果 AI 生成代码时变得束手束脚，每次都只输出最保守的版本。

后来我做了两个调整：

• 规则压缩到 80 行以内，只保留"必须遵守"和"绝对不要"
• 团队约定类的（比如 PR 流程、commit 格式）放 README，不放 .cursorrules

我后来琢磨出来的边界是：.cursorrules 写 AI 必须遵守的代码契约，README 写给人看的流程文档。两个不要混在一起。

坑二：规则和实际代码脱节

我曾经在规则里写"使用 Zustand 状态管理"，但项目里还有几个老模块用的是 Redux。AI 看到规则就敢改老模块的 Redux 代码。

解决办法是：.cursorrules 只约束新写的代码，老模块的维护规则在文件头注释里写清楚。这条踩得比较疼，印象很深。

坑三：以为全局规则能搞定一切

~/.cursor/rules/ 里的全局规则我放了一些通用规范（注释风格、禁止 emoji、日志规范），但项目相关的一律不放。原因是换项目时全局规则会跟着生效，A 项目的约定跑到 B 项目里会冲突。

我现在的做法是：全局规则只放个人习惯（写代码不写 emoji、变量名用英文等），项目相关的一律项目级。

自查清单（我每次都会过一遍）

1. 文件名是 .cursorrules 不是其他？
2. 技术栈写得具体到了版本号（React 18，不是 React）？
3. 有"绝对不要"段落吗？没有就补上，AI 真的会试
4. 涉及多文件协作的逻辑，列了步骤吗？
5. 团队成员都看过这份规则吗？这条最重要

最后一句，也是我写完这篇文章才想明白的：.cursorrules 不是文档，是契约。

你写得越具体，AI 的发挥越稳定；你写得越模糊，AI 给你胡来就越没心理负担。

如果你刚接触 Cursor，建议从最常用的项目开始，花半小时把第一套模板填出来。一周后你再回来看生成代码的质量，会发现明显不一样。

Composer Agent 那个坑比这个还多，下一篇再写。