Cursor Rules配置指南：如何自定义AI代码辅助规则

分类：配置与优化

Cursor Rules是一套强大的配置系统，让你能够自定义AI代码辅助的行为。通过创建.mdc文件，你可以告诉AI遵循特定的编程规范、架构模式和项目约定，从而获得更精准的代码建议和帮助。

什么是Cursor Rules？

Cursor Rules是一种配置机制，允许你为AI提供持久性的上下文和指导。它解决了AI模型无法在会话间保持记忆的问题，通过规则文件为不同的项目场景提供针对性的指导。

  • 持久化指导：在所有Chat和内联编辑中保持一致的AI行为
  • 项目特定：为不同项目设置不同的编程规范和约定
  • 版本控制：规则文件可以与代码一起进行版本管理
  • 团队协作：确保团队成员获得一致的AI建议

规则类型详解

Cursor支持四种不同类型的规则，每种都有不同的触发条件和使用场景：

1. Always（始终应用）

这类规则会在所有AI交互中自动加载到上下文中。

---
description: 
globs: 
alwaysApply: true
---

使用TypeScript严格模式
总是使用const而不是let，除非变量需要重新赋值
遵循项目的命名约定

2. Auto Attached（自动附加）

当你在聊天中附加或提到匹配特定模式的文件时，这类规则会自动激活。

---
description: 
globs: src/**/*.tsx,src/**/*.jsx
alwaysApply: false
---

React组件开发规范：
- 使用函数组件而不是类组件
- 使用TypeScript接口定义Props
- 组件文件名使用PascalCase

3. Agent Requested（AI主动请求）

AI会根据描述判断是否需要使用这个规则。需要提供清晰的描述。

---
description: 编写或修改API端点时使用的验证规则
globs: 
alwaysApply: false
---

API开发规范：
- 所有端点必须使用Zod进行输入验证
- 返回统一的错误格式
- 包含适当的HTTP状态码

4. Manual（手动引用）

只有当你在聊天中明确提到这个规则时才会激活。

---
description: 
globs: 
alwaysApply: false
---

数据库操作模板：
- 使用事务处理敏感操作
- 实现适当的错误处理和回滚
- 包含操作日志记录

创建和管理Rules

方法一：使用Cursor设置界面（推荐）

  1. 打开Cursor设置（Ctrl+Shift+J 或 Cmd+Shift+J）
  2. 找到"Rules"部分
  3. 在"Project Rules"区域点击"+ Add new rule"
  4. 填写规则名称（会自动添加.mdc扩展名）
  5. 选择规则类型和配置相应选项
  6. 在编辑器中写入规则内容

方法二：手动创建文件

  1. 在项目根目录创建 .cursor/rules 文件夹
  2. 创建 .mdc 扩展名的文件
  3. 按照标准格式编写规则内容

💡 命名建议

使用数字前缀来控制规则优先级：001-099（核心规则）、100-199（集成规则）、200-299（模式规则）

实用配置示例

示例1：前端组件规范(前端最佳实践：前端开发中使用Cursor AI提高效率)

---
description: React组件开发标准和样式指南
globs: src/components/**/*.tsx
alwaysApply: false
---

前端组件开发规范：

## 组件结构
- 使用函数组件 + TypeScript
- Props接口定义在组件文件顶部
- 使用默认导出

## 样式规范
- 优先使用Tailwind CSS类
- 复杂动画使用Framer Motion
- 避免内联样式

## 示例模板：
```typescript
interface ComponentProps {
  title: string;
  children?: React.ReactNode;
}

const Component: React.FC = ({ title, children }) => {
  return (
    

      
{title}

      {children}
    

  );
};

export default Component;
```

示例2：API开发规范

---
description: 编写API端点时的验证和错误处理规范
globs: src/api/**/*.ts,src/routes/**/*.ts
alwaysApply: false
---

API开发规范：

## 输入验证
- 使用Zod schema验证所有输入
- 定义完整的类型定义
- 导出生成的TypeScript类型

## 错误处理
- 统一错误响应格式
- 使用适当的HTTP状态码
- 包含详细的错误信息

