Cursor规则
Cursor 规则是 Cursor AI 编辑器中使用的一套 AI 行为约束与约定机制，通过用户规则和项目规则两个层级，确保 AI 在代码生成、建议和分析过程中保持一致性与可控性
1. 概念介绍
1.1 Cursor 规则概述
Cursor 规则是一个分层的配置系统，用于指导 AI 助手在代码生成、建议和分析过程中的行为。它由两个互补的层级组成：
- 用户规则（User Rules）：存储在 Cursor 设置中的全局规则，适用于所有项目
- 项目规则（Project Rules）：存储在项目
.cursor/rules/目录中的特定规则，仅适用于当前项目
1.2 规则的核心作用
规则系统主要解决四个问题：
- 保持一致 - AI 按统一标准工作，代码风格统一
- 个性定制 - 适应你的习惯和项目需求
- 提升质量 - 减少错误，自动应用最佳实践
- 提高效率 - 减少重复说明，AI 更准确
1.3 规则优先级体系
项目规则 > 用户规则 > 默认行为
这种设计确保了灵活性：用户规则提供一致的个人偏好基线，项目规则可以根据特定需求进行覆盖和补充。
2. 规则配置详解
2.1 用户规则格式
存储位置：Cursor Settings → Rules & Memories → User Rules(不同版本可能有差异)
用户规则特性：
| 特性 | 说明 |
|---|---|
| 格式支持 | 纯文本 |
| 生效范围 | 全局，所有项目自动应用 |
| 版本控制 | 不纳入项目版本控制 |
| 修改权限 | 个人设置，不影响团队成员 |
| 优先级 | 低于项目规则 |
2.2 项目规则格式（MDC）
存储位置：项目根目录 .cursor/rules/*.mdc
格式：MDC（Markdown with Components）
作用范围：当前项目
MDC 文件结构：
---
description: "规则的简短描述"
globs: **/*.ts,**/*.tsx
alwaysApply: true
---
# 规则标题
规则的具体内容...
2.3 MDC 元数据字段详解
| 字段 | 类型 | 必需 | 默认值 | 描述 |
|---|---|---|---|---|
description | string | Apply Intelligently 模式必须 | - | 规则的简短描述，用于 AI 智能判断适用场景 |
globs | string | 否 | **/* | 文件匹配模式，用逗号分隔多个模式 |
alwaysApply | boolean | 否 | false | 是否在所有上下文中强制应用 |
2.4 规则应用模式
Cursor 提供四种规则应用模式，满足不同场景的需求：
模式 1：Always Apply（总是应用）
配置方式：
---
alwaysApply: true
---
特点：
- 在所有对话、编辑、补全中自动应用
- 适用于全局性的规范要求
适用场景：
- 安全规范（如禁止硬编码密钥）
- 代码格式要求（如缩进、命名规范）
- 错误处理标准
模式 2：Apply Intelligently（智能应用）
配置方式：
---
description: "React Hooks 使用规范"
---
特点：
- AI 根据
description和上下文智能判断是否应用 - 无需手动指定文件模式
- 灵活性强，减少配置复杂度
适用场景：
- 特定技术栈的最佳实践（AI 可判断何时相关）
- 业务领域规范（如"支付模块必须有事务处理"）
- 复杂的条件性规则
模式 3：Apply to Specific Files（应用到特定文件）
配置方式：
---
description: "TypeScript 类型定义规范"
globs: **/*.ts,**/*.tsx
---
特点：
- 精确控制规则应用范围
- 基于文件路径模式匹配
适用场景：
- 特定文件类型的规则（如测试文件、配置文件）
- 特定目录的规则（如组件目录、工具目录）
- 需要精确控制作用范围的规则
示例：
# 匹配特定文件类型
globs: **/*.ts,**/*.tsx
# 匹配特定目录
globs: src/components/**/*
# 匹配测试文件
globs: **/*.test.ts,**/*.spec.ts,**/__tests__/**
# 匹配多种文件类型和目录
globs: **/*.js,**/*.jsx,src/utils/**/*,src/hooks/**/*
Globs 生效时机：
当你打开、编辑文件或使用 AI 补全/Chat 时，Cursor 会根据当前文件路径匹配相应的规则。
匹配机制示例：
- 编辑
src/components/Button.tsx时，会应用所有匹配该路径的规则 - 例如：
**/*.tsx（匹配所有 TypeScript React 文件）、src/components/**/*（匹配组件目录下所有文件）
Globs 匹配机制确保了不同类型的文件能够应用最适合的规则配置。
模式 4：Apply Manually（手动应用）
配置方式：
创建规则文件（如 legacy-code.mdc），不设置 alwaysApply 或 globs
使用方式：
在对话中通过 @ 符号手动引用：
@legacy-code 帮我重构这段代码
特点：
- 完全由用户控制何时应用
- 不会自动触发
- 可作为临时规则或特殊场景规则
适用场景：
- 遗留代码重构指导
- 特殊的一次性任务规则
- 实验性规范
2.5 规则管理与调试
切换规则类型
在 Cursor 中打开规则文件后，通过顶部的类型下拉菜单选择规则类型，该操作会自动更新 description、globs 和 alwaysApply 属性。
查看已启用的规则
已启用的规则会显示在 Agent 对话框的上下文管理栏（顶部），如下图所示：
如上图所示，编号 2 处展示了激活的两条规则（一条为 alwaysApply: true 的全局应用规则，另一条为通过 globs 匹配到当前文件的规则）。tab 指示的是你正在编辑的文件。
排查规则问题
如果规则没生效，可以在规则设置中看到错误信息，如下图：
3. 最佳实践
3.1 规则编写技巧
具体明确，避免模糊
不好的规则：
- "代码要写得好"
- "保持良好的代码风格"
- "注意性能优化"
好的规则：
- "使用 2 空格缩进，不使用 Tab"
- "函数命名使用驼峰命名法，类使用 PascalCase"
- "列表渲染超过 100 项时使用虚拟滚动"
分层设计规则
通用规则（alwaysApply: true）：
- 安全规范
- 错误处理
- 代码格式
特定规则（globs:xx）：
- 特定框架约定（React、Vue）
- 特定文件类型（测试、配置）
- 特定业务场景
3.2 规则文件组织
推荐的目录结构
.cursor/rules/
├── README.md # 规则文档说明
├── core/ # 核心规则（alwaysApply: true）
│ ├── security.mdc # 安全规范
│ ├── errors.mdc # 错误处理
│ └── format.mdc # 代码格式
├── languages/ # 语言特定规则
│ ├── typescript.mdc
│ └── python.mdc
├── frameworks/ # 框架规则
│ └── react.mdc
└── project-specific/ # 项目特定规则
├── api.mdc
└── database.mdc
3.3 版本控制与团队协作
规则文件纳入版本控制
.gitignore 中不要忽略 .cursor 目录
4. 实用示例
4.1 用户规则示例
用户规则采用纯文本格式，在 Cursor 设置中配置，适用于所有项目：
1. 语言与注释
- 默认使用中文回答问题，除非用户特别要求英文
- 默认使用英文代码注释，除非特别要求中文
- 公共 API 使用 JSDoc/TSDoc 格式
2. 回答风格
- 尽量简洁明了，避免不必要的废话和重复说明
- 先给出关键答案，再提供简短解释或示例
3. 安全与稳健性（最高优先级）
- 绝对禁止硬编码任何敏感信息（密码、API密钥、IP）
- 所有配置必须从环境变量或配置文件中读取
- 必须进行错误处理，对可能失败的操作使用 try-catch 或等效机制
4. 代码整洁与可维护性（参考《代码整洁之道》）
- 函数短小且单一职责，每个函数只做一件事
- 变量、函数、类命名语义清晰，易读易理解
- 避免重复代码（遵循 DRY 原则）
- 错误处理明确且一致，保证程序健壮
- 模块和类职责明确，依赖清晰，便于扩展和维护
5. 设计模式规范
- 优先使用常见设计模式优化结构与扩展性。
- 推荐使用的设计模式：
- 单例模式（Singleton）：用于全局唯一实例。
- 工厂方法模式（Factory Method）：避免直接实例化，提升可扩展性。
- 策略模式（Strategy）：将可变行为封装为可替换策略。
- 观察者模式（Observer）：用于事件驱动和响应式设计。
- 装饰器模式（Decorator）：在不修改原类的情况下动态扩展功能。
- 命令模式（Command）：将操作封装为对象，便于撤销与队列化。
- 适配器模式（Adapter）：用于兼容不同接口的组件。按这个格式修改
- Proxy（代理模式）：控制访问或增强功能（缓存、安全、远程访问）
4.2 项目规则示例
项目规则采用 MDC 格式，存储在 .cursor/rules/ 目录中，仅适用于当前项目。以下展示不同应用模式的实际使用场景：
示例 1：Always Apply - 安全规范
.cursor/rules/core/security.mdc：
---
description: "全局安全规范，所有代码必须遵守"
alwaysApply: true
---
# 安全规范
## 敏感信息处理
- 绝对禁止硬编码任何敏感信息（密码、API密钥、IP地址、Token）
- 所有配置必须从环境变量或加密配置文件中读取
- 使用 `.env.example` 提供配置模板，真实配置文件加入 `.gitignore`
## 数据验证
- 所有用户输入必须进行验证和清理
- API 请求参数必须进行类型检查和范围验证
- 数据库查询使用参数化查询，防止 SQL 注入
示例 2：Apply Intelligently - 框架最佳实践
.cursor/rules/frameworks/react-hooks.mdc：
---
description: "React Hooks 使用规范和最佳实践"
---
# React Hooks 规范
AI 会在检测到 React Hooks 相关代码时自动应用此规则。
## Hooks 使用规则
- 只在 React 函数组件或自定义 Hooks 中调用 Hooks
- 不在循环、条件或嵌套函数中调用 Hooks
- 自定义 Hook 必须以 `use` 开头命名
## 依赖数组规范
- useEffect/useMemo/useCallback 必须正确声明依赖项
- 避免遗漏依赖导致的过期闭包问题
- 对象和函数依赖应该用 useMemo/useCallback 包装
示例 3：Apply to Specific Files - TypeScript 类型规范
.cursor/rules/languages/typescript.mdc：
---
description: "TypeScript 类型定义和使用规范"
globs: **/*.ts,**/*.tsx
---
# TypeScript 规范
## 类型定义
- Props 接口使用 `interface` 定义并导出
- 工具类型使用 `type` 定义
- 避免使用 `any`，优先使用具体类型或泛型
- 使用 `unknown` 替代 `any` 处理不确定类型
## 组件类型
- React 组件 Props 必须有完整的类型定义
- 函数组件使用 `React.FC` 或显式声明返回类型
- 事件处理函数使用正确的事件类型（如 `React.ChangeEvent<HTMLInputElement>`）
示例 4：Apply Manually - 遗留代码处理
.cursor/rules/project-specific/legacy-refactor.mdc：
---
description: "遗留代码重构指南，需手动引用"
---
# 遗留代码重构指南
通过 @legacy-refactor 手动引用此规则
## 重构策略
- 保持原有功能不变，先添加测试用例
- 逐步替换旧 API，保持向后兼容
- 使用适配器模式过渡新旧实现
- 重构完成后更新文档和注释
## 临时豁免
遗留代码重构期间允许：
- 使用 `@ts-ignore` 标记已知类型问题
- 保留部分 `any` 类型（需添加 TODO 注释）
- 暂不强制执行最新的代码规范
总结：
有效的 Cursor 规则体系需要持续迭代和优化。从简单的个人偏好开始，逐步构建团队共享的规则库，结合版本控制和团队协作流程，最终形成提升开发效率和代码质量的强大工具。