摘要：本文详细介绍了 Cursor Rules（.cursorrules）的配置与使用，这是一个项目级的 AI 指令文件，能够显著提升 AI 生成代码与项目规范的一致性。文章从背景问题出发，解释了 Rules 的工作原理，提供了 Java Spring Boot、Python FastAPI、JavaScript/TypeScript 以及项目架构速览四种实用模板，并分享了按语言区分规则、结合不同 AI 模型等进阶用法，帮助开发者一次性配置，让 AI 在后续所有代码生成中都能遵循项目约定。

先交代一下背景

用了 Cursor 两个月后，我发现一个问题——

同一个项目里，AI 生成代码的质量差异很大。写工具类的时候质量很高，但一涉及到项目特有的架构约定，AI 就开始乱来了。

比如我项目里统一用 Result 类包装返回值、异常用全局拦截器处理、数据库字段用了逻辑删除……这些东西 AI 不知道。所以它生成的代码经常自作主张地直接 return user 而不是 return Result.success(user)，直接捕获异常而不是抛出去让拦截器处理。

后来我发现了 Cursor 的一个功能，叫 Rules（或者叫 .cursorrules）。这玩意能帮你告诉 AI：我们这个项目有什么约定、什么禁止、什么必须用。

用了之后效果立竿见影——AI 生成的代码和项目风格匹配度从 60% 提高到 95% 以上。

今天就把这东西怎么配、配什么，完整写出来。

Cursor Rules 是什么

简单说，Cursor Rules 是一个 项目级 AI 指令文件。你把它放到项目根目录，命名为 .cursorrules，Cursor（和 Windsurf，如果是 .windsurfrules）每次生成代码的时候，会把 Rules 文件的内容作为对话上下文注入给 AI。

你可以理解成——你给 AI 发了一份「项目员工手册」，上面写清楚了你的项目规范。AI 每次干活前，先读一遍手册，然后再开工。

这个文件的作用范围是整个项目，不是单个文件。所以一次配置，所有生成都受益。

怎么配置

在项目根目录创建 .cursorrules 文件：

your-project/
├── .cursorrules      ← 新建这个文件
├── src/
├── pom.xml
└── ...

然后往里面写内容，格式就是纯文本。下面是几个实用模板，你直接抄就行。

模板一：Java Spring Boot 项目专用

你是一个 Java 后端开发专家，精通 Spring Boot 3.x。
项目约束
所有 Controller 返回 Result<T> 统一封装
Service 层必须 @Transactional，不能用 SqlSession 手动提交
异常全部 throw 出去，由 GlobalExceptionHandler 统一处理
数据库逻辑删除用 @TableLogic，不要物理删除
RESTful 风格：名词复数路由，GET 查/POST 增/PUT 改/DELETE 删
数据库字段名用下划线（snake_case），Java 属性用驼峰（camelCase）
禁止在 Controller 里写业务逻辑
输出规范
代码注释用中文，简洁，每段逻辑只加一条注释
生成 Java 文件时包含 import 语句
Controller 层使用 @Valid + @Validated 做参数校验
Service 层方法签名不要 throws Exception

把这套规则放进 .cursorrules 后，AI 生成的 Controller 会自动：

@PostMapping("/users")
public Result<User> createUser(@Valid @RequestBody UserCreateRequest request) {
    User user = userService.createUser(request);
    return Result.success(user);  // 自动用 Result 包装
}

而不是以前那种：

@PostMapping("/addUser")
public String addUser(@RequestBody UserCreateRequest request) {
    // 直接在 Controller 里写业务逻辑
    userMapper.insert(request.toUser());
    return "ok";
}

差距就是这么大。

模板二：Python + FastAPI 项目专用

你是一个 Python 后端开发者，精通 FastAPI。
项目约束
所有响应用 Pydantic BaseModel 定义 Schema
数据库操作用 SQLAlchemy 2.0 async session
密码用 bcrypt 加密
JWT token 认证，从 header 取出 token 后解析 user_id
错误码统一用自定义的 AppException 抛出
日志用 structlog 结构化日志
输出规范
代码注释用中文，一句一注释
类型注解必须完整
所有 API 路径前加 /api/v1/
每个 API 函数添加 summary 和 description 参数

看，这就是一份员工手册。AI 每次生成都按这个规范走，不会有任何偏差。

模板三：通用 JavaScript/TypeScript 项目

你是一个前端/Node.js 开发者，精通 TypeScript。
项目约束
函数用箭头函数，不要 function 关键字
所有接口返回类型用 axios 泛型定义
组件文件用 PascalCase，工具函数文件用 camelCase
React 组件用函数组件 + hooks，不用 class 组件
不允许使用 any 类型
不允许使用 var
输出规范
import 按顺序：第三方库 → 内部模块 → 样式
组件 props 用 interface 定义，不要 inline
状态管理用 zustand，不用 redux
异步操作一律用 async/await，不用 .then

模板四：项目架构/技术栈速览（适合接手老项目）

## 项目技术栈
- Spring Boot 2.7.3 + MyBatis Plus 3.5.2
- MySQL 8.0 + Redis 6.x + RabbitMQ
- Maven 多模块：common / dal / service / web
核心架构约定
dal 层：只操作数据库，不写业务逻辑
service 层：业务逻辑，事务边界在这里
web 层：只做参数校验和结果包装
跨模块调用必须走 Service 接口，不要直接依赖 Mapper
常见模式
分页查询：用 PageHelper.startPage() + PageInfo 包装
缓存：用 @Cacheable 注解，缓存 key 格式为 "prefix:id"
异步：用 @Async 注解，自定义线程池配置

接手老项目的时候放一个，AI 生成的东西直接和项目的技术栈匹配。不用你反复纠正。

一些进阶用法

按语言区分规则

如果项目是前后端混合，可以在 .cursorrules 里分类写：

## 处理 Java 代码时
(Spring Boot 规范)
处理 JavaScript 代码时
(React 规范)

Cursor 会根据你当前编辑的文件类型自动匹配对应的规则。

结合 Claude 和 GPT 的限制

不同模型对 Rules 文件的支持程度不同：

- Cursor 内置模型：完全支持

- Claude 3.5 Sonnet：高度兼容

- GPT-4：基本兼容

如果发现 AI 没有严格遵守 Rules，可以手动说一句：「记住项目根目录的 .cursorrules 文件」，它就会重新加载。

总结

.cursorrules 的本质是什么？

它不是你给 AI 的约束——是你给 AI 的上下文。

你的项目有自己的技术栈、编码规范、架构约定，AI 刚进来看不到这些。.cursorrules 就是告诉它：「你好，这个项目是这样的，请按这种方式干活。」

我建了个自己常用的模板库项目，每次新建项目直接拷贝一份对应的 Rules 进去，后续 AI 生成代码的质量稳得一批。

你也试试，把项目规范写进去，然后观察 AI 生成代码的变化——你会觉得自己换了一个 AI。

---

下一篇预告：AI 写 SQL——把需求描述丢进去，生产级SQL就出来了

私信回复「666」，一次性领走：

面试宝典：Java 高频考点速查表、HashMap/ConcurrentHashMap 源码笔记、JVM 调优案例、Spring Boot 面试 50 问

AI 编程工具箱：Cursor/Copilot/Codex 六工具对比表、10 个 Prompt 模板、Debug 万能公式、Cursor 速查手册、AI 图片生成入门、30+ 效率工具包

一份资料包，两个专栏都能用。「唠点键盘之外的」，只讲干货。