Cursor mdc规则学习总结

Cursor mdc 规则学习总结

• Cursor mdc 规则示例
• Cursor 官方已废弃 .cursorules，主推 Project Rules。

一、新建配置

新建 Project Rules

创建 Project Rules 有两种方式，一种是 可视化方式，一种是 手动创建

可视化方式

进入 Cursor 设置页面，点击【General】找到【Project Rules】

点击【Add new rule】，输入规则文件名称

创建完成就可以看到在项目根目录多了一个 .cursor/rules 目录，目录是刚刚创建的 vue3-rules.mdc 文件

手动创建

在项目根目录创建一个 .cursor/rules 目录（注意是两级目录）或者使用命令行创建

mkdir -p .cursor/rules

在 .cursor/rules 目录下新建 typescript-rules.mdc 文件，内容如下：

---
description: TypeScript coding standards
globs: **/*.ts,**/*.tsx
priority: 1
---

# TypeScript Coding Standards

## 基本规范

-   使用 `const` 而不是 `let` 来声明常量
-   使用 `const` 而不是 `let` 来声明变量
-   使用 2 个空格缩进
-   显式声明函数返回类型
-   使用单引号
-   使用箭头函数
-   使用解构赋值
-   避免使用 `any` 类型

Project Rules 规则格式

mdc 规则

新规则文件采用 .mdc 格式，主要由两部分组成:

• YAML 格式头部配置
  • name：项目规则名称
  • description：项目规则描述
  • priority：项目规则优先级，默认优先级为 0，数字越大优先级越高，相同优先级按文件名排序
  • globs：匹配规则
  • when：规则生效条件，满足条件的规则才会生效
• Markdown 或者 XML 格式规则内容

glob 规则

常用的 glob 语法规则:

• *：匹配任意文件名
• **：匹配任意目录深度
• !：排除匹配
• {}：组合匹配

glob 的基本语法非常灵活可以任意组合，我们可以组合出更多满足日常需求的规则

# 多内容匹配

\*_/_.{ts, tsx, js}

# 匹配所有 .ts 文件

\*_/_.ts

# 排除测试文件

!\*_/_.test.ts

# 排除构建目录

!**/dist/** !**/build/**

# 匹配特定目录

src/components/\*_/_.tsx 123456789101112

规则继承复用

Project Rules 的规则继承、复用也很简单，就是在一个 .mdc 文件中通过 @file 引入其他规则作为上下文使用

条件规则

Project Rules 支持根据环境变量设置规则：

---
name: develop-rules
description: Development environment rules
when: ${NODE_ENV} === 'development'
---
12345

Project Rules 分类管理？

看到有小伙伴将 Project Rules 做了分类管理，如下：

.cursor/rules
├─ common
│  └─ base.mdc             // 通用规则
├─ frontend
│  ├─ vue3-rules.mdc       // 前端vue3规则
│  └─ typescript-rules.mdc // 前端ts规则
└─ styles
   └─ less.mdc             // 样式less规则

经本人测试该方式不会被系统识别会导致 Project Rules 失效，Cursor 该版本不建议做 Project Rules 分类管理。

官方 mdc

官网地址：https://cursor.directory/generate

cursor.directory 提供了生成 Project Rules 的功能，只需按提示上传文件即可

React 规则

---
name: react-rules
description: React project best practices and coding standards
globs:
    - 'src/**/*.tsx'
    - 'src/**/*.jsx'
    - 'src/**/*.ts'
priority: 2
---

# React 项目规范

## 组件规范

### 基础规则

-   使用函数组件 + Hooks 模式
-   组件文件使用 .tsx 扩展名
-   组件名使用 PascalCase 命名
-   文件名与组件名保持一致

### 目录结构

src/ ├── components/ # 通用组件 ├── pages/ # 页面组件 ├── hooks/ # 自定义 hooks ├── utils/ # 工具函数 ├── services/ # API 服务 ├── types/ # TypeScript 类型 └── styles/ # 样式文件

