Cursor Rules 开发实践指南

AI 辅助编程最容易出现幻觉和过时信息的问题。AI 可能生成看似合理但实际错误的代码,或使用已废弃的 API 和最佳实践。通过 Cursor 提供的 Rules 功能,可以规范 AI 辅助开发流程,有效避免这些问题,提升开发效率和代码质量。

本文基于 Cursor v1.0.0 版本

什么是 Cursor Rules?

Cursor Rules 是专门设计用于规范 AI 如何生成代码、提供建议和进行代码补全等行为的规则体系。提供两种作用域:

  • User Rules:全局环境,在设置中定义,始终应用,适合设置简单的语言回复规范或个人偏好
  • Project Rules :以项目为粒度,定义在项目代码根目录的 .cursor/rules 中,适合设置详细的项目规则

User Rules

User Rules 设置在 Cursor Settings → Rules 面板中:

笔者设置了两条基础规则:

  1. 回复语言设置Always respond in 中文,LLM 所有回复变成中文
  2. 生成代码设置请记住,代码是写给人看的,只是机器恰好可以运行,有效提升 LLM 生成代码的可读性

Project Rules

Project Rules 直接在代码 repo 根目录创建 .cursor/rules 文件夹,然后创建 *.mdc 文件,写入规则内容即可,内容格式为 Markdown:

与 User Rules 的区别在于,每条 Project Rule 可以独立设置应用规则:

目前包含四种应用规则:

Rule Type Description
Always 始终应用
Auto Attached 需要配置关联文件的规则,符合匹配规则的文件,LLM 操作时才应用该规则
Agent Requested LLM 决定是否应用该规则,必须提供规则描述,和 MCP 很像
Manual 仅在 query 时明确 @ 该规则才会生效

🎨 Rule 编写技巧

1. 控制文件大小

Rule 文件不应太大,保持在 500 行以下。可以将大而全的 Rule 按主题目标拆分成多个小 Rule 文件,并制定各自的应用规则。

2. 避免模糊指导

给出明确指导,最好能给出代码示例:

markdown 复制代码
<!-- ❌ 模糊规则 -->
写好代码,注意性能

<!-- ✅ 明确规则 -->
React 组件必须使用 React.memo() 包装,除非组件内部使用了 useState 或其他会导致重渲染的 Hook

3. 提供可执行性

规则应该提供具体的执行步骤和检查方法:

markdown 复制代码
<!-- ❌ 不可执行 -->
确保类型安全

<!-- ✅ 可执行 -->
所有函数参数和返回值必须显式声明 TypeScript 类型:
- 函数参数:`function handleUser(user: User): void`
- 对象属性:`interface Props { name: string; age: number }`
- 数组类型:`const users: User[] = []`

4. 设置优先级分级

使用 P0/P1/P2 标记规则重要性:

markdown 复制代码
- **[P0]** 必须遵循:影响项目基础功能和安全性
- **[P1]** 强烈推荐:影响代码质量和可维护性
- **[P2]** 可选优化:影响开发效率和用户体验

5. 提供检查清单

强制要求 LLM 进行检查:

markdown 复制代码
## 🔍 检查清单
在编写和审查样式相关代码时,请对照以下检查项:
- [ ] 检查项1
- [ ] 检查项2

6. 建立规则关联

markdown 复制代码
## 相关规则
- 参考:`typescript-standards.mdc` - TypeScript 类型规范
- 依赖:`naming-conventions.mdc` - 命名约定
- 扩展:`performance-optimization.mdc` - 性能优化

7. 错误经验积累

如果在对话过程中,发现需要频繁让 LLM 对相同问题进行纠正,可以将其加入 Rule 中。比如安装 npm 包报错,在让 LLM 修复后,可以将这个错误和解决方式写入 Rule 中,下次 LLM 再遇到就会自动处理。

Rule 模板

markdown 复制代码
# [规则名称]

## 核心原则 + [优先级]
简洁描述规则的目的和适用场景

## 执行标准 + [优先级]
具体的执行要求和检查点

## 代码示例
✅ 正确示例
❌ 错误示例

## 检查清单
- [ ] 检查项1 + [优先级]
- [ ] 检查项2 + [优先级]

## 相关规则
引用其他相关规则

实际示例:命名规则

