【AI智能体】Cursor 规则配置项目实战操作详解

目录

一、前言

二、Cursor 介绍

2.1 Cursor 是什么

2.2 Cursor 核心特性

2.3 Cursor与传统IDE区别

2.4 Cursor与传统IDE核心差异总结

2.5 Cursor 规则介绍

2.4.1 什么是 Cursor Rules

2.4.2 Cursor 规则文件作用

2.4.3 Cursor Rules 分级与存放位置

三、Cursor 规则配置与使用

3.1 Cursor 用户规则介绍与使用

3.1.1 什么是用户 Rule（规则）

3.1.2 用户 Rule与项目Rule 比较

3.1.3 用户 Rule创建与使用

3.2 Cursor mdc 格式语法

3.2.1 什么是mdc文件格式

3.2.2 mdc 文件结构与规范

3.3 Cursor 项目规则配置与使用

3.3.1 Cursor 规则文件创建方式

3.3.2 Cursor 规则文件编写规范

3.3.3 创建规则文件

3.3.4 规则应用

3.3.5 规则文件使用示例

3.3.6 规则文件如何编写

3.3.7 Cursor 规则使用技巧补充

3.3.8 Cursor 进阶规则使用技巧

3.3.9 最佳实践建议

四、写在文末

一、前言

在过去的很长一段时间里，Cursor 被誉为最全能的 AI 工具，它不仅是一个编程 Agent，更是一个几乎可以替换掉任何对话工具的全能 AI。Cursor 的出现，让很多软件工程师大开眼界，从而打开了一扇从传统编程进入到AI编程的新时代，可以说，只要你能想到的场景，Cursor 都能帮你自动化完成。借助Cursor ，不仅可以大大提升编程效率，而且对着技术的发展，Cursor 的功能也越来越完善，不仅可以做AI编程，在更多的领域都展示出了强大的能力，本篇将详细介绍Cursor 中自定义规则的配置与使用。

二、Cursor 介绍

2.1 Cursor 是什么

Cursor是一个类VSCode的智能编程IDE，集成了GPT-4、Claude3.5等先进大语言模型(LLM)，本质上是一个内置AI助手的VSCode。它不仅支持自然语言编程，还提供从代码编写、调试、重构到部署的智能辅助。你可以像和人交流一样与AI协作，大幅提升开发效率和代码质量。官网：https://cursor.com/

2.2 Cursor 核心特性

Cursor 主要包括如下核心特点：

• AI原生设计:

  • 从底层架构就融入了AI能力，而非后期添加的插件智能代码生成:通过自然语言描述快速生成代码片段

• 上下文感知:

  • 深度理解项目结构和代码关系

• 实时协助:

  • 在编程过程中提供即时的建议和优化

• 多模型支持:

  • 集成了多种先进的大语言模型

2.3 Cursor与传统IDE区别

Cursor与传统IDE主要有下面的区别：

2.4 Cursor与传统IDE核心差异总结

与传统的IDE相比，具有如下的核心差异

2.5 Cursor 规则介绍

2.4.1 什么是 Cursor Rules

Cursor Rules，中文翻译过来是 Cursor 规则。就是给Cursor制定一系列规则，约束AI生成的代码。

