旧的方式已经在走下坡路

很多教程还在讲 .cursorrules 文件。这个文件放在项目根目录，全局生效，写一堆规则进去。

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

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

现在是切换的好时机。

图：.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<T>，不用 ResponseEntity<Object>：
- 成功：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
---

# 测试编写规范

## 框架