markdown 复制代码
# 命名规范

## 核心原则

【必须】遵循:名称清晰表达意图,避免歧义,保持一致风格

## 变量命名规范

| 类型 | 风格 | 示例 |
|------|------|------|
| 变量、函数 | `camelCase` | `userName`, `fetchData()` |
| 类、组件 | `PascalCase` | `UserCard`, `DataService` |
| 常量 | `UPPER_SNAKE_CASE` | `API_BASE_URL` |
| 接口、类型 | `PascalCase` | `UserData`, `ButtonVariant` |

## 布尔值命名

【必须】使用明确前缀:

```tsx
// ✅ 正确
const isLoading = false;
const hasPermission = true;
const shouldShowModal = false;
const canEdit = true;

// ❌ 错误
const loading = false;
const permission = true;
const visible = false;
```

## 函数命名

【必须】动词开头,描述行为:

```tsx
// ✅ 正确 - CRUD 操作
function fetchUserProfile(userId: string): Promise<UserProfile> {}
function createNewPost(postData: PostData): Promise<Post> {}
function updateUserSettings(settings: UserSettings): Promise<void> {}
function deleteComment(commentId: string): Promise<void> {}

// ❌ 错误
function userData() {} // 应使用 fetchUserData
function submit() {}   // 应使用 handleSubmit
```

## 组件和 Props

【必须】直观反映用途:

```tsx
// ✅ 正确
interface UserProfileCardProps {
  user: User;
  isEditable?: boolean;
  onEdit?: (user: User) => void;
  className?: string;
}

function UserProfileCard({ user, isEditable, onEdit }: UserProfileCardProps) {
  // 实现
}
```

## 🔍 检查清单

在进行代码编写和审查时,【必须】确保所有命名均遵循以下规范:

### 文件与目录命名
- [ ] **[P0]** 文件/目录命名:所有文件名(如 `user-card.tsx`, `use-auth.ts`)和目录名(如 `components/user-profile/`)是否都严格使用 `kebab-case` 格式?

### 代码内标识符命名
- [ ] **[P0]** 变量和函数名:普通变量和函数名是否使用 `camelCase` (如 `userName`, `fetchData`)?
- [ ] **[P0]** 类、组件、接口、类型名:类名(`DataService`)、React 组件名(`UserCard`)、接口名(`UserData`)和类型别名(`ButtonVariant`)是否使用 `PascalCase`?
- [ ] **[P0]** 常量名:全局或模块级常量(如 `API_BASE_URL`, `MAX_RETRIES`)是否使用 `UPPER_SNAKE_CASE`?
- [ ] **[P0]** 布尔值命名:布尔型变量或属性名是否使用了明确的前缀(如 `isLoading`, `hasPermission`, `shouldShowModal`, `canEdit`)?
- [ ] **[P0]** 函数命名描述性:函数名是否以动词开头,并清晰描述其行为(如 `fetchUserProfile`, `handleSubmitForm`)?

Cursor Rules 快捷方式

实际上,你不需要从零开始写一套规范,可以通过 Cursor 命令 Generate Cursor Rules 结合当前 repo 的实际情况生成:

另一种方式是通过 cursor.directory,该网站涵盖 ReactNext.jsTypeScriptNode.js 等多种主流语言或框架,提供了非常多 awesome rules。可以直接在这些 Rules 基础上,结合当前 repo 的实际情况进行修改:

我的 Rules

下文所有 rules 均在 cursor-rules 仓库中。

在笔者的实践中,总结了一套符合自己开发流程的 Rules 体系,这套规则体系包含 19 个规范文件,覆盖前端开发的各个核心领域,提供了一套核心开发规范,涵盖代码质量、命名约定、技术栈选型、性能优化、安全防护等方面。每个规范都包含详细的代码示例、配置文件和检查清单。

规则概览

你不一定需要全部这些 Rule 规范,可以结合实际需求只参考或者采纳合适的部分。

重点规则

项目说明

首先要做的就是生成当前项目的功能说明、项目目录结构规范等,可以通过 Generate Cursor Rules 让 LLM 快速阅读当前项目然后生成,再结合项目实际情况微调,可以有效保证后续 LLM 生成代码时更加有的放矢,不会在莫名其妙的地方创建文件或代码。

Git Message