• Cursor 的规则系统是让 AI 按照你的技术栈、代码规范和项目架构来生成代码的关键。通过配置.cursor/rules/*.mdc文件，你可以告诉 AI "你是谁"、"项目用什么技术"以及"代码该怎么写"

• 当一条规则被触发后，规则中的内容会被附加到提示词中，为 AI 提供参考，无论是在自动补全、 代码生成、重构还是错误修复时都能遵循这些规范

2.4.2 Cursor 规则文件作用

规则文件具有下面的作用：

• 指明项目所使用的技术栈（Vue 3, Element Plus, Pinia, TypeScript, Vite）

• 明确项目约定（组件/文件命名、CSS 命名、导入顺序）

• 避免误判：减少 Cursor 提供的错误补全或重复实现已有功能

• 提升智能度：帮助 AI 生成符合项目风格、结构规范、命名约定的代

2.4.3 Cursor Rules 分级与存放位置

之前接触过Claude Code 的同学应该不陌生，Claude Code中的规则配置分全局和项目级别，在 Cursor 当中，也不例外，它支持两种级别的规则：

• 全局规则（User Rules）：针对所有项目通用的规则

• 项目规则（Project Rules）：存放于项目目录下的 .cursor/rules 中，只用于约束当前项目

规则文件放在项目根目录下的.cursor/rules/文件夹中，使用.mdc格式

your-project/ ├── .cursor/ │ └── rules/ │ ├── typescript.mdc # TypeScript 规范 │ ├── components.mdc # 组件规范 │ └── api.mdc # API 规范 ├── src/ └── ...

⚠️ 注意：旧的.cursorrules单文件方式已不再推荐，新项目请使用.cursor/rules/多文件方式。

对上面的规则文件目录位置做一些补充说明：

• 📁 路径固定：必须为 .cursor/rules/

• 📄 扩展名固定：必须为 .mdc

• ✅文件可以有多个，每个规则建议单独拆分主题编写，如 unocss-guidelines.mdc, project-structure.mdc, naming-conventions.mdc 等

三、Cursor 规则配置与使用

从大的方面划分，Cursor 规则可以划分为用户规则和项目规则下面分别通过实际操作做详细介绍。

3.1 Cursor 用户规则介绍与使用

3.1.1 什么是用户 Rule（规则）

用户 Rule 是一组配置规则，用于定义系统在执行任务或操作时的行为约束，特别是在 AI 编程、自动化

任务、操作代理（Agent）执行环境等场景中，用于控制哪些操作允许、哪些禁止、如何处理异常等。

用户规则是全局的，不受项目规则配置的限制，即用户规则在所有项目中生效

3.1.2 用户 Rule与项目Rule 比较

Cursor 用户 Rule与项目Rule 的对比差异如下

💡 版本提示：早期版本使用根目录下的.cursorrules单文件。新版本（v0.12+）推荐使用.cursor/rules/目录下的.mdc文件，支持多规则拆分和更精细的控制。

3.1.3 用户 Rule创建与使用

在Cursor 中，配置用户规则在设置那里，如下图，展示了3个不同规则的TAB页，用户规则就在User那里

如果你需要新增规则，点击New，在下面新增的输入框中输入你要编写的用户规则

比如，我在这里需要新增下面的规则

3.2 Cursor mdc 格式语法

想必使用过Claude Code 或者 codex 的同学应该还有印象，在这两种AI编程模型中，他们都有自己的项目规则文件，不过他们统一都是.md格式文件，即markdown格式的，但是在Cursor 中，采用了叫 mdc结尾的格式文件，虽然后缀不太一样，但是整体用法是相似的，为了后续深入学习和了解Cursor规则，有必要了解一下mdc 的语法格式使用。

3.2.1 什么是mdc文件格式

.mdc（Markdown with Configuration）是一种扩展的 Markdown 文件格式，专为 Cursor等智能开发工具设

计，用于编写规则、配置、教学任务等内容。

它结合了 Markdown 的可读性与结构化的前置元数据（Frontmatter），使得开发者可以在统一语法中定义：

• 文件适用范围

• 启用方式（自动、手动）

• 配套文件引用

• 规则说明、注释、命令等

3.2.2 mdc 文件结构与规范

每个 .mdc 文件由两部分组成：

1. 前置元数据（Frontmatter）：用三横线（---）包裹，定义规则的描述和适用范围。

2. 规则正文：使用Markdown格式编写具体指令

1）前置元数据（Frontmatter）

使用三横线 --- 包裹，采用 YAML 格式，主要用于声明规则的元信息。

常见字段如下：

--- description: "在 React 项目中使用 TypeScript 和 Tailwind CSS" globs: - "src/**/*.tsx" alwaysApply: true ---

2）正文（Markdown格式）

正文使用标准 Markdown 编写，可以包含标题、列表、代码块、注释、引用文件等。是实际执行规则或

说明内容的主体。

常用语法支持：

• 标题：用于结构化说明

• 列表项：用于列出规范细则

• @file：表示要引用的外部文件路径

• @command：表示要执行的指令（例如用于脚手架）

如下给出一个比较完整的示例

