Cursor Rules 深度使用——个性化你的 AI 编程助手

适读人群：使用 Cursor 的开发者 | 阅读时长：约15分钟 | 核心价值：掌握 .cursorrules 配置，让 AI 补全真正符合你的项目规范

去年我接了个老项目迁移的活，一个 2015 年的 Spring MVC 项目，要升级到 Spring Boot 3。打开 Cursor，让它帮我生成一个 Controller。

结果出来一堆我不认识的东西——用了 Lombok 的 @RequiredArgsConstructor，注入方式用字段注入，异常处理用了 @RestControllerAdvice。

这东西本身没问题，是现代 Spring 的标准写法。但问题是这个团队的老代码全是构造器注入、没有 Lombok、异常处理是 AOP 切面。AI 生成的代码和存量代码风格完全不统一，每次我都要手动改。

改了一周之后，我终于去认真研究了 .cursorrules 文件。

研究完我就一个感受：这东西应该是入坑 Cursor 第一天就该配置的，不是高级功能。

---

.cursorrules 是什么

很多人用 Cursor 很久了，但不知道这个文件的存在。简单说：.cursorrules 是放在项目根目录的一个纯文本文件，Cursor 在每次生成代码时都会把这个文件的内容附加到上下文里。

等于说你提前告诉 AI："在这个项目里，你要遵守这些规则。"

这和每次手动在 Chat 里说"记得用 Java 17，记得遵循我们的命名规范"完全不同——后者你会忘，AI 也会忘，前者是系统级的约束。

文件位置：

my-project/
├── src/
├── pom.xml
├── .cursorrules    <-- 放这里
└── ...

Cursor 还支持在 Settings > Rules for AI 里配置全局 Rules，但我建议项目级别的规范放 .cursorrules，全局只放你个人的偏好（比如"不要生成中文注释"之类的）。

---

我的 Java Spring 项目配置

下面是我在 Spring Boot 项目里用的 .cursorrules，这是经过半年打磨之后的版本：

# Java Spring Boot 项目规范

## 技术栈
- Java 17, Spring Boot 3.2.x
- Maven 构建
- MyBatis-Plus ORM
- Redis 缓存
- 不使用 Lombok（团队已决策，不引入）

## 代码规范

### 依赖注入
- 必须使用构造器注入，禁止字段注入
- 超过3个依赖的类，考虑拆分职责

### 命名规范
- 接口：IUserService（I前缀）
- 实现类：UserServiceImpl
- DO（数据库对象）：UserDO
- VO（视图对象）：UserVO
- DTO（传输对象）：UserDTO
- 常量类：UserConstants（不用interface定义常量）

### 异常处理
- 业务异常继承 BusinessException
- BusinessException 包含 errorCode 和 message 字段
- 不要在 Service 层 catch 然后返回 null，直接抛出
- 全局异常由 GlobalExceptionHandler 处理，不要在 Controller 里写 try-catch

### 数据库操作
- 简单 CRUD 直接用 MyBatis-Plus 的 BaseMapper/IService
- 复杂查询写 XML，不要用 QueryWrapper 堆砌超过5个条件
- 字段更新用 UpdateWrapper 指定字段，不要直接 updateById 传全量对象

### 返回值
- 统一返回 Result<T> 包装类
- Result 包含 code、message、data 字段
- 分页返回 PageResult<T>

### 注释规范
- 公共方法必须有 Javadoc
- 复杂业务逻辑内联注释说明"为什么"，不是"是什么"
- 不要写无意义注释如 "// 获取用户"

## 生成代码时的附加要求
- 生成完整可运行的代码，不要省略 import
- 如果我的需求描述不清楚，先问清楚再生成，不要猜测
- 遇到安全相关操作（SQL拼接、文件操作、外部请求），主动提示潜在风险
- 不要自作主张引入新依赖，如果确实需要告诉我

这个配置有几个细节值得说：

"不使用 Lombok"这条很关键。 AI 天然喜欢用 Lombok，因为训练数据里大量现代 Java 代码都用。但如果你的团队决策是不引入，你不写这条，AI 每次都会给你加 @Data，然后你再删，浪费时间。

明确说"先问清楚再生成"。 这条改变了我和 Cursor 的交互模式。以前 AI 总是猜我的意图然后生成一大堆，有时候猜对有时候猜错，猜错了我还得重新描述。加了这条之后，AI 遇到模糊需求会先问，整体生成质量高很多。