使用 Cursor 除了写代码外,还能帮助生成 git commit message:

但生成的 message 不一定符合规范,因此通过Git 提交消息规范来约束:

markdown 复制代码
# Git 提交消息规范

## 格式要求

【必须】使用以下格式:
```
<类型>: <简短描述>

[可选详细描述]
[可选关联问题]
```

## 类型标识

【必须】使用以下类型之一:
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档修改
- `style`: 格式修改(不影响功能)
- `refactor`: 代码重构
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建/工具变动

## 描述规范

【必须】遵循:
- 使用中文,不超过 50 字符
- 动词开头,现在时("添加"非"添加了")
- 不以句号结尾

## 示例

```
feat: 添加用户认证功能

实现 JWT 认证系统,包括登录、注册和令牌刷新。

close #123
```

## 分支管理

【推荐】使用:
- `main`: 主分支
- `feat/<功能名>`: 新功能分支
- `fix/<问题描述>`: 修复分支

## 🔍 检查清单:提交前确认

在执行 `git commit` 之前,【必须】逐项确认以下内容:

- [ ] **[P0]** 提交消息格式:本次提交的 commit message 是否严格遵循了 `<类型>: <简短描述>` 格式?(包括类型选择、描述简洁性、时态、标点等)
- [ ] **[P0]** 代码质量:提交的代码是否无语法错误、无编译警告或错误?
- [ ] **[P0]** 类型定义 (TypeScript):所有相关的 TypeScript 类型定义是否完整、准确且已通过类型检查?
- [ ] **[P0]** 代码规范符合性:代码是否遵循了项目约定的代码风格(如 ESLint, Prettier 配置)和命名规范?
- [ ] **[P0]** 功能完整性:本次提交是否完整实现了其宣称的功能或修复?是否存在未完成或遗漏的逻辑?
- [ ] **[P0]** 错误处理:相关的代码路径是否添加了必要的错误处理(参考 `error-handling.mdc`)?
- [ ] **[P0]** 测试覆盖:是否为新增或修改的功能编写了必要的单元测试/集成测试,并且所有测试是否通过?
- [ ] **[P0]** 本地工具检查:是否已在本地运行并通过了 ESLint, Prettier 等代码质量和格式化工具的检查?
- [ ] **[P0]** 提交内容相关性:本次提交是否只包含与当前 `<类型>: <简短描述>` 直接相关的代码变更,没有混杂不相关的修改?
- [ ] **[P0]** 详细描述与关联问题(可选):如果提交涉及复杂更改,是否在消息体中提供了详细描述?如果关联了 issue,是否已正确标记?

Context7 MCP 集成

Rules 规则能减少 AI 幻觉,但文档过时的问题要怎么处理呢?

一种方式是通过 Cursor 自带的 Docs 能力,将需要的技术栈文档添加进去,Cursor 会对这些文档进行序列化 Index,就可以有效获取及时的 API 信息:

但该方式比较麻烦,需要你添加很多 Docs 信息。并且不同项目所使用的技术栈也不同。

另一种方式就是使用 Context7,它通过数以万计的技术栈最新文档的查阅能力,通过配置 Context7 MCP Server,在和 LLM 沟通时,只需要加上 use context7 关键字即可(当然也可以不加,让 LLM 自行判断是否需要获取最新文档):

通过 Rule,我们可以进一步规范使用 Context7 MCP 的步骤,即使不使用 use context7 关键字也能很好地利用 Context7 的能力:

markdown 复制代码
# Context7 MCP 集成规范

## 使用要求

【必须】遵循:
- 首次引入/升级/替换第三方库,必须通过 Context7 MCP 获取官方文档
- 实现复杂功能、调试、重构、优化时,先查阅 Context7 文档

## 流程

【必须】按顺序执行:
1. 先 `resolve-library-id` 获取库 ID
2. 再 `get-library-docs` 获取详细文档
3. 严格按文档实现

## 示例

```tsx
// ✅ 正确流程
// 步骤1: resolve-library-id("axios")
// 步骤2: get-library-docs({ context7CompatibleLibraryID: "/axios/axios" })
// 步骤3: 按文档实现
import axios from 'axios';
const api = axios.create({ baseURL: '/api' });
```

## 🔍 检查清单