### Hooks 使用规范

-   自定义 Hook 以 `use` 开头
-   避免在循环/条件语句中使用 Hooks
-   合理使用 useMemo 和 useCallback
-   使用 useContext 管理全局状态

### 性能优化

-   合理拆分组件
-   使用 React.memo 避免不必要渲染
-   使用 React.lazy 实现代码分割
-   图片使用 next/image 优化

### TypeScript 集成

-   为 Props 定义接口
-   使用 FC 类型声明组件
-   避免使用 any
-   合理使用泛型

## 状态管理

-   小型项目使用 Context + useReducer
-   大型项目推荐使用 Redux Toolkit
-   遵循不可变数据原则
-   合理划分 state 结构

Vue 规则

---
name: vue-rules
description: Vue.js project best practices and coding standards
globs:
    - 'src/**/*.vue'
    - 'src/**/*.ts'
priority: 2
---

# Vue 项目规范

## 组件规范

### 基础规则

-   使用 Composition API
-   组件名使用 PascalCase
-   Props 定义使用 defineProps
-   事件使用 defineEmits

### 目录结构

src/ ├── components/ # 通用组件 ├── views/ # 页面视图 ├── composables/ # 组合式函数 ├── utils/ # 工具函数 ├── api/ # API 接口 ├── types/ # TypeScript 类型 └── assets/ # 静态资源

### 组合式函数规范

-   以 `use` 开头命名
-   一个函数只做一件事
-   返回响应式数据
-   注意依赖收集

### 性能优化

-   合理使用 computed
-   v-show vs v-if
-   使用 defineAsyncComponent
-   keep-alive 缓存

### TypeScript 集成

-   使用 defineComponent
-   Props 类型声明
-   组件实例类型
-   响应式类型

## 状态管理

-   小型项目使用 provide/inject
-   大型项目使用 Pinia
-   模块化状态管理
-   合理使用 storeToRefs

Styles 规则

---
name: style-rules
description: CSS/LESS/SCSS styling best practices
globs:
    - 'src/**/*.css'
    - 'src/**/*.less'
    - 'src/**/*.scss'
    - 'src/**/*.module.*'
priority: 1
---

# 样式规范

## 命名规范

### BEM 命名

-   Block: 独立实体
-   Element: 使用双下划线 \_\_
-   Modifier: 使用双横线 -- .block {} .block\_\_element {} .block--modifier {}

### CSS Modules

-   文件名使用 .module.css
-   类名使用小驼峰
-   避免全局样式
-   合理使用组合

## 目录结构

styles/ ├── global/ # 全局样式 ├── themes/ # 主题文件 ├── variables/ # 变量定义 ├── mixins/ # 混入 └── components/ # 组件样式

## 响应式设计

-   使用相对单位
-   移动优先原则
-   合理使用媒体查询
-   避免固定宽度

### 断点设置

@screen-xs: 480px; @screen-sm: 576px; @screen-md: 768px; @screen-lg: 992px; @screen-xl: 1200px;

## 性能优化

-   避免深层嵌套
-   合理使用选择器
-   压缩和合并
-   CSS 代码分割

## 主题定制

-   使用 CSS 变量
-   设计 Token 系统
-   暗黑模式支持
-   主题切换方案

## 最佳实践

-   避免 !important
-   模块化样式
-   注释规范
-   代码复用

二、迁移实战 - 从 0 到 1 的升级指南 🛠️

2.1 创建规则目录

首先需要在项目根目录创建规则文件夹:

# 创建规则目录
mkdir -p .cursor/rules

# 可选:将旧规则文件移动到新目录
mv .cursorrules .cursor/rules/general.mdc

2.2 规则文件结构

新的规则文件采用 .mdc 格式,由两部分组成:

1. YAML 头部配置
2. Markdown 规则内容

一个完整的规则文件示例:

---
name: typescript-rules
description: TypeScript coding standards and best practices
globs:
    - 'src/**/*.ts'
    - 'src/**/*.tsx'
    - '!src/**/*.test.ts'