--- description: "在 React 项目中使用 TypeScript 和 Tailwind CSS" globs: - "src/**/*.tsx" alwaysApply: true --- # 项目基础说明 - 本项目基于 Vue 3 + TypeScript + Element Plus + Pinia + Vite 搭建。 - 采用组合式 API（`<script setup lang="ts">`）进行开发。 - 状态管理使用 Pinia，模块化组织。 - 路由使用 Vue Router，采用权限动态路由配置。 - 接口请求统一封装在 `@/utils/request.ts` 中，使用 Axios。 - 表格、表单页面基于 Element Plus 封装通用组件，提高复用性。 # 组件和文件命名规范 - 组件文件名使用 `PascalCase` 格式，例如：`UserTable.vue`, `LoginForm.vue` - 公共组件放置在 `src/components/` 下，业务组件可放在 `src/views/模块/components/` 中 - 文件夹名和非组件 `.ts/.scss` 文件使用 `kebab-case` 格式，例如：`user-api.ts`, `login form.scss` - 页面文件命名与路由保持一致，使用 `kebab-case`，例如：`user-list.vue`, `role-edit.vue` # 样式和 CSS 使用约定 - **优先使用原子类：** 使用 UnoCSS 提供的原子类进行布局和样式，例如常见的 flex 布局（`flex justify-center items-center` 等）。样式语义明确，便于维护。 - **常用组合提取为全局快捷方式：** 对于**频繁使用**的原子类组合，应在 `unocss.config.ts` 中 通过 `shortcuts` 定义全局组合类。例如：将 `flex justify-center items-center` 定义为 `flex-center`，这样可以在整个项目中复用。组合类命名应简洁且语义化，反映布局或功能意图。 - **非常用组合使用局部类：** 对于特定组件中使用但不常见的、超过3个的原子类组合，应该在组件内使 用局部CSS类（使用`<style scoped>`块），避免过多的全局组合污染全局命名空间。 - **避免重复代码：** 不论是通过全局`shortcuts`还是局部CSS类，都应避免在多个地方重复编写相同 的原子类列表，保持代码 DRY（Don't Repeat Yourself）原则。 - **样式优先级：** 优先考虑 UnoCSS 解决方案（原子类或组合类），其次才是传统 CSS。当需要使用传 统 CSS 时，遵循 BEM 命名规范，即 `block__element--modifier` 格式。 # 导入顺序规范（保持统一结构） 1. Vue 相关 API（如 `ref`, `computed`, `onMounted`） 2. 第三方库（如 `element-plus`, `axios`） 3. 工具函数（如 `@/utils/*`） 4. 状态管理（如 `@/store/*`） 5. 项目内部组件、模块（如 `@/components`, `@/views`） 6. 样式文件 # 开发注意事项 - 使用 TypeScript，避免使用 `any`； - 组件职责单一，保持结构清晰； - 所有组件必须使用组合式 API； - 适当添加注释，提升 AI 理解。

3.3 Cursor 项目规则配置与使用

3.3.1 Cursor 规则文件创建方式

Cursor 有两种主要创建规则的方式：

1. 使用命令（推荐）：直接在 Cursor 的聊天框中输入/create-rule，然后描述你的需求，AI 会帮你生成规则文件并保存到正确位置。

2. 手动创建：在项目根目录下创建.cursor/rules文件夹，并在其中新建.mdc文件，按照上述格式编写即可。

3.3.2 Cursor 规则文件编写规范

1. 为了让 AI 更好地理解和执行，编写规则内容时有几个技巧：

1）明确角色与约束

像给新人布置任务一样，清晰地说明要求和“禁区”。例如，一个 Vue 3 项目的规则可以这样写

--- globs: "**/*.vue" alwaysApply: false --- # 角色 你是一名精通 Vue 3 的高级前端工程师。 # 【权重最高】禁止事项 - 严格禁止使用 Options API，必须使用 Composition API 和 `<script setup>` 语法。 - 禁止使用 `var` 关键字，变量声明统一使用 `const` 或 `let`。 - 禁止在 `template` 中编写复杂逻辑，应使用 `computed`。 # 推荐做法 - 组件命名使用 PascalCase，Props 命名使用 camelCase。 - 对于复杂类型，优先使用 TypeScript 的 `interface` 而非 `type`。

2）提供示例模板

直接给 AI 一个代码模板，比用文字描述“组件应该怎么组织”高效得多

## Vue 组件模板 请严格按照以下结构组织代码： ```vue <script setup lang="ts"> // 1. Props 定义 interface Props { title: string } const props = defineProps<Props>() // 2. Emits 定义 const emit = defineEmits<{ close: [] }>() // 3. 响应式状态与计算属性 const isActive = ref(false) // 4. 方法 </script> <template> <!-- 模板内容 --> </template>