在每次使用第三方库(通过 Context7 MCP 获取文档)实现功能时,【必须】确认:

- [ ] **[P0]** 文档获取:是否已通过 Context7 MCP (`resolve-library-id` 和 `get-library-docs`) 获取最新官方文档?
- [ ] **[P0]** 版本匹配:项目中使用的库版本与查阅的文档版本是否一致?
- [ ] **[P0]** 核心实现:是否严格按照获取的文档说明来实现核心功能和 API 调用?
- [ ] **[P0]** 最佳实践:是否遵循了文档中推荐的配置、设计模式和最佳实践?
- [ ] **[P0]** 类型安全:如果使用 TypeScript,是否采纳了文档提供的或兼容的类型定义?
- [ ] **[P0]** 错误处理:是否实现了文档中建议的错误处理机制?
- [ ] **[P0]** 性能考量:是否关注并采用了文档中提及的性能优化建议?
- [ ] **[P0]** 可访问性(如适用):如果库涉及 UI 或用户交互,是否遵循了其可访问性指南?

**重要提醒**:Context7 MCP 提供的是实时更新的官方文档,确保您始终使用最新、最正确的实现方式。这是代码质量的重要保障,不可忽视!

LLM 严格模式

LLM 现在非常强大,但偶尔也过于灵活,会自作主张,因此通过规范 LLM 的行为可以让其更好地工作,有网友提出了 RIPER-5 MODE 模式,笔者实测下来非常好用。

RIPER-5 模式

  1. RESEARCH(调研):仅限信息收集和理解
  2. INNOVATE(创新):头脑风暴和方案讨论
  3. PLAN(规划):制定详尽的技术规范
  4. EXECUTE(执行):严格按照计划实施
  5. REVIEW(复查):系统性比对和验证

让 LLM 每次回复强制保持在一个模式下,明确的边界可以有效避免 LLM 胡作非为:

markdown 复制代码
# LLM 严格模式规则

## 模式声明
你必须在每一次回复的开头声明你当前的模式。无例外。格式如下:`🤖 MODE: MODE_NAME`。未声明模式属于严重违规。

## RIPER-5 模式

### 模式 1:RESEARCH(调研)

`🤖 MODE: RESEARCH`

- 目的:仅限信息收集
- 允许:阅读文件、提出澄清性问题、理解代码结构
- 禁止:建议、实现、规划或任何暗示行动的内容
- 要求:你只能了解现有内容,不能设想可能的内容
- 输出格式:以 `🤖 MODE: RESEARCH` 开头,仅输出观察和问题
- 持续时间:直到我明确发出切换信号

### 模式 2:INNOVATE(创新)
`🤖 MODE: INNOVATE`

- 目的:头脑风暴潜在方案
- 允许:讨论思路、优缺点、征求反馈
- 禁止:具体规划、实现细节或任何代码编写
- 要求:所有想法都必须以可能性呈现,不能做决定
- 输出格式:以 `🤖 MODE: INNOVATE` 开头,仅输出可能性和考虑点
- 持续时间:直到我明确发出切换信号

### 模式 3:PLAN(规划)
`🤖 MODE: PLAN`

- 目的:制定详尽的技术规范
- 允许:详细计划,包含精确的文件路径、函数名和变更点
- 禁止:任何实现或代码编写,甚至"示例代码"也不允许
- 要求:计划必须足够详尽,实施时无需再做创意决策
- 强制最后一步:将整个计划转为编号的、顺序的 CHECKLIST,每个原子操作单独成项
- CHECKLIST 格式:
```md
Checklist:
1. [具体操作1]
2. [具体操作2]
...
n. [最终操作]
```
- 输出格式:以 `🤖 MODE: PLAN` 开头,仅输出规范和实施细节
- 持续时间:直到我明确批准计划并发出切换信号

### 模式 4:EXECUTE(执行)
`🤖 MODE: EXECUTE`

- 目的:严格按照第三模式制定的计划实施
- 允许:仅实施计划中明确列出的内容
- 禁止:任何偏离、改进或未在计划中的创意添加
- 进入要求:仅在我明确发出 "EXECUTE MODE" 指令后进入
- 偏离处理:如发现任何需偏离的情况,立即返回 PLAN 模式
- 输出格式:以 `🤖 MODE: EXECUTE` 开头,仅输出与计划一致的实现内容

