Cursor Rules 完全指南

掌握 AI 编码助手的秘密武器

系统: Project Rules (.cursor/rules/) + User Rules | 格式: MDC (Markdown Components) | 应用: 智能上下文注入

📊 Cursor Rules 核心数据

🎯 什么是 Cursor Rules？

Cursor Rules 是项目特定的指令和指南，告诉 Cursor AI 如何为你的项目生成代码。

核心价值

🏗️ Cursor Rules 系统架构

整体架构图

📁 规则类型详解

1. 项目规则 (Project Rules)

存储位置： .cursor/rules/

特点：

• ✅ 版本控制（Git 跟踪）
• ✅ 团队共享
• ✅ 项目特定
• ✅ MDC 格式

结构：

project/
├── .cursor/
│   └── rules/
│       ├── base.mdc              # 基础规则
│       ├── typescript.mdc        # TypeScript 规范
│       ├── react.mdc             # React 最佳实践
│       └── api-design.mdc        # API 设计规范
├── backend/
│   └── .cursor/rules/
│       └── backend-specific.mdc  # 后端特定规则
└── frontend/
    └── .cursor/rules/
        └── frontend-specific.mdc # 前端特定规则

2. 用户规则 (User Rules)

存储位置： Cursor Settings → Rules

特点：

• ✅ 全局应用
• ✅ 个人偏好
• ✅ 跨项目使用
• ❌ 不能版本控制

适用场景：

• 个人编码风格
• 常用工具偏好
• 通信方式设定

3. 遗留规则 (.cursorrules)

存储位置： 项目根目录 .cursorrules

状态： ⚠️ 已弃用，建议迁移到 Project Rules

🎛️ 规则应用类型

应用类型详解

应用类型选择决策树

📝 MDC 格式详解

MDC 文件结构

MDC (Markdown Components) 是 Cursor 项目规则的标准格式。

MDC 完整示例

---
description: TypeScript 最佳实践和编码规范
globs:
- "**/*.ts"
- "**/*.tsx"
alwaysApply: true
tags:
- typescript
- coding-standards
priority: high

🚀 创建 Cursor Rules

创建流程

步骤详解

步骤 1: 创建规则目录

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

# 创建子模块规则目录（可选）
mkdir -p backend/.cursor/rules
mkdir -p frontend/.cursor/rules

步骤 2: 创建第一个规则

# 创建基础规则文件
touch .cursor/rules/base.mdc

基础模板：

---
description: 项目基础编码规范
alwaysApply: true
---

步骤 3: 创建特定规则

React 组件规则：

cat > .cursor/rules/react.mdc << 'EOF'
---
description: React 组件开发规范
globs:
- "**/*.tsx"

API 设计规则：

cat > .cursor/rules/api-design.mdc << 'EOF'
---
description: REST API 设计规范
globs:
- "**/api/**/*.ts"
- "**/routes/**/*.ts"
alwaysApply: false
tags:
- api
- backend

🎨 规则设计最佳实践

10 条黄金法则

规则编写模板

📚 实战示例库

示例 1: Next.js + TypeScript 规则

---
description: Next.js 13+ App Router 开发规范
globs:
- "**/app/**/*.tsx"
- "**/app/**/*.ts"
alwaysApply: false
tags:
- nextjs
- app-router
---

示例 2: 测试规范

---
description: Jest + React Testing Library 测试规范
globs:
- "**/*.test.ts"
- "**/*.test.tsx"
- "**/__tests__/**"
alwaysApply: false
tags:
- testing
- jest

示例 3: 性能优化规则

---
description: Web 性能优化最佳实践
alwaysApply: false
tags:
- performance
- optimization
---

# 性能优化规范

🔄 规则应用流程

规则加载与应用

🎓 高级技巧

技巧 1: 规则层次化

技巧 2: 使用标签组织

---
description: React Hooks 规范
tags:
- react
- hooks

技巧 3: 规则版本管理

---
description: API 设计规范 v2.0
tags:
- api
- version:2.0

技巧 4: 条件规则

---
description: TypeScript 严格模式
globs:
- "**/*.ts"
- "**/*.tsx"

技巧 5: 规则引用

---
description: 完整的 React 规范
---

# React 开发规范

🔍 规则测试与验证

测试流程

测试清单

## 规则测试清单

### 功能测试
- [ ] 规则在预期场景下正确应用
- [ ] 生成的代码符合规则要求
- [ ] 规则不干扰非相关代码