## 示例：
```typescript
const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
});

type CreateUserRequest = z.infer;

export async function createUser(req: Request) {
  try {
    const data = CreateUserSchema.parse(req.body);
    // 处理逻辑
    return { success: true, data: user };
  } catch (error) {
    return { 
      success: false, 
      error: "验证失败",
      details: error.issues 
    };
  }
}
```

示例3：测试编写指南

---
description: 编写或修改测试文件时使用
globs: **/*.test.ts,**/*.spec.ts,src/__tests__/**/*.ts
alwaysApply: false
---

测试编写指南：

## 测试结构
- 使用describe/it的嵌套结构
- 每个测试应该独立且可重复
- 使用清晰的测试描述

## 命名约定
- describe: 描述被测试的功能模块
- it: 描述具体的测试场景
- 使用"should"开头描述期望行为

## 示例：
```typescript
describe('UserService', () => {
  describe('createUser', () => {
    it('should create user with valid data', () => {
      // 测试逻辑
    });
    
    it('should throw error with invalid email', () => {
      // 测试逻辑
    });
  });
});
```

高级功能

文件引用

你可以在规则中引用其他文件作为额外的上下文：

---
description: 使用项目架构模板
globs: src/**/*.ts
alwaysApply: false
---

项目架构规范：
参考以下模板文件进行开发：

@src/templates/service-template.ts
@src/templates/component-template.tsx

遵循这些模板的结构和模式。

嵌套规则

你可以在项目的不同目录中创建特定的规则目录：

project/
  .cursor/rules/           # 项目级别规则
  frontend/
    .cursor/rules/         # 前端特定规则
  backend/
    server/
      .cursor/rules/       # 后端服务特定规则

最佳实践

规则编写原则

  • 保持规则简洁，单个规则不超过500行
  • 将大规则拆分为多个可组合的小规则
  • 提供具体的代码示例而不是模糊的描述
  • 使用清晰的内部文档风格编写规则
  • 定期更新规则以反映项目演进

文件组织建议

  • 使用有意义的文件名，如 001-core-typescript.mdc
  • 按功能模块组织规则，而不是按文件类型
  • 为重要规则添加版本号和更新日期
  • 在团队中建立规则评审流程

常见问题解决

Q1：规则没有生效怎么办？

A：检查以下几点：

  • 确认文件扩展名是 .mdc
  • 验证frontmatter格式正确
  • 对于Auto Attached规则，确保文件模式匹配
  • 对于Agent Requested规则，确保有清晰的描述
  • 重启新的聊天会话

Q2：规则文件修改后丢失了？

A：这是已知问题，解决方法：

  1. 完全关闭Cursor
  2. 重新打开时会出现"未保存更改"提示
  3. 选择"Override"覆盖
  4. 重新打开Cursor

Q3：如何调试规则是否被加载？

A：你可以：

  • 在AI聊天中询问当前有哪些规则生效
  • 查看Cursor设置中的Rules部分
  • 在规则中添加标识性文本来确认加载

Q4：规则之间发生冲突怎么办？

A：Cursor的冲突解决机制：

  • 数字较大的规则文件优先级更高
  • 嵌套目录中的规则优先于父目录
  • 后加载的规则会覆盖先加载的冲突部分
  • 建议通过命名和组织避免冲突

用户规则vs项目规则

特性 用户规则 项目规则
作用范围 所有项目全局生效 仅在当前项目中生效
存储位置 Cursor设置中 .cursor/rules目录
版本控制 不支持 ✅ 支持版本控制
团队共享 不支持 ✅ 可团队共享
文件引用 不支持 ✅ 支持引用项目文件
适用场景 个人偏好设置 项目特定规范

总结

Cursor Rules是一个强大而灵活的系统，可以显著提升AI代码辅助的质量和针对性。通过合理配置规则，你可以：

  • 确保AI理解并遵循项目的编程规范
  • 提供项目特定的上下文和约定
  • 在团队中保持一致的代码风格和架构模式
  • 减少重复性的提示和说明

开始时建议从简单的规则开始，逐步完善和扩展。记住，好的规则应该是清晰、具体且可操作的，这样AI才能提供最有价值的帮助。

相关问题