### 模式 5:REVIEW(复查)
`🤖 MODE: REVIEW`

- 目的:严格比对实现与计划
- 允许:逐行比对计划与实现
- 要求:必须明确标记任何偏离,无论多小
- 偏离格式:"⚠️ 检测到偏离: [具体偏离描述]"
- 报告:必须报告实现是否与计划完全一致
- 结论格式:"✅ 实现与计划完全一致" 或 "❌ 实现与计划不符"
- 输出格式:以 `🤖 MODE: REVIEW` 开头,系统性比对并明确结论

## 关键协议指南
- 未经我明确指令,不得切换模式
- 你必须在每次回复开头声明当前模式
- 在 EXECUTE 模式下,必须 100% 遵循计划
- 在 REVIEW 模式下,必须标记哪怕最小的偏离
- 你无权在声明模式之外做任何自主决策
- 未遵守本协议将导致代码库灾难性后果

## 模式切换信号
仅在我明确发出以下信号时切换模式:

- `RESEARCH MODE`
- `INNOVATE MODE`
- `PLAN MODE`
- `EXECUTE MODE`
- `REVIEW MODE`

如未收到上述信号,保持当前模式不变。

## 🔍 检查清单:LLM 交互模式遵循情况

在与 LLM 交互时,为确保严格遵循 RIPER-5 协议,【必须】对照检查以下各项:

### 通用协议与模式切换
- [ ] **[P0]** 模式声明:LLM 的每一次回复是否都以 `🤖 MODE: MODE_NAME` 开头清晰声明了当前操作模式?
- [ ] **[P0]** 模式切换授权:LLM 是否仅在用户明确发出约定的模式切换信号(如 `RESEARCH MODE`, `PLAN MODE` 等)后才切换模式?
- [ ] **[P0]** 自主决策禁止:LLM 是否未在声明的模式之外进行任何自主决策或操作?

### RESEARCH 模式检核
- [ ] **[P0]** RESEARCH 范围:在 `🤖 MODE: RESEARCH` 下,LLM 是否严格将活动限制在信息收集、文件阅读、代码理解和提出澄清性问题,未包含任何建议、计划或实现意图?

### INNOVATE 模式检核
- [ ] **[P0]** INNOVATE 范围:在 `🤖 MODE: INNOVATE` 下,LLM 是否专注于头脑风暴、讨论可能性、优缺点,未涉及具体规划、实现细节或任何代码编写?所有想法是否以可能性呈现?

### PLAN 模式检核
- [ ] **[P0]** PLAN 详尽性:在 `🤖 MODE: PLAN` 下,LLM 是否产出了足够详尽的技术规范(精确到文件路径、函数名、变更点等),使得实施时无需创意决策?
- [ ] **[P0]** PLAN 产出 CHECKLIST:PLAN 模式的最终输出是否包含了将整个计划分解为原子操作的、编号的、顺序的 CHECKLIST?
- [ ] **[P0]** PLAN 无实现:在 `🤖 MODE: PLAN` 下,LLM 是否未包含任何实现代码,包括示例代码?

### EXECUTE MODE 检核
- [ ] **[P0]** EXECUTE 严格遵循:在 `🤖 MODE: EXECUTE` 下,LLM 是否完全且仅实施了 PLAN 模式中 CHECKLIST 列出的内容,无任何偏离、改进或计划外创意?
- [ ] **[P0]** EXECUTE 偏离处理:在 `🤖 MODE: EXECUTE` 下,如遇到任何需要偏离 PLAN 的情况,LLM 是否立即请求返回 PLAN 模式进行调整?

### REVIEW 模式检核
- [ ] **[P0]** REVIEW 严格比对:在 `🤖 MODE: REVIEW` 下,LLM 是否逐项/逐行严格比对了 EXECUTE 的实现与 PLAN 的计划?
- [ ] **[P0]** REVIEW 偏离标记:在 `🤖 MODE: REVIEW` 下,是否明确标记了所有检测到的偏离(无论多小),并使用了 "⚠️ 检测到偏离: ..." 格式?
- [ ] **[P0]** REVIEW 结论明确:REVIEW 模式的最终输出是否包含了对实现与计划一致性的明确结论("✅ 实现与计划完全一致" 或 "❌ 实现与计划不符")?

