Cursor Rules 指南 - AI Coding Wiki

📋 什么是 Cursor Rules

Cursor Rules 是 Cursor 编辑器的规则配置系统，用于指导 AI 在代码生成过程中遵循特定的规范和标准。通过定义项目背景、编码规范、库偏好等，你可以确保 Cursor 生成的代码与项目需求高度契合。

简单来说，Rules 就是给 Cursor AI 的"行为准则"：

告诉 AI 你的项目是做什么的
规定代码应该遵循什么风格
指定使用哪些库和框架
设定输出语言和格式偏好

🎯 规则类型

Cursor Rules 分为两个级别：

1. User Rules（全局规则）

位置：Cursor Settings → Rules

适用于所有项目的通用规则，如：

输出语言偏好（中文/英文）
响应长度限制
统一的代码风格
通用的最佳实践

User Rules 示例

# 语言设置
- 所有对话和注释使用中文
- 代码中的变量名和函数名使用英文

# 代码风格
- 使用 2 空格缩进
- 使用单引号而非双引号（JavaScript/TypeScript）
- 函数优先使用箭头函数

# 输出格式
- 回复简洁明了，避免冗余解释
- 代码块要标注语言类型
- 重要更改要说明原因

2. Project Rules（项目规则）

位置：.cursor/rules/ 目录下的 .mdc 文件

针对特定项目的规则，支持多种触发模式：

Rule Type	触发方式	适用场景
`Always`	每次对话自动携带	项目核心规范、架构说明
`Auto Attached`	匹配文件类型自动生效	特定语言的编码规范
`Agent Request`	Agent 自动判断是否生效	特定功能的实现指南
`Manual`	手动 @ 引用	偶尔使用的特殊规则

⚙️ 配置方法

方法一：通过 Cursor 设置界面

          步骤
        

          1. 打开 Cursor 设置（Cmd/Ctrl + ,）
选择 "Rules" 标签页
在 "Project Rules" 区域点击 "Add new rule"
指定规则名称，按 Enter 键
Cursor 会自动创建 .cursor/rules 文件夹
编辑生成的 .mdc 文件，添加规则内容
        

方法二：手动创建文件

bash

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

# 创建全局规则文件
touch .cursor/rules/global.mdc

# 创建特定语言规则
touch .cursor/rules/typescript.mdc

.mdc 文件结构

markdown - .cursor/rules/global.mdc

---
description: 项目全局规则
globs:
alwaysApply: true
---

# 项目背景
这是一个使用 Next.js 14 + TypeScript 开发的 SaaS 应用。

# 技术栈
- 框架：Next.js 14 (App Router)
- 语言：TypeScript 5.x
- 样式：Tailwind CSS + shadcn/ui
- 状态管理：Zustand
- 数据获取：TanStack Query

# 编码规范
- 组件使用函数式组件 + Hooks
- 使用 TypeScript 严格模式
- 遵循 Airbnb JavaScript 风格指南

# 文件结构
- app/: 页面路由
- components/: 可复用组件
- lib/: 工具函数和配置
- hooks/: 自定义 Hooks
- types/: TypeScript 类型定义

📄 最佳实践模板

React/Next.js 项目

markdown

# Next.js App Router 最佳实践

## 组件规范
- 默认使用 Server Components
- 仅在需要交互时使用 Client Components（添加 'use client'）
- 使用 layout.tsx 共享布局
- 使用 loading.tsx 处理加载状态
- 使用 error.tsx 处理错误

## 数据获取
- Server Components 中直接 async/await 获取数据
- Client Components 使用 TanStack Query
- 避免在客户端请求敏感数据

## 样式规范
- 使用 Tailwind CSS 工具类
- 复杂样式抽取为组件
- 使用 cn() 函数合并类名
- 响应式设计遵循移动优先

## 性能优化
- 图片使用 next/image
- 字体使用 next/font
- 适当使用 React.memo 和 useMemo
- 大型列表使用虚拟滚动

Python 项目

markdown

# Python 项目规范

## 代码风格
- 遵循 PEP 8 规范
- 使用 Black 格式化代码
- 使用 isort 排序导入
- 最大行长度 88 字符

## 类型注解
- 所有函数必须有类型注解
- 使用 typing 模块的高级类型
- 复杂类型使用 TypeAlias

## 文档规范
- 所有公共函数必须有 docstring
- 使用 Google 风格的 docstring
- 包含参数说明、返回值、异常

## 测试
- 使用 pytest 框架
- 测试文件命名 test_*.py
- 测试函数命名 test_*
- 保持测试覆盖率 > 80%

💡 使用技巧

💡 技巧 1：提供项目上下文

在规则开头清晰描述项目背景，帮助 AI 理解上下文。包括项目类型、目标用户、核心功能等。

💡 技巧 2：明确能改什么、不能改什么

在规则中明确标注哪些文件/代码可以修改，哪些是核心逻辑不应该碰。

💡 技巧 3：使用 Auto Attached 规则

为不同文件类型创建专门的规则。例如 *.test.ts 文件自动应用测试规范。

⚠️ 注意事项

规则不宜过长。过于详细的规则会占用 context 空间，影响 AI 理解能力。保持规则简洁、重点突出。

目录结构和技术栈文件

推荐在项目根目录维护两个文件，并在规则中引用：

          目录结构
        

          project/
├── .cursor/
│   └── rules/
│       ├── global.mdc
│       └── typescript.mdc
├── directorystructure.md    # 目录结构说明
├── technologystack.md       # 技术栈说明
└── ...
        

📚 相关资源

Cursor Directory - 社区分享的优质 Rules 模板
Cursor 官方文档 - Rules 使用指南
Awesome CursorRules - 精选 Rules 集合