Cursor Rules 深度玩法：从全局配置到项目级规则，让 AI 真正理解你的项目
用 Cursor 写了一段时间代码，你可能已经习惯了这种“反复纠正”的体验：AI 帮你写了一段 Ja va 代码——用了 Lombok 的 @Data，但你们项目禁止用 Lombok；AI 生成了 SQL——用了 SELECT *，但你们 DBA 明确禁止；AI 帮你建了个表——没加 create_time 和 update_time，不符合你们的建表规范；AI 写了个前端组件——用了 Class 组件，但你们全是函数式 + Hooks。每次都要纠正一遍，下次开新会话又忘了。
问题的本质在于：你的项目有一套“隐性知识”。这些知识包括技术栈偏好（Spring Boot 3.x / React 18 / Vue 3）、代码规范、数据库规范、团队约定和业务约束。而这些知识要么在你的大脑里（会忘记，会遗漏），要么在散落的文档里（AI 看不到），要么是口头约定（新人不知道，AI 更不知道）。Cursor Rules 的价值，恰恰是把这些“隐性知识”变成“显性配置”——让 AI 每次对话都自动加载，不用重复说，也不会忘记。
一、Cursor Rules 全景图：先搞清楚有哪些规则
Cursor 的规则体系不是一个文件那么简单，它有四种来源，各有各的适用场景。首先是 User Rules（用户规则），作用域是所有项目，配置位在 Cursor 设置界面，特点全局生效、不跟项目走，适合个人偏好、语言习惯和通用编码风格。其次是 Project Rules（项目规则），作用域是单个项目，配置位在 .cursor/rules/*.mdc，特点跟 Git 走、团队共享，适合技术栈规范、数据库规范、业务约束。然后是 Team Rules（团队规则），作用域是团队或组织，配置位在团队管理后台，Team/Enterprise 计划可用，适合公司级编码标准和安全规范。最后是 AGENTS.md（袋里规则），作用域是单个项目，配置位在项目根目录，纯 Markdown，无需 frontmatter，适合轻量级项目快速上手。
加载优先级是：User Rules → Team Rules → Project Rules。冲突处理方面，后加载的覆盖先加载的。
你可能在网上看到两种写法，别搞混了。旧版（已废弃，但仍兼容）是在项目根目录放一个.cursorrules 文件，所有规则塞一起。新版（推荐）是在项目根目录建 .cursor/rules/ 文件夹，每个规则一个文件。比如 ja va-backend.mdc 负责 Ja va 后端规范，database.mdc 负责数据库规范，git-commit.mdc 负责 Git 提交规范，等等。推荐新版的原因很明显：按场景拆分、单个文件更聚焦、支持四种加载模式、文件匹配模式精准控制作用范围、团队协作时 diff 更清晰，而且不会一个文件几千行看不过来。
二、四种加载模式详解——这是 Rules 最核心的设计
每个.mdc 文件的开头有一段 YAML frontmatter，它决定了这条规则什么时候生效。
Always Apply（始终生效）：无论你在写什么代码，这些规则都应该生效。比如代码风格、语言偏好、安全底线。但注意，Always Apply 的规则每次对话都会消耗 token，放太多东西就是白白烧钱。黄金法则是：只放“无条件适用”的规则，控制在 200 行以内（约 600-800 tokens），不要把 Ja va 规范放在 Always Apply（写前端时完全浪费），适合放语言偏好、安全底线、输出格式要求。
Auto-attached（自动附加）：当你打开或编辑匹配 globs 模式的文件时，自动加载。这是最推荐的模式——精准投递，不浪费 token。比如 Ja va 后端可以配置 ["src/main/ja va/**/*.ja va", "pom.xml"]，React 前端可以配置 ["src/**/*.tsx", "src/**/*.ts", "package.json"]，数据库相关可以配置 ["**/*.sql", "**/mapper/**/*.xml", "**/migration/**"]。
Agent-decided（AI 自主判断）：你不确定该匹配哪些文件，但描述了场景，让 AI 自己判断要不要加载。关键在于 description 要写得足够明确。比如不要把 description 写成模糊的“数据库规则”，而要写成“数据库设计和 SQL 编写规范，当涉及建表、写 SQL、数据库迁移、MyBatis XML 编写时使用”，这样 AI 看到你在写 SQL 就会主动加载。
Manual（手动引用）：没有 description、没有 globs、alwaysApply 为 false，只能手动触发。适用场景是不常用但偶尔需要的规则，使用时在对话中 @rules/performance-checklist 手动引用。
三、由浅入深——从你的第一条 Rule 开始
入门：User Rules（全局配置）。打开 Cursor → Settings → Rules，这里可以写全局规则。推荐的配置包括：始终用中文回复，使用中文变量注释但代码本身用英文，不要主动添加我没要求的功能，生成代码后简要说明改了什么，禁止在代码注释中解释修改内容。User Rules 的定位是个人偏好——跟着你走，不跟项目走。适合放语言偏好、交互习惯、通用编码习惯。不适合放项目技术栈、团队规范、临时指令。
基础：AGENTS.md（最快上手）。如果你觉得 .mdc 文件的 frontmatter 太麻烦，可以先用 AGENTS.md——纯 Markdown，零学习成本。在项目根目录创建 AGENTS.md，写上技术栈、代码规范、数据库规范、禁止事项等。AGENTS.md 的定位是轻量、快速、够用，适合个人项目或小团队快速上手。和 .cursor/rules/ 相比，AGENTS.md 的优点是零学习成本、一个文件搞定，缺点是没有条件加载（所有规则全量加载）、不能按文件类型匹配。
进阶：Project Rules（分场景精准配置）。这是真正发挥 Rules 威力的地方。以一个全栈项目为例，完整的 Rules 目录结构可以是：.cursor/rules/ 下分 always/、backend/、frontend/、workflow/、devops/ 等子目录，每个目录下放对应的 .mdc 文件，用 globs 或 description 精准控制作用范围。
四、实战场景一：开发类 Rules
Ja va Spring Boot 后端规范的核心内容很多。分层架构方面，Controller 只做参数校验和调用 Service，禁止写业务逻辑；Service 负责业务逻辑编排和事务管理；Mapper 继承 BaseMapper。统一返回格式方面，所有 API 返回Result，包含 code、message、data。异常处理方面，业务异常用 throw new BusinessException，全局捕获用 @RestControllerAdvice。命名规范方面，类名大驼峰、方法名小驼峰、常量全大写下划线。禁止事项包括 System.out.println、硬编码魔法数字、直接拼接 SQL 字符串、在循环中做数据库查询、@Autowired 字段注入、返回 null 集合等。
React + TypeScript 前端规范也有完整的体系。组件规范方面，使用函数式组件 + Hooks，禁止 Class 组件，文件名 PascalCase，每个组件一个文件不超过 200 行，Props 必须定义 interface，使用 named export。Hooks 使用规则方面，useState 管简单状态，useReducer 管复杂状态，useMemo/useCallback 仅在性能瓶颈时使用，useEffect 依赖数组必须完整。TypeScript 规范方面，strict 模式开启，禁止 any，接口用 interface，类型别名用 type。样式方面，使用 Tailwind CSS，响应式 mobile-first。禁止事项包括 var、index 作为 key、在 useEffect 回调中直接用 async、!important、inline style。
五、实战场景二：数据库类 Rules
数据库规范是很多团队最容易忽略的——直到某天 DBA 怒了。 数据库设计规范中，建表规范要求所有表必须有id（BIGINT UNSIGNED AUTO_INCREMENT）、create_time、update_time、is_deleted 字段。命名规范方面，表名小写下划线带业务前缀，字段名小写下划线，索引命名 idx_表名_字段名。字段类型选择方面，字符串用 VARCHAR(n) 按实际最大长度设置，数字用 BIGINT UNSIGNED 或 DECIMAL，时间用 DATETIME 不用 TIMESTAMP。
SQL 编写规范要求禁止 SELECT *，WHERE 条件字段必须有索引，JOIN 不超过 3 个表，分页查询必须有 ORDER BY，大表查询必须有 LIMIT。索引规范方面，单表索引不超过 5 个，联合索引遵循最左前缀原则，区分度低的字段不建索引。禁止事项包括在代码中拼接 SQL、不带 WHERE 的 UPDATE/DELETE、在循环中执行 SQL、在大表上用 LIKE '%xxx'、在线上直接执行 DDL。
如果你配了数据库 MCP（比如 MySQL、Doris、PostgreSQL），可以写一条专门的 Rule。安全底线方面，禁止执行 DROP TABLE/DATABASE，禁止不带 WHERE 的 DELETE/UPDATE，禁止修改线上数据库表结构，查询必须加 LIMIT（默认 100，最大 1000）。查询习惯方面，先查表结构再写查询，大表先 COUNT 估算数据量，复杂查询先 EXPLAIN 看执行计划。
六、实战场景三：全局 vs 项目级——怎么分配规则？
这是很多人纠结的问题：哪些规则放全局？哪些放项目级？ 全局规则只放“跟项目无关”的个人偏好。推荐放全局的包括：语言偏好、交互风格、安全底线、输出格式、通用习惯。不要放全局的包括：技术栈规范、数据库规范、业务逻辑、框架特定配置。 项目级规则的组织策略有三种。策略一按技术栈分，适合小项目，比如backend.mdc、frontend.mdc、database.mdc、git.mdc。策略二按职责分，适合中大项目，比如 architecture.mdc、coding-style.mdc、security.mdc、database.mdc、testing.mdc、api-design.mdc、deployment.mdc。策略三按模块分，适合 Monorepo，比如 common.mdc 和 modules/ 下的 user-service.mdc、order-service.mdc、payment.mdc。
七、Rules vs Skills vs Superpowers——三种体系的区别
你可能还听过 Cursor Superpowers 和 Skill，它们和 Rules 到底什么关系？ Rules 是持久化的编码约束和规范，解决“AI 生成的代码不符合我的规范”的问题。Skills 是可复用的工作流程封装，解决“每次都要重复描述工作流程”的问题。Superpowers 是社区维护的预置 Agent 框架，提供开箱即用的高级开发工作流。 三种体系是互补的，不是替代的。一个典型的配置组合是：Rules 作为约束层（比如“所有 Ja va 代码必须遵循阿里巴巴编码规约”），Skills 作为流程层（比如“当做 Code Review 时，按 P0-P3 优先级检查”），Superpowers 作为能力层（比如“用 TDD 模式开发”）。 怎么选？取决于你的需求阶段。第一阶段刚用 Cursor，先配 Rules，一个 AGENTS.md 或 3-5 条 Project Rules 就够了。第二阶段用了一两个月，Rules 稳定了，开始用 Skills 封装重复工作流。第三阶段重度用户，Rules + Skills 都有了，尝试 Superpowers 解锁高级 Agent 能力。核心原则：不要一上来就搞一套复杂的配置，先用最简单的方式解决最痛的问题，再逐步迭代。八、Rules 的优缺点——不吹不黑
优点方面：零学习成本上手，写个 AGENTS.md 放项目根目录 5 分钟搞定；精准控制，Auto-attached 模式可以按文件类型精确匹配；团队可共享，.cursor/rules/ 跟 Git 走，新人 clone 项目就自动有规范；与 IDE 深度集成，比对话中反复提示更可靠；版本可追溯，规范变更可以 diff、review、rollback。 缺点方面：不是 100% 强制执行，Rules 是“强烈建议”而非“硬性约束”，解决方案是关键词用“禁止”而非“尽量不要”；Token 消耗，Always Apply 的规则每次对话都消耗 token，解决方案是合理使用四种加载模式；规则冲突，User Rules 和 Project Rules 可能冲突，解决方案是保持规则间无交叉，定期 review；调试困难，不确定某条规则是否被加载，解决方案是在对话中问 AI“你当前加载了哪些规则？”；维护成本，项目演进后规则可能过时，解决方案是每月 review 一次。九、完整实战案例：我的真实项目配置
以一个日常维护的 Ja va 后端项目为例，User Rules 全局配置包括：始终用中文回复，始终不要开启 plan 模式直接做，禁止使用子袋里全部使用当前 agent，改完代码后简要说明改动点。 Ja va 后端项目 Rules 目录结构为：ja va-backend.mdc（Auto-attached: *.ja va, pom.xml）核心内容为分层架构、命名规范、统一返回、异常处理；database.mdc（Agent-decided: SQL/数据库相关）核心内容为建表规范、SQL 规范、索引策略；mcp-safety.mdc（Agent-decided: MCP 数据库操作）核心内容为禁止 DROP、必须 LIMIT、先 EXPLAIN；git-commit.mdc（Agent-decided: Git 操作）核心内容为 feat/fix/docs 类型、中文描述、72 字符限制。
效果对比很明显：没有 Rules 时新建 Controller 可能写业务逻辑在里面，有 Rules 后严格只做参数校验；建表语句忘了 create_time/update_time，有 Rules 后自动带上所有必备字段；写 SQL 可能 SELECT *，有 Rules 后列出具体字段加 LIMIT。
