最佳实践指南

💡 最大化发挥 Cursor AI 规则的价值

规则选择策略

新项目 vs 现有项目

项目类型	推荐策略	说明
新项目	选择完整规则集	从项目开始就建立规范，如 `nextjs-typescript`
现有项目	渐进式引入	从 `general/code-guidelines` 开始，逐步引入
团队项目	选择熟悉技术栈	根据团队技能选择，确保可维护性
学习项目	选择教育型规则	带有详细注释的规则集

技术栈匹配表

前端框架

React → rules/frontend/react/nextjs-typescript/
Vue   → rules/frontend/vue/composition-api/
Angular → rules/frontend/angular/angular-typescript/
Svelte → rules/frontend/svelte/sveltekit-tailwind-typescript-guide/

后端语言

Python   → rules/backend/python/fastapi-api-example/
Node.js  → rules/backend/nodejs/nestjs-typescript/
Go       → rules/backend/go/backend-scalability/
Java     → rules/backend/java/springboot-jpa/
PHP      → rules/backend/php/laravel-php-83/

移动端开发

Flutter       → rules/mobile/flutter/flutter-app-expert/
React Native  → rules/mobile/react-native-expo/
SwiftUI       → rules/mobile/swiftui-guidelines/
Android       → rules/mobile/android/modern-android/

项目配置实践

单技术栈项目

对于单一技术栈项目，直接复制对应规则：

bash

# Next.js 项目示例
cp rules/frontend/react/nextjs-typescript/.cursorrules ./

多技术栈项目

方案一：合并规则文件

bash

# 创建合并后的规则
cat rules/frontend/react/nextjs-typescript/.cursorrules > .cursorrules
echo "" >> .cursorrules
echo "# ===== 后端规则 =====" >> .cursorrules
echo "" >> .cursorrules
cat rules/backend/python/fastapi-api-example/.cursorrules >> .cursorrules

方案二：目录级规则（推荐）

bash

# 项目根目录 - 通用规则
cp rules/general/code-guidelines/.cursorrules ./

# frontend/ 目录 - 前端规则
cp rules/frontend/react/nextjs-typescript/.cursorrules frontend/

# backend/ 目录 - 后端规则  
cp rules/backend/python/fastapi-api-example/.cursorrules backend/

💡 优势：各模块独立管理，避免规则冲突

验证配置

bash

# 检查文件存在
ls -la .cursorrules

# 查看文件内容
cat .cursorrules

# 验证文件编码
file .cursorrules  # 应显示: UTF-8 Unicode text

# 检查文件大小（建议 < 50KB）
ls -lh .cursorrules

团队协作指南

版本控制

必须将 .cursorrules 加入 Git 管理：

bash

# 添加规则文件
git add .cursorrules

# 提交
git commit -m "chore: add team coding rules configuration

- Add Cursor AI coding rules for project consistency
- Based on nextjs-typescript and fastapi best practices"

git push

⚠️ 重要：不要将 .cursorrules 加入 .gitignore

团队文档模板

在项目 README 中添加 Cursor 配置说明：

markdown

## 开发环境配置

本项目使用 Cursor AI 编程规则统一代码规范。

### 必要步骤