priority: 1
---

# TypeScript Coding Standards

## 基础规范

-   使用 2 空格缩进
-   优先使用 const 声明变量
-   显式声明函数返回类型

## 最佳实践

-   避免 any 类型
-   合理使用泛型
-   接口优于类型别名

## 参考文档

Read more from @common-rules.mdc

2.3 规则分类示例

推荐按照以下方式组织规则文件:

.cursor/rules/
├── common/
│   ├── general.mdc     # 通用规则
│   └── git.mdc         # Git 规范
├── frontend/
│   ├── javascript.mdc  # JS 规则
│   ├── typescript.mdc  # TS 规则
│   └── react.mdc       # React 规则
├── backend/
│   ├── node.mdc       # Node.js 规则
│   └── database.mdc   # 数据库规则
└── style/
    ├── css.mdc        # CSS 规则
    └── less.mdc       # LESS 规则

2.4 Glob 模式详解

新系统支持强大的 glob 匹配模式:

globs:
    # 匹配所有 .ts 文件
    - '**/*.ts'

    # 排除测试文件
    - '!**/*.test.ts'

    # 排除构建目录
    - '!**/dist/**'
    - '!**/build/**'

    # 匹配特定目录
    - 'src/components/**/*.tsx'

常用的 glob 语法:

• *: 匹配任意文件名
• **: 匹配任意目录深度
• !: 排除匹配
• {}: 组合匹配

三、进阶技巧 - 玩转规则系统 🎯

3.1 规则继承与复用

使用 @file 语法引用其他规则:

# React 组件规范

继承通用前端规范 @frontend/common.mdc

## 特殊规则

-   使用函数组件
-   采用 Hooks 开发

3.2 个人规则配置

创建个人专属规则:

# 创建个人规则目录
mkdir -p .cursor/rules/personal

# 添加到 .gitignore
echo ".cursor/rules/personal/" >> .gitignore

3.3 规则优先级

通过 priority 字段控制规则优先级:

---
name: override-rules
description: Override default rules
priority: 100 # 高优先级规则
---

优先级说明:

• 数字越大优先级越高
• 默认优先级为 0
• 相同优先级按文件名排序

3.4 条件规则

支持根据环境变量设置规则:

---
name: dev-rules
description: Development environment rules
when: ${NODE_ENV} === 'development'
---

3.5 规则模板

创建规则模板便于复用:

---
name: rule-template
description: Template for new rules
---

# ${name} 规范

## 基础规则

${rules}

## 最佳实践

${practices}

四、实战案例 - 规则系统应用场景 💡

4.1 多人协作项目

适合大型团队的规则结构:

.cursor/rules/
├── team/              # 团队通用规则
├── projects/          # 项目特定规则
└── members/           # 成员个性化规则

4.2 Monorepo 项目

针对 monorepo 的规则配置:

---
name: package-rules
description: Rules for specific package
globs: ['packages/*/src/**/*.ts']
---

4.3 微前端项目

为不同子应用设置规则:

.cursor/rules/
├── main/             # 主应用规则
└── sub-apps/         # 子应用规则
    ├── app1.mdc
    └── app2.mdc

五、注意事项 ⚠️

1. 迁移时间

   • .cursorrules 将在未来版本废弃
   • 建议尽快完成迁移工作
   • 保留旧规则作为备份

2. 规则冲突

   • 注意 glob 匹配范围
   • 合理设置优先级
   • 避免循环引用

3. 性能考虑

   • 规则文件不宜过大
   • 避免过于复杂的 glob 模式
   • 适当使用规则缓存

4. 团队协作

   • 统一规则命名规范
   • 做好规则文档
   • 及时同步规则变更

六、最佳实践配置示例 📚

6.1 React 项目配置示例

---
name: react-rules
description: React project best practices and coding standards
globs:
    - 'src/**/*.tsx'
    - 'src/**/*.jsx'
    - 'src/**/*.ts'
