你的 Cursor 还在靠缘分猜你的代码规范？Rules 配置完，AI 像换了个人

网乱世

154人浏览 · 2026-07-19 16:19:22

网乱世 · 2026-07-19 16:19:22 发布

旧的方式已经在走下坡路
很多教程还在讲 .cursorrules 文件。这个文件放在项目根目录，全局生效，写一堆规则进去。

问题在于它是一个单文件，不能按场景激活，不能分模块管理。你的项目有 Java 后端、有测试、有数据库迁移脚本，这三块的规范完全不同。一个文件全塞进去，既超长又难维护，AI 读取的时候也容易被稀释。

Cursor 的新系统是 .cursor/rules/ 目录 + .mdc 文件，每个 .mdc 文件对应一个规则模块，支持 4 种激活类型。.cursorrules 还没有强制废弃，但 Cursor 官方已经在引导用户迁移，新功能只加在 .mdc 体系上。

现在是切换的好时机。

Cursor Rules 目录结构与 4 种激活类型关系图
图：.cursor/rules/ 目录结构与 4 种激活类型的对应关系

4 种激活类型，用错了比没配还糟
这里有个大多数人绕不过去的坑：不是配了 Rules 就有效，是配对了激活类型才有效。

Cursor 的 .mdc 文件支持 4 种激活方式，官方界面里叫 Rule Type：

Always（全局生效）
打开任何文件都加载，适合全项目通用的强制规范。

适合放什么：禁用 System.out.println、统一返回体格式、Git commit 规范、所有文件的 package 命名惯例。

注意：别把太多规则塞进 Always，它每次都消耗 context 窗口。超过 50 行，建议拆出去。

Auto Attached（文件匹配自动触发）
用 glob 模式匹配文件路径，只有打开匹配的文件时才加载。这是用得最多的类型。

配置示例：

**/.java → 触发 Java 规范
**/.go → 触发 Go 规范
/test/ → 触发测试规范
/migration/ → 触发数据库迁移规范
适合放什么：各技术栈的语言规范、框架用法惯例、文件结构规定。

Agent Requested（AI 自主决定）
AI 根据当前上下文判断要不要加载这条规则，你给这个规则写一个 description，AI 读 description 决定是否引入。

适合放什么：可选的、特定场景才需要的规则，比如「使用 Reactor 响应式编程时的规范」、「接入第三方 SDK 时的注意事项」。

Manual（手动 @引用）
只有你显式在 chat 里 @这个规则文件，AI 才加载。

适合放什么：性能优化检查清单、安全审计要点、Code Review 标准——这些不是写代码时常用的，是特定任务才需要的。

推荐配比：80% Auto Attached + 10% Always + 10% Manual。

Agent Requested 初看很智能，但实测下来，AI 的判断不稳定，有时候该用的没加载，不该用的加载了。生产项目里尽量用 Auto Attached，明确匹配，不靠推理。

动手：从创建第一个 .mdc 文件开始
先建好目录结构。在项目根目录：

mkdir -p .cursor/rules
创建方式一（GUI）： Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows），搜索 New Cursor Rule，填入名称和类型，Cursor 会自动在 .cursor/rules/ 下创建文件。

创建方式二（CLI）：在 Cursor 的 chat 里输入 /rules（2026-01-08 新增的命令），可以直接在对话中新建和编辑规则。

.mdc 文件的结构很简单：

description: 这条规则的说明（Agent Requested 类型时 AI 靠这个决定是否加载）
globs: **/*.java
alwaysApply: false

规则标题

规则内容，用自然语言写，AI 能读懂即可。
可以加代码示例，可以加反例。
alwaysApply: true 等同于 Always 类型；globs 有值且 alwaysApply: false 等同于 Auto Attached；两个都空 + 有 description 等同于 Agent Requested；手动创建但不写 globs 就是 Manual。

Java Spring Boot 项目实战模板
以下是码哥在实际 Spring Boot 3.x 项目里用的规则，拿走即用，按你的项目实际情况改。

核心规范文件：java-spring.mdc

description: Java Spring Boot 核心编码规范
globs: “**/*.java”
alwaysApply: false

Java Spring Boot 3.x 编码规范

技术栈版本

Java 21，使用 Virtual Threads
Spring Boot 3.3.x
Maven 依赖管理

禁止行为

禁止使用 System.out.println，统一用 @Slf4j 的 log.info/warn/error
禁止直接 throws Exception，必须抛出具体业务异常
禁止在 Service 层返回 ResponseEntity，那是 Controller 层的事
禁止修改 pom.xml 中的 Spring Boot Parent 版本，除非明确指示
禁止生成 // TODO 占位注释，要么给完整实现，要么不生成
禁止使用已标记 @Deprecated 的 API

统一返回体

所有接口返回 Result，不用 ResponseEntity：

成功：Result.success(data)
失败：Result.fail(ErrorCode.XXX)

异常处理

Service 层抛出继承 BaseException 的业务异常
统一由 @RestControllerAdvice 的 GlobalExceptionHandler 处理
不在 Controller 层写 try-catch

包结构（严格遵守）

controller：只处理请求参数校验和返回体封装
service / serviceImpl：业务逻辑
repository：数据访问，只用 JPA Repository 接口
domain/entity：数据库实体，用 @Entity 注解
dto：接口入参 DTO，用 @Validated 做参数校验
vo：接口出参 VO

命名规范

类名 PascalCase，方法/字段 camelCase
接口方法动词开头：get/create/update/delete/query
常量 UPPER_SNAKE_CASE，全部放 constant 包下的 Constants 类

RESTful 风格

GET 查询，POST 创建，PUT 全量更新，PATCH 部分更新，DELETE 删除
路径用小写连字符：/api/v1/user-orders，不用下划线
测试规范文件：testing.mdc

description: 单元测试和集成测试规范
globs: “/test//*.java”
alwaysApply: false

测试编写规范

框架

单元测试：JUnit 5 + Mockito
集成测试：Spring Boot Test + Testcontainers（MySQL/Redis）

命名

方法名：given_当前状态_when_执行操作_then_期望结果
例：given_userExists_when_getUserById_then_returnUserVO

强制要求

Service 层方法必须有对应单元测试
测试方法不得共享状态，每个测试独立可运行
Mock 外部 HTTP 调用，不发真实网络请求
禁止 @Autowired 注入，用构造函数注入方便 Mock
使用后实际效果：配置前，Cursor 生成的代码里 System.out.println 出现频率约 30%，异常处理用原始 try-catch 的比例超 60%。配置后，这两个问题基本消失，需要手动干预的代码量大概少了 40-50%。这是在一个 3 人团队的实际项目里统计的，样本不大，但方向是对的。

Go 项目实战模板
Go 的规则比 Java 简单，但有几个地方 AI 特别容易犯错。