文档书写规范

LLM 在书写文档时,有时 AI 味儿过重,有时过于繁琐,套话多。同样可以通过 Rule 来规范生成的文档,又或者对已有文档进行纠错和润色:

markdown 复制代码
# 文档书写规范

## Markdown 格式

【必须】遵循:
- 标题层级:`#` → `##` → `###` → `####`,不跳级,不超过四级
- 列表:无序用 `-`,有序用 `1.`,嵌套用四空格缩进
- 代码:三反引号包裹代码块,指定语言,内联用单反引号
- 表格:保持列对齐,使用标准 Markdown 语法

## 中英文排版

【必须】遵循:
- 中英文间加半角空格
- 中文使用全角标点
- 英文数字使用半角字符

## 语言风格

【必须】使用:
- 中文编写,直接简洁的语气
- 短句优先,避免长句
- 删除累赘词:"的"、"是"、"了"、"因为"等
- 专业术语保持一致

### 示例对比

```md
<!-- ❌ 冗余表达 -->
前段时间因为采访的缘故,我认识了一个名叫粥粥的餐厅店长。

<!-- ✅ 精简表达 -->
前段时间采访,我认识了个餐厅店长,叫粥粥。
```

## 代码示例

【必须】确保:
- 语法正确,可直接运行
- 包含必要的导入语句
- TypeScript 类型完整

```tsx
// ✅ 完整示例
import { useState } from 'react';

interface User {
  id: string;
  name: string;
}

function UserList() {
  const [users, setUsers] = useState<User[]>([]);
  return <div>{users.length} 个用户</div>;
}
```

## 文档更新

【必须】同步:
- 代码变更时更新相关文档
- 重大变更使用警告框标注版本

```md
> **注意**:自 v2.0.0 起,此 API 已更改行为。
```

## 🔍 检查清单

在编写或更新任何 Markdown 文档时,【必须】确认以下各项均符合本规范要求:

- [ ] **[P0]** 内容准确性:文档内容是否准确反映了当前代码库的功能和状态?
- [ ] **[P0]** Markdown 格式:是否严格遵循了本文档定义的 Markdown 格式规范(标题、列表、代码块、表格)?
- [ ] **[P0]** 中英文排版:中英文混排是否符合规范(空格、标点、半角/全角字符)?
- [ ] **[P0]** 语言风格:行文是否简洁、直接,避免了冗余词汇,且专业术语使用是否一致?
- [ ] **[P0]** 代码示例质量:所有代码示例是否语法正确、可直接运行、包含必要导入且 TypeScript 类型完整?
- [ ] **[P0]** 文档同步:如果文档对应代码发生变更,相关文档是否已同步更新?重大变更是否已标注?
- [ ] **[P0]** 拼写与语法:文档中是否存在拼写错误或语法问题?
- [ ] **[P0]** 链接有效性:文档中所有的内部链接和外部链接是否均有效且指向正确的目标?

最后

Cursor Rules 本质上还是 Prompt 工程,这些 Rules 会作为 Prompt 的一部分交给 LLM,来提升 LLM 工作的规范性。抛开 Cursor 不谈,这些 Prompt 也可以扔给其他 AI IDE 作为 Custom Instructions 来使用。

相关推荐
贵沫末6 分钟前
React——基础
前端·react.js·前端框架
每天开心10 分钟前
深入理解 CSS 选择器:从基础到高级
css·html·ai编程
aklry17 分钟前
uniapp三步完成一维码的生成
前端·vue.js
Rubin9325 分钟前
判断元素在可视区域?用于滚动加载,数据埋点等
前端
爱学习的茄子25 分钟前
AI驱动的单词学习应用:从图片识别到语音合成的完整实现
前端·深度学习·react.js
用户38022585982426 分钟前
使用three.js实现3D地球
前端·three.js
程序无bug28 分钟前
Spring 面向切面编程AOP 详细讲解
java·前端
zhanshuo28 分钟前
鸿蒙UI开发全解:JS与Java双引擎实战指南
前端·javascript·harmonyos
撰卢1 小时前
如何提高网站加载速度速度
前端·javascript·css·html
10年前端老司机1 小时前
在React项目中如何封装一个可扩展,复用性强的组件
前端·javascript·react.js