你花钱订阅了Cursor，结果AI生成的代码风格混乱、不守规范、每次都要重新解释项目结构——问题不在AI，在你没写Rules。

先说结论

Cursor Rules 是控制AI行为的规则系统。没有它，AI像个每次轮岗的实习生——你得反复解释项目规范。有了它，AI变成了资深同事，开口就知道该用什么风格、遵守什么架构、避开什么坑。

为什么你需要 Cursor Rules

大多数人用 Cursor 的方式，只发挥了30%的潜力。

你在Chat里说"帮我写个登录接口"，AI给你一段代码。你说"不对，我们项目用Kotlin不是Java"，它道歉然后重写。你说"数据库操作要走Repository层"，它又道歉。每次对话都在重复同样的纠正。

这就是没有 Rules 的代价——你的项目规范全靠口头传达，AI的上下文窗口一关就全忘了。

有人会说"我有AGENTS.md啊"。没错，AGENTS.md定义的是跨工具的通用原则（“写清晰的代码"“遵循SOLID”）。但Cursor Rules控制的是Cursor专属行为——用什么语言、什么框架、什么命名规范、哪些文件不能碰。两者是互补关系，不冲突。

规则系统演变：从单文件到目录

Cursor的规则系统经历过一次大升级：

旧版的问题是所有规则挤在一个文件里，没法按场景分类。新版用目录结构，每个 .mdc 文件是一条独立规则，可以精确控制触发条件。

迁移很简单：把旧 .cursorrules 的内容移入 .cursor/rules/global.mdc，加上frontmatter就行。

MDC 文件格式详解

.mdc 文件是Markdown + YAML frontmatter的组合：

1
2
3
4
5
6
7
8
9

---
description: 规则说明（AI靠这个判断是否需要加载）
globs: **/*.tsx
alwaysApply: false
---

# 规则标题

规则内容，用Markdown格式书写。

三个frontmatter字段决定了规则的行为：

• description：给AI看的"说明书”。Agent Requested类型靠它判断是否加载
• globs：文件匹配模式。Auto Attached类型靠它触发
• alwaysApply：设为true就是Always类型，始终加载

四种规则类型（核心）

这是整个系统最关键的部分。四种类型对应四种触发方式，用对了事半功倍，用错了形同虚设。

Always：全局常驻

alwaysApply: true，每次对话都加载。

适合放什么？全局代码风格、语言偏好、项目架构概览。

1
2
3
4
5
6
7
8
9

---
description: 全局代码规范
alwaysApply: true
---

# 代码规范
- 使用TypeScript，禁止any
- 组件用PascalCase，工具函数用camelCase
- 注释用英文

注意：Always规则会占用AI的上下文窗口。放太多Always规则，AI留给实际代码的空间就少了。全局规则控制在3-5条以内。

Auto Attached：文件触发

globs 匹配时自动加载。你编辑 .tsx 文件，React相关的规则自动生效。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

---
description: React组件开发规范
globs: **/*.tsx
alwaysApply: false
---

# React规范
- 组件用函数式，不用class
- Props用interface定义，不用type
- 样式用Tailwind，不用CSS Modules

最适合按文件类型区分规则的场景：TypeScript有TypeScript的规范，Python有Python的规范，互不干扰。

Agent Requested：AI自判断

alwaysApply: false 且没有 globs，AI根据description判断是否需要加载。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
description: 数据库迁移和ORM操作规范。当涉及数据库schema变更、
  migration文件编写、Prisma/TypeORM操作时使用。
globs:
alwaysApply: false
---

# 数据库规范
- 迁移文件必须可回滚
- 禁止直接修改生产环境schema
- 字段命名用snake_case

这类规则的关键在description写得好不好。太笼统（“数据库相关规则”）AI可能不加载；太具体（列了一堆关键词）反而有效。

Manual：手动触发

用户在Chat中 @规则名 手动激活。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

---
description: 发布流程检查清单。部署到生产环境前手动激活。
alwaysApply: false
---