### 边界测试
- [ ] 处理空输入
- [ ] 处理极大输入
- [ ] 处理特殊字符
- [ ] 处理嵌套结构

### 错误测试
- [ ] 正确识别反模式
- [ ] 提供有用的错误提示
- [ ] 不产生误报

### 性能测试
- [ ] 规则加载时间 < 100ms
- [ ] 不显著影响 AI 响应速度
- [ ] 上下文大小合理 (< 10KB)

### 集成测试
- [ ] 与其他规则兼容
- [ ] 不产生冲突规则
- [ ] 优先级正确

### 用户体验
- [ ] 规则描述清晰
- [ ] 示例代码完整
- [ ] 错误信息有帮助

📦 规则管理

团队协作

.cursor/
├── rules/
│   ├── README.md           # 规则文档
│   ├── base.mdc
│   ├── frontend/
│   │   ├── react.mdc
│   │   ├── nextjs.mdc
│   │   └── styling.mdc
│   ├── backend/
│   │   ├── api-design.mdc
│   │   ├── database.mdc
│   │   └── security.mdc
│   └── testing/
│       ├── unit-tests.mdc
│       └── e2e-tests.mdc
└── .gitignore

.cursor/rules/README.md:

# 项目 Cursor Rules

## 概览

本目录包含项目的 Cursor AI 规则配置。

🚀 最佳实践总结

Dos ✅

1. ✅ 明确版本 - 指定框架和库的版本
2. ✅ 提供示例 - 包含完整的代码示例
3. ✅ 标记废弃 - 明确指出过时的模式
4. ✅ 解释原因 - 说明为什么推荐某种做法
5. ✅ 保持更新 - 随项目演进更新规则
6. ✅ 组织清晰 - 使用层次结构和标签
7. ✅ 测试充分 - 覆盖各种场景
8. ✅ 文档完善 - 添加 README 和注释
9. ✅ 版本控制 - 提交到 Git 便于追踪
10. ✅ 团队协作 - 通过 PR 审查规则

Don’ts ❌

1. ❌ 过度冗长 - 避免规则文件超过 500 行
2. ❌ 模糊描述 - 不要使用含糊的语言
3. ❌ 缺少示例 - 仅有规则没有示例
4. ❌ 忽略测试 - 未验证规则效果
5. ❌ 单一文件 - 所有规则塞在一个文件
6. ❌ 缺少上下文 - 不说明适用场景
7. ❌ 过时信息 - 包含已废弃的做法
8. ❌ 冲突规则 - 规则之间相互矛盾
9. ❌ 忽视性能 - 规则过大影响响应速度
10. ❌ 单打独斗 - 不与团队讨论规则

📚 学习资源

官方资源

• 🌐 Cursor 官方文档
• 📖 Cursor Rules for AI

社区资源

• 📄 Awesome Cursor Rules - 1000+ 社区规则
• 🎯 Cursor Directory - 规则模板库
• 📝 DotCursorRules - 规则生成器
• 🤖 CursorRules.org - 免费 AI 生成器

技术文章

• How to Write Great Cursor Rules - Trigger.dev
• Getting Better Results from Cursor AI
• Mastering Cursor Configuration

🎯 下一步行动

快速开始

1. 创建规则目录

   mkdir -p .cursor/rules

2. 从模板开始

   • 访问 cursor.directory
   • 选择适合的技术栈模板
   • 下载并定制化

3. 测试规则

   在 Composer 中输入: "根据项目规则创建一个 React 组件"

4. 迭代优化

   • 收集团队反馈
   • 分析 AI 生成质量
   • 持续改进规则

进阶路线

💡 总结

Cursor Rules 是 AI 编码助手的秘密武器：

核心价值：

• 🎯 代码一致性 - 统一团队编码风格
• 🚀 开发效率 - AI 生成符合规范的代码
• 📚 知识共享 - 将最佳实践编码化
• 🛡️ 质量保证 - 预防常见错误

三大规则类型：

1. 项目规则 - .cursor/rules/ (版本控制，团队共享)
2. 用户规则 - Settings (个人偏好，全局应用)
3. 遗留规则 - .cursorrules (已弃用，建议迁移)

四种应用方式：

• Always - 始终应用
• Auto Attached - 模式匹配
• Agent Requested - 智能选择
• Manual - 手动附加

开始使用 Cursor Rules，让 AI 真正理解你的项目！ 🚀