1. 安装 [Cursor 编辑器](https://cursor.sh/)
2. 确保项目根目录有 `.cursorrules` 文件
3. 在 Cursor 设置中启用 "Use .cursorrules" 选项

### 规则说明

- **技术栈**: Next.js + TypeScript + Tailwind CSS
- **后端**: Python FastAPI
- **规则来源**: [awesome-cursorrules-zh](https://github.com/LessUp/awesome-cursorrules-zh)

### 自定义规则

如需添加项目特定规则，请在 `.cursorrules` 文件末尾添加，
不要修改现有规则内容。

团队规则模板库

创建团队模板目录供成员选择：

bash

# 创建模板目录
mkdir -p .cursorrules-templates

# 保存常用规则模板
cp rules/frontend/react/nextjs-typescript/.cursorrules .cursorrules-templates/frontend.cursorrules
cp rules/backend/python/fastapi-api-example/.cursorrules .cursorrules-templates/backend.cursorrules
cp rules/general/code-guidelines/.cursorrules .cursorrules-templates/general.cursorrules

# 添加模板说明
cat > .cursorrules-templates/README.md << 'EOF'
# 团队规则模板

## 使用说明

根据项目类型选择对应的模板文件：

- `frontend.cursorrules` - 前端项目
- `backend.cursorrules` - 后端项目  
- `general.cursorrules` - 通用规范

## 应用模板

```bash
cp .cursorrules-templates/frontend.cursorrules ./.cursorrules

EOF


---

## 规则编写规范

### 规则结构

一个良好的 `.cursorrules` 文件应包含：

```markdown
# 项目编程规范

## 概述
- 项目简述
- 技术栈说明
- 设计原则

## 编码规范

### 命名规范
- 变量命名
- 函数命名
- 文件命名

### 代码结构
- 文件组织
- 模块划分
- 导入规范

### 错误处理
- 异常策略
- 日志规范

### 性能优化
- 最佳实践
- 避免事项

## 框架特定规范
（根据技术栈添加）

规则编写最佳实践

实践	说明	示例
具体明确	避免模糊描述	❌ "使用好的命名" → ✅ "组件使用 PascalCase"
提供示例	复杂规则给出示例	"错误处理示例: try { ... } catch (e) { logger.error(e) }"
分类组织	按功能分组	编码规范 / 架构规范 / 测试规范
保持简洁	只保留必要规则	单条规则控制在 200 字以内
优先级排序	重要规则放前面	架构 > 编码 > 风格

自定义规则模板

markdown

## [项目名] 自定义规则

### 项目规范
- API 路由统一使用 /api/v1 前缀
- 响应格式: { success: boolean, data: any, error?: string }
- 所有模型必须包含 created_at 和 updated_at

### 命名约定
- 组件: PascalCase (UserProfile.tsx)
- 工具函数: camelCase (formatDate.ts)
- 常量: UPPER_SNAKE_CASE (API_BASE_URL)
- 数据库表: snake_case (user_profiles)

### 代码风格
- 使用单引号而非双引号
- 缩进使用 2 个空格
- 最大行长度 100 字符

### 安全要求
- 所有用户输入必须验证
- 敏感操作需要权限检查
- 不在日志中记录密码/Token

性能优化建议

规则文件优化

bash

# 检查文件大小（建议 < 50KB）
ls -lh .cursorrules

# 检查行数（建议 < 500 行）
wc -l .cursorrules

Cursor 配置优化

json

{
  "cursor.ai.model": "claude-3.5-sonnet",
  "cursor.ai.maxTokens": 4096,
  "cursor.ai.temperature": 0.2,
  "cursor.ai.enableCodeActions": true
}

性能检查清单

[ ] 规则文件简洁，无冗余内容
[ ] 避免重复定义相同规则
[ ] 定期清理不再使用的规则
[ ] 规则条目有清晰的优先级

常见问题规避

❌ 常见错误

错误	后果	正确做法
混合不兼容规则	AI 建议混乱	选择技术栈匹配的规则
规则过于复杂	响应变慢	保持规则简洁聚焦
忽略项目特性	建议不适用	添加项目自定义规则
频繁更改规则	结果不一致	稳定后锁定规则版本
不加测试直接应用	不符合预期	先在测试文件验证

✅ 推荐做法

做法	说明
渐进式采用	先用基础规则，再逐步添加特定规则
定期评估	每月评估规则效果，调整优化
团队同步	确保团队成员使用相同版本规则
版本锁定	将规则文件纳入版本控制
文档化	记录规则变更和原因

渐进式采用路线图

第一周：基础规则

✓ 复制通用规则
✓ 熟悉 AI 建议模式
✓ 团队成员安装 Cursor

第二周：框架规则

✓ 添加框架特定规则
✓ 调整编码风格
✓ 收集团队反馈

第三周：自定义规则

✓ 添加项目特定规则
✓ 完善团队约定
✓ 解决规则冲突

第四周：优化完善

✓ 评估规则效果
✓ 精简冗余规则
✓ 锁定规则版本

⬆ 返回顶部 | 📚 返回文档首页

最佳实践指南 ​

目录 ​

规则选择策略 ​

新项目 vs 现有项目 ​

技术栈匹配表 ​

项目配置实践 ​

单技术栈项目 ​

多技术栈项目 ​

验证配置 ​

团队协作指南 ​

版本控制 ​

团队文档模板 ​

团队规则模板库 ​

规则编写最佳实践 ​

自定义规则模板 ​

性能优化建议 ​

规则文件优化 ​

Cursor 配置优化 ​

性能检查清单 ​

常见问题规避 ​

❌ 常见错误 ​

✅ 推荐做法 ​

渐进式采用路线图 ​

第一周：基础规则 ​

第二周：框架规则 ​

第三周：自定义规则 ​

第四周：优化完善 ​

最佳实践指南

目录

规则选择策略

新项目 vs 现有项目

技术栈匹配表

项目配置实践

单技术栈项目

多技术栈项目

验证配置

团队协作指南

版本控制

团队文档模板

团队规则模板库

规则编写最佳实践

自定义规则模板

性能优化建议

规则文件优化

Cursor 配置优化

性能检查清单

常见问题规避

❌ 常见错误

✅ 推荐做法

渐进式采用路线图

第一周：基础规则

第二周：框架规则

第三周：自定义规则

第四周：优化完善