"不要省略 import"。 这条超级实用。AI 默认会生成省略 import 的代码，你还得自己加。这一条能省很多时间。

---

Python FastAPI 项目的 Rules

我同时在维护几个 Python 项目。Python 项目的 Rules 风格完全不同：

# Python FastAPI 项目规范

## 技术栈
- Python 3.11+
- FastAPI + Pydantic v2
- SQLAlchemy 2.0（async）
- PostgreSQL + asyncpg
- Poetry 包管理

## 代码风格
- 遵循 PEP 8
- 类型注解必须完整，不允许使用 Any（除非有明确注释说明原因）
- 函数参数超过4个改用 Pydantic model
- 异步函数全部用 async/await，不要混用同步代码

## API 设计
- 路由用复数名词：/users, /orders
- 版本前缀：/api/v1/
- 响应模型必须定义 Pydantic schema，不要直接返回 ORM 对象
- 错误响应统一格式：{"detail": {"code": "USER_NOT_FOUND", "message": "..."}}

## Pydantic 规范
- 输入 schema 命名：UserCreateRequest, UserUpdateRequest
- 输出 schema 命名：UserResponse, UserListResponse
- 使用 model_validator 和 field_validator 做业务校验
- 不要在 validator 里做数据库查询

## 数据库操作
- Repository 模式隔离数据库操作
- Service 层不直接操作 Session
- 事务在 Service 层控制
- 查询结果用 scalars().all() 不要用 fetchall()

## 测试
- 每个 endpoint 必须有对应的集成测试
- 用 pytest-asyncio
- 测试数据用 factory_boy 生成，不要硬编码

## 安全
- 所有用户输入经过 Pydantic 校验
- SQL 操作全部参数化，禁止字符串拼接
- 文件上传校验文件类型和大小
- 敏感字段（密码、token）用 SecretStr 类型

注意这里我加了测试相关的规范。因为我发现如果不说，AI 生成代码时很少主动帮你生成测试，加了这条之后，我请它帮我写新 endpoint 时，它会顺带生成对应的测试文件。

---

前端 Vue 项目的 Rules

前端项目我用的是 Vue 3 + TypeScript，Rules 侧重点又不一样：

# Vue 3 前端项目规范

## 技术栈
- Vue 3.4+, TypeScript 5.x
- Vite 5 构建
- Pinia 状态管理
- Vue Router 4
- Element Plus UI
- Axios HTTP 客户端

## 组件规范
- 全部使用 Composition API + <script setup>
- 不用 Options API
- 组件文件名 PascalCase：UserCard.vue
- 业务组件放 src/views/，通用组件放 src/components/

## TypeScript 要求
- 禁用 any，实在不行用 unknown + 类型守卫
- Props 必须定义 interface，不用 defineProps 的泛型简写
- Emit 事件必须定义类型
- API 响应数据必须有对应的 interface 定义在 src/types/ 下

## 状态管理（Pinia）
- Store 文件命名：useUserStore.ts
- Action 处理异步操作和错误，不要在组件里写 try-catch 调 API
- 不要把 UI 状态（loading、dialog visible）放进 Store，组件内部管理

## 样式
- 优先用 Element Plus 的 CSS 变量做主题定制
- 业务样式用 scoped
- 公共样式变量统一放 src/styles/variables.scss
- 不要写内联 style，除非是动态绑定

## API 调用
- API 函数统一放 src/api/ 目录
- 按业务模块分文件：user.ts, order.ts
- 使用封装好的 request 实例，不要直接用 axios
- 接口参数和返回值都有 TypeScript 类型

## 生成代码附加要求
- 生成完整的 .vue 单文件组件，包含 template/script/style
- TypeScript 类型要精确，不要偷懒写 any
- 如果用到 Element Plus 组件，使用正确的组件名（el-button 不是 Button）

前端 Rules 有个我踩过的坑：不明确说"使用 Composition API"，AI 会随机给你生成 Options API，特别是在 Vue 2 数据占多数的训练集影响下。

---

把团队规范写进 Rules

这是我觉得 .cursorrules 最有价值的地方——它是团队规范落地的执行层。