这种方法能确保 AI 生成的代码结构一致性大幅提升

3）最佳实践技巧推荐

• 规则宜精不宜多：保持每条规则清晰、聚焦。如果规则超过500行，考虑将其拆分为多个更具体的规则文件。

• 善用.cursorignore：可以创建一个.cursorignore文件，让 AI 忽略node_modules、dist等构建目录，避免不必要的信息干扰。

• 把设计文档放进.cursor/：将项目架构图、技术方案等文档放在.cursor/文件夹下，AI 在生成代码时可以主动引用这些内容，更好地理解项目全局。

• 团队共享规则：将.cursor/rules目录提交到 Git 仓库，整个团队就能共享一套统一的 AI 开发规范。企业版用户还可以在后台设置强制生效的团队规则。

3.3.3 创建规则文件

可以手动创建规则文件，也可以通过内置的命令创建，手动创建方式如下：

• 说明：文件名可自定义，扩展名必须为 .mdc

# 第一步，创建规则文件的目录 mkdir -p .cursor/rules #创建规则文件 touch .cursor/rules/project-guidelines.mdc

如果是自动创建，打开Cursor 的编辑器Chat窗口，输入 / 并选择弹出的 Generate Cursor Rules 选项，即可自动生成 .cursor/rules/ 目录及默认的规则文件

我们用第二种方式来尝试一下，按照上一步，选中了 / create-rule 之后，在后面输入下面的提示词

经过一会儿的等待后，Cursor 读懂了我制定模块的项目，为我生成了项目介绍文档，并且是mdc格式的

3.3.4 规则应用

规则文件创建出来后，进入规则文件，可以看到上面有个下拉框，提供了几个选项

这几个选项的含义如下：

• Always：始终应用规则（想始终生效）

• Auto Attached：当匹配 globs 模式的文件被引用时自动附加规则（想自动触发用）

• Agent Requested：根据 AI 代理的判断决定是否应用规则，需要提供规则说明（想让 AI 自己决定是否用）

• Manual：仅在提示中显式使用 @规则名 时附加规则。（想手动调用规则）

3.3.5 规则文件使用示例

首先让Cursor 读懂项目之后生成一个API 设计规则，然后基于这个规则编写接口，给出如下提示词：

读懂 gh-pda 模块的项目开发规范，然后生成一个API 接口设计规范，后续我就与你共同持续完善这个接口设计文档

最后Cursor 为我们生成了我指定模块的api接口设计规范

• 实际使用时，还需要人工进行二次校对、完善这个文档

打开这份文档后，我选择了手动引用，然后在对话框那里可以看到已经可以看到上述创建成功的文件了

接下来，基于创建的API设计规则文件让Cursor 生成接口

补充说明：

• 通过自然语言提示词让Cursor 生成规则的方式更多适合于那种工程结构比较规范的场景，Cursor在生成规则文件时，会自动理解项目然后生成符合项目要求的规则

• 生成出来的规则文件，还需要人工做二次校对，比如调整其中有语法错误的内容，有明显逻辑漏洞的内容，甚至不符合要求的内容，同时，再根据实际要求补充一些Cursor 没有想到的

• 而全新的项目，则可以借助其他比较成熟完善的配置规则，然后在此基础上做一些调整适配即可使用

• 规则文件有多种，可以分目录存放，比如有项目描述规则文件，API接口设计规范文件，组件使用规则，SQL编写规范等

访问 cursor.directory，上面有大量针对不同技术栈（React、Vue、Python、Rust等）的现成规则，复制下来稍作修改即可使用。

3.3.6 规则文件如何编写

在上述案例操作中，演示了项目规则文件如何从0到1创建出来，事实上，如果你的项目已经比较成熟稳定，上面这种方式是最快捷的，如果你的项目还在规划、设计和成型中，可以手动编写，可以先制定API接口设计规范，后续再进行丰富完善即可，而规则文件内部的内容，网上有很多资料，首先文档格式必须为.mdc 结尾，本质就是Markdown 文档，但具有特殊结构。以下以开源项目 vue3-element-admin 为例，给出适用于 Vue 3 + TypeScript 项目的推荐规则模板写法，可做参考：