# 发布检查
- [ ] 所有测试通过
- [ ] CHANGELOG已更新
- [ ] 环境变量已配置
- [ ] 数据库迁移已测试

适合低频但重要的场景：发布流程、数据迁移、紧急修复。

实用规则模板（直接复制使用）

代码风格规则

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

---
description: 项目代码风格统一规范
alwaysApply: true
---

# 代码风格
- 缩进：2空格（前端），4空格（Python）
- 字符串：单引号（JS/TS），双引号（Python）
- 分号：不加分号（JS/TS）
- 命名：组件PascalCase，变量camelCase，常量UPPER_SNAKE_CASE
- 函数不超过30行，超过就拆
- 每个函数必须有JSDoc/docstring

安全规则

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
description: 安全编码规范，防止常见漏洞
alwaysApply: true
---

# 安全规范
- 禁止硬编码密钥、密码、Token，用环境变量
- SQL查询必须用参数化，禁止字符串拼接
- 用户输入必须校验和转义
- API接口必须有认证中间件
- 敏感数据（密码、Token）禁止出现在日志中

测试规则

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
description: 测试编写规范。涉及单元测试、集成测试时使用。
alwaysApply: false
---

# 测试规范
- 测试文件和源文件同目录，命名 xxx.test.ts
- 用 describe/it 结构，描述行为而非实现
- mock外部依赖，不mock被测函数
- 每个测试只验证一个行为
- 测试覆盖率不低于80%

Git 规则

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
description: Git提交规范
alwaysApply: true
---

# Git规范
- commit message用英文，格式：type(scope): description
- type: feat/fix/refactor/docs/test/chore
- scope: 模块名（auth/api/ui/db）
- 每个commit只做一件事
- 禁止提交 .env、node_modules、dist

创建规则的三种方式

方式一：直接建文件

在 .cursor/rules/ 目录下创建 .mdc 文件，写好frontmatter和内容。最直接，适合已有明确想法的情况。

方式二：Chat命令

在Cursor Chat中输入 /rules，会打开规则编辑器。适合快速创建单条规则。

方式三：AI生成

在Chat中输入 /Generate Cursor Rules，AI会分析你的项目结构和现有代码，自动生成一套规则。适合项目初期快速起步。

我的建议：先用方式三生成初始规则，再用方式一逐条精调。AI生成的规则通常80%可用，但剩下20%需要你根据项目实际情况修正。

踩坑经验

坑1：规则太多导致AI混乱

我见过有人写了20多条Always规则。结果AI的上下文窗口被规则塞满，留给实际代码的空间都不够了。AI开始"选择性失忆"，有时遵守规则有时不遵守，表现极不稳定。

正确做法：Always规则不超过5条。其余用Auto Attached或Agent Requested按需加载。

坑2：规则互相冲突

一条规则说"用class组件"，另一条说"用函数式组件"。AI遇到这种情况会随机选一个，或者两头讨好写出四不像。

正确做法：定期检查规则之间有没有矛盾。按文件类型拆分规则，减少交叉。

坑3：glob匹配不生效

写了个 globs: *.ts，结果TypeScript文件没有触发规则。原因是glob需要完整的路径匹配模式，*.ts 不匹配 src/utils/helper.ts。

正确做法：用 **/*.ts 匹配所有子目录下的TypeScript文件。

坑4：description写得太模糊

Agent Requested类型完全依赖description来判断是否加载。如果你写"代码规范"，AI大概率不会加载——太笼统了。

正确做法：在description中明确列出触发场景。比如"API接口设计规范。当编写REST API路由、中间件、请求/响应处理时使用。"

与 AGENTS.md 的关系

两者不是替代关系，而是互补：

实际项目中的组合方式：AGENTS.md放"我们要做什么"（产品方向、架构原则、技术选型），.cursor/rules放"具体怎么做"（代码风格、框架规范、文件结构）。

两者写得好，AI的表现会从"实习生"进化到"资深同事"——它不只是能写代码，而是能写你的项目风格的代码。