我之前参与过很多"制定代码规范"的工作，结果都一样：文档写得很好，然后放在 Wiki 里吃灰。没人看，也没人执行。

.cursorrules 不一样。它是每次 AI 生成代码时都会生效的约束。团队里人用 AI 辅助的频率越高，这个文件的价值就越大。

我们团队的落地方式：

把 .cursorrules 提交进 Git 仓库。 这样所有人拉代码就自动有了规范，不需要单独同步文件。

在 Code Review 里加一条检查： "AI 生成的代码有没有符合 .cursorrules 的规范。" 这逼着大家去看 Rules 文件，也逼着大家更新它。

把 Rules 更新加进 Onboarding 流程。 新人入职第一天，让他把本地 Cursor 配置好，包括设置全局 Rules 和理解项目 .cursorrules。

---

我踩过的坑

Rules 文件不是越长越好。 我有段时间把所有规范都堆进去，结果文件超过 2000 字，AI 开始"选择性遵守"——因为上下文太长，它只处理部分规则。现在我只放最重要、最容易出错的规范，一般控制在 800 字以内。

不要用负面表述堆砌。 "不要用 A，不要用 B，不要用 C，不要用 D……" 这种写法效果差。换成正面表述："使用 X"，AI 更容易遵守。

定期更新。 技术栈变了、团队决策变了，.cursorrules 要跟着更新。我们把 Rules 更新加进了 Sprint Review，每两周看一次有没有需要改的。

全局 Rules 和项目 Rules 要区分。 我的全局 Rules 只有一条："代码注释和变量命名用英文。" 其他所有规范都在项目级别配置。不要把项目特定的东西放全局，会干扰其他项目。

---

一个具体的对比

配置前，我让 Cursor 生成一个用户查询接口，它给我：

@RestController
@RequestMapping("/user")
@RequiredArgsConstructor
public class UserController {
    
    private final UserService userService;
    
    @GetMapping("/{id}")
    public ResponseEntity<UserVO> getUser(@PathVariable Long id) {
        return ResponseEntity.ok(userService.getById(id));
    }
}

用了 Lombok，返回了 ResponseEntity 而不是我们统一的 Result<T>，路径用了单数。

配置后，同样的需求：

@RestController
@RequestMapping("/users")
public class UserController {
    
    private final IUserService userService;
    
    public UserController(IUserService userService) {
        this.userService = userService;
    }
    
    /**
     * 根据ID查询用户信息
     *
     * @param id 用户ID
     * @return 用户详情
     */
    @GetMapping("/{id}")
    public Result<UserVO> getUser(@PathVariable Long id) {
        UserVO userVO = userService.getUserById(id);
        return Result.success(userVO);
    }
}

构造器注入、无 Lombok、Result<T> 包装、Javadoc 注释、路径用复数。这才是我想要的。

---

几个高级用法

可以在 Rules 里引用文件结构。 比如：

## 项目结构
- 所有工具类放 src/main/java/com/example/util/
- 常量统一放 src/main/java/com/example/constant/
- 不要在 Controller 层新建 util 类

这样 AI 生成新文件时会放到正确的位置。

可以描述反模式。 把你们团队历史上踩过的坑写进去：

## 历史教训（避免重蹈覆辙）
- 不要用 String 类型存储枚举值，统一用枚举类
- 时间字段用 LocalDateTime，不要用 Date 或 Timestamp
- 金额字段用 BigDecimal，严禁用 double/float

可以加上 Context 描述。 让 AI 理解你的业务：

## 业务背景
这是一个 B2B SaaS 系统，核心概念：
- Tenant：租户，多租户隔离
- 所有数据查询必须带 tenantId 条件
- 不要生成不带 tenantId 过滤的批量查询

这个 Context 描述配合上去之后，AI 生成代码会自动考虑多租户场景，不用每次都在 Prompt 里说。

---

.cursorrules 这个文件，我觉得是 Cursor 功能里被严重低估的一个。很多人花时间去研究各种 Prompt 技巧，但忘了先把基础的上下文配置好。

基础配好之后，AI 补全的准确率能提升不少。更重要的是，团队里不同人用 AI 生成的代码风格会更接近，减少 Code Review 里那些"这不符合规范"的来回。

把你们团队的规范落进 .cursorrules 吧，这比 Wiki 文档管用多了。