# 项目基础说明 - 本项目基于 Vue 3 + TypeScript + Element Plus + Pinia + Vite 搭建。 - 采用组合式 API（`<script setup lang="ts">`）进行开发。 - 状态管理使用 Pinia，模块化组织。 - 路由使用 Vue Router，采用权限动态路由配置。 - 接口请求统一封装在 `@/utils/request.ts` 中，使用 Axios。 - 表格、表单页面基于 Element Plus 封装通用组件，提高复用性。 # 组件和文件命名规范 - 组件文件名使用 `PascalCase` 格式，例如：`UserTable.vue`, `LoginForm.vue` - 公共组件放置在 `src/components/` 下，业务组件可放在 `src/views/模块/components/` 中 - 文件夹名和非组件 `.ts/.scss` 文件使用 `kebab-case` 格式，例如：`user-api.ts`, `login form.scss` - 页面文件命名与路由保持一致，使用 `kebab-case`，例如：`user-list.vue`, `role-edit.vue` # 样式和 CSS 使用约定 - **优先使用原子类：** 使用 UnoCSS 提供的原子类进行布局和样式，例如常见的 flex 布局（`flex justify-center items-center` 等）。样式语义明确，便于维护。 - **常用组合提取为全局快捷方式：** 对于**频繁使用**的原子类组合，应在 `unocss.config.ts` 中 通过 `shortcuts` 定义全局组合类。例如：将 `flex justify-center items-center` 定义为 `flex-center`，这样可以在整个项目中复用。组合类命名应简洁且语义化，反映布局或功能意图。 - **非常用组合使用局部类：** 对于特定组件中使用但不常见的、超过3个的原子类组合，应该在组件内使 用局部CSS类（使用`<style scoped>`块），避免过多的全局组合污染全局命名空间。 - **避免重复代码：** 不论是通过全局`shortcuts`还是局部CSS类，都应避免在多个地方重复编写相同 的原子类列表，保持代码 DRY（Don't Repeat Yourself）原则。 - **样式优先级：** 优先考虑 UnoCSS 解决方案（原子类或组合类），其次才是传统 CSS。当需要使用传 统 CSS 时，遵循 BEM 命名规范，即 `block__element--modifier` 格式。 # 导入顺序规范（保持统一结构） 1. Vue 相关 API（如 `ref`, `computed`, `onMounted`） 2. 第三方库（如 `element-plus`, `axios`） 3. 工具函数（如 `@/utils/*`） 4. 状态管理（如 `@/store/*`） 5. 项目内部组件、模块（如 `@/components`, `@/views`） 6. 样式文件 # 开发注意事项 - 使用 TypeScript，避免使用 `any`； - 组件职责单一，保持结构清晰； - 所有组件必须使用组合式 API； - 适当添加注释，提升 AI 理解。

3.3.7 Cursor 规则使用技巧补充

下面再结合实际经验补充一些常用的使用技巧

• 拆分规则主题： 可以为不同模块分别写规则，比如 style-guidelines.mdc、project-structure.mdc、component-conventions.mdc，让 AI 更易查阅上下文

• 越具体越好： 你越明确规则，Cursor 越能准确给出符合你期望的代码。避免废话和废规则： Focuson 可执行、可操作、可验证的规则。比如“命名要清晰”不如“类名采用 BEM 规范并用小写字母连接” 具体有效

• 随项目迭代更新规则： 规则应当与代码保持同步更新，特别是引入新的库、工具、编码风格变更时

3.3.8 Cursor 进阶规则使用技巧

对于复杂项目，建议采用三层结构，职责分离，下面给出一个示例参考规范配置结构

.cursor/rules/ ├── ai.mdc # AI 协作总纲（定义执行流程） ├── basic/ # 基础规范层 │ ├── typescript.mdc │ ├── code-quality.mdc │ └── naming.mdc ├── modules/ # 模块规范层 │ ├── components.mdc │ ├── service.mdc │ └── hooks.mdc └── workflow/ # 流程规范层 ├── curd-page.mdc └── log.mdc

3.3.9 最佳实践建议

下面结合实践中的操作，给出一些最佳实践建议

四、写在文末

本文通过较大的篇幅详细介绍了Curosr 中自定义配置规则的使用，并通过项目实际操作演示了具体的用法，希望对看到的同学有帮助，本篇到此结束感谢观看。