Cursor的高阶用法（1）：.cursor/rules深度配置 — 让AI完全懂你的项目

一、为什么需要Rules？

在没有Rules的情况下，AI可能会随意选择技术方案，命名风格飘忽不定，甚至生成你不用的依赖。而通过Rules，我们可以将项目的隐性知识变为AI的显性约束，减少90%的纠正对话。

二、Rules文件的位置与加载逻辑

Cursor支持三种规则配置方式，优先级从高到低：

2.1 项目级规则：.cursor/rules/（推荐）

Cursor 1.x版本推出了.cursor/rules/目录，支持按文件/目录粒度加载规则。每个.mdc文件头部可以声明globs（作用范围）：

---
globs: ["src/components//.tsx", "src/pages//.tsx"]
---

你是一名React前端工程师。本项目使用以下技术栈：...

2.2 旧版全局规则：.cursorrules

项目根目录的.cursorrules文件，对整个项目生效。Cursor仍然支持，但新版推荐迁移到.cursor/rules/。

2.3 用户全局规则：Cursor设置 > Rules for AI

在Cursor设置中的"Rules for AI"区域填写，对你打开的所有项目都生效，适合写个人编码习惯。

三、一份好的Rules文件包含什么？

以全栈Next.js项目为例，推荐的规则结构如下：

# 项目：[项目名称]

## 角色定义
你是一名全栈工程师，精通TypeScript、React 18、Next.js 14 App Router、Prisma和PostgreSQL。

## 技术栈（禁止使用其他替代方案）
- 前端框架：Next.js 14（App Router，不用Pages Router）
- UI组件：shadcn/ui + Tailwind CSS v3
- 状态管理：Zustand（禁止使用Redux、MobX）
- 数据获取：React Query v5（禁止使用SWR、axios裸请求）
- 表单验证：Zod + React Hook Form
- ORM：Prisma（禁止写原生SQL）
- 包管理器：pnpm（所有命令用pnpm，禁止npm/yarn）

## 目录结构约定
- 页面组件：src/app/[路由]/page.tsx
- Server Components：默认，除非明确需要交互才加'use client'
- 可复用组件：src/components/[功能域]/ComponentName.tsx
- 工具函数：src/lib/[模块名].ts
- API路由：src/app/api/[端点]/route.ts

## 命名规范
- 组件文件：PascalCase（UserCard.tsx）
- 工具函数文件：camelCase（formatDate.ts）
- 变量/函数：camelCase
- 常量：UPPERSNAKECASE
- 类型/接口：PascalCase，接口名加I前缀（IUser）

## 代码风格（强制要求）
1. 所有函数必须有TypeScript类型标注，禁止使用any
2. 错误处理：使用try/catch，不要.catch(console.log)省事
3. 异步函数使用async/await，禁止.then()链式调用
4. 组件props必须定义接口：interface [ComponentName]Props { ... }
5. 禁止在组件内部写内联样式，使用Tailwind类名

## 注释规范
- 公共函数必须写JSDoc注释（参数、返回值、示例）
- 复杂业务逻辑写行内注释解释"为什么"，不写"是什么"
- 禁止无意义注释（如//调用函数、//返回结果）

## 输出约束
- 生成代码时，只输出需要修改的部分，不要重复粘贴未变更的代码
- 不要添加任何"根据你的需求，我写了..."类的前缀废话
- 如果需求不明确，先问清楚再写，不要猜测

四、针对不同项目类型的规则模板

4.1 Python FastAPI 后端项目

## 技术栈
- Python 3.11+
- FastAPI（异步路由）
- SQLAlchemy 2.0（ORM，使用async session）
- Pydantic v2（数据验证）
- pytest（测试框架，禁止unittest）

## 代码约定
- 所有路由函数必须是async def
- 数据库操作使用Dependency Injection注入session
- 响应模型必须定义Pydantic schema，禁止直接返回ORM对象
- 环境变量通过pydantic-settings的Settings类读取，禁止os.environ直接读取
- 错误响应统一使用HTTPException，不自定义异常类

## 测试要求
- 每个路由至少写一个集成测试
- 使用httpx.AsyncClient进行异步测试
- 数据库测试使用独立的test数据库，fixture中自动创建/清理

4.2 Go 微服务项目

## 项目约定
- Go 1.22+，使用Go modules
- Web框架：gin（路由层），禁止net/http裸用
- 日志：zap（禁止log标准库）
- 配置：viper+yaml文件
- 数据库：sqlx（禁止GORM）

## 错误处理
- 错误必须向上传递，不在中间层打日志后再返回
- 自定义错误类型使用errors.New()或fmt.Errorf("%w", err)
- 禁止panic（除非是程序初始化阶段的不可恢复错误）

## 项目结构
- cmd/：程序入口
- internal/：私有业务代码（禁止外部包导入）
- pkg/：可供外部复用的工具包

五、进阶技巧：让规则更精准

5.1 用否定约束避免AI "发挥"

明确说不要什么，是最容易忽视的规则类型：

## 禁止事项（遇到这些情况，必须先询问）
- 禁止引入.cursor/rules/allowed-deps.md清单之外的新依赖
- 禁止修改src/config/目录下的任何文件
- 禁止删除任何已有的类型定义
- 禁止在没有错误处理的情况下使用JSON.parse()

5.2 注入上下文文件

对于大型项目，可以在规则中引用其他文档：

## 阅读以下文件了解项目背景
- 项目架构说明：docs/architecture.md
- API接口规范：docs/api-spec.md
- 数据库表设计：docs/schema.md

5.3 分层规则：全局 + 模块级

六、常见错误与排查

问题1：写了规则但AI还是不遵守
- 检查规则文件是否保存（.mdc后缀，不是.md）
- 检查globs配置是否匹配当前文件路径
- 规则太长、太模糊：把最重要的规则放在文件开头
- 尝试在对话中直接说「根据项目规则回答」

问题2：不同模块规则冲突
- 使用globs严格限定每个规则文件的作用范围
- 全局规则只写通用约定，模块规则只写该模块的特定约定

问题3：规则文件应该提交到Git吗？
- 强烈建议提交.cursor/rules/，这样团队所有成员使用Cursor时都会自动加载项目规则，避免AI在不同人的电脑上生成风格迥异的代码。

七、小结

Rules是让Cursor从「通用AI助手」变成「项目专属助手」的关键。一份好的规则文件能把你从反复纠正AI输出中解放出来，让它第一次就给出符合项目规范的代码。

下一章我们将深入讲解Agent模式：如何用Cursor完成跨多个文件的复杂功能开发。感谢关注！