priority: 2
---

# React 项目规范

## 组件规范

### 基础规则

-   使用函数组件 + Hooks 模式
-   组件文件使用 .tsx 扩展名
-   组件名使用 PascalCase 命名
-   文件名与组件名保持一致

### 目录结构

src/ ├── components/ # 通用组件 ├── pages/ # 页面组件 ├── hooks/ # 自定义 hooks ├── utils/ # 工具函数 ├── services/ # API 服务 ├── types/ # TypeScript 类型 └── styles/ # 样式文件

### Hooks 使用规范

-   自定义 Hook 以 `use` 开头
-   避免在循环/条件语句中使用 Hooks
-   合理使用 useMemo 和 useCallback
-   使用 useContext 管理全局状态

### 性能优化

-   合理拆分组件
-   使用 React.memo 避免不必要渲染
-   使用 React.lazy 实现代码分割
-   图片使用 next/image 优化

### TypeScript 集成

-   为 Props 定义接口
-   使用 FC 类型声明组件
-   避免使用 any
-   合理使用泛型

## 状态管理

-   小型项目使用 Context + useReducer
-   大型项目推荐使用 Redux Toolkit
-   遵循不可变数据原则
-   合理划分 state 结构

6.2 Vue 项目配置示例

---
name: vue-rules
description: Vue.js project best practices and coding standards
globs:
    - 'src/**/*.vue'
    - 'src/**/*.ts'
priority: 2
---

# Vue 项目规范

## 组件规范

### 基础规则

-   使用 Composition API
-   组件名使用 PascalCase
-   Props 定义使用 defineProps
-   事件使用 defineEmits

### 目录结构

src/ ├── components/ # 通用组件 ├── views/ # 页面视图 ├── composables/ # 组合式函数 ├── utils/ # 工具函数 ├── api/ # API 接口 ├── types/ # TypeScript 类型 └── assets/ # 静态资源

### 组合式函数规范

-   以 `use` 开头命名
-   一个函数只做一件事
-   返回响应式数据
-   注意依赖收集

### 性能优化

-   合理使用 computed
-   v-show vs v-if
-   使用 defineAsyncComponent
-   keep-alive 缓存

### TypeScript 集成

-   使用 defineComponent
-   Props 类型声明
-   组件实例类型
-   响应式类型

## 状态管理

-   小型项目使用 provide/inject
-   大型项目使用 Pinia
-   模块化状态管理
-   合理使用 storeToRefs

6.3 样式文件配置示例

---
name: style-rules
description: CSS/LESS/SCSS styling best practices
globs:
    - 'src/**/*.css'
    - 'src/**/*.less'
    - 'src/**/*.scss'
    - 'src/**/*.module.*'
priority: 1
---

# 样式规范

## 命名规范

### BEM 命名

-   Block: 独立实体
-   Element: 使用双下划线 \_\_
-   Modifier: 使用双横线 --

.block {} .block\_\_element {} .block--modifier {}

### CSS Modules

-   文件名使用 .module.css
-   类名使用小驼峰
-   避免全局样式
-   合理使用组合

## 目录结构

styles/ ├── global/ # 全局样式 ├── themes/ # 主题文件 ├── variables/ # 变量定义 ├── mixins/ # 混入 └── components/ # 组件样式

## 响应式设计

-   使用相对单位
-   移动优先原则
-   合理使用媒体查询
-   避免固定宽度

### 断点设置

@screen-xs: 480px; @screen-sm: 576px; @screen-md: 768px; @screen-lg: 992px; @screen-xl: 1200px;

## 性能优化

-   避免深层嵌套
-   合理使用选择器
-   压缩和合并
-   CSS 代码分割

## 主题定制

-   使用 CSS 变量
-   设计 Token 系统
-   暗黑模式支持
-   主题切换方案

## 最佳实践

-   避免 !important
-   模块化样式
-   注释规范
-   代码复用