规则系统：.cursorrules 与 Project Rules

为什么需要规则系统

没有规则的 AI 就像没有代码规范的团队：每次生成的代码风格各异，选用的库不一致，注释风格混乱，甚至可能使用你项目不兼容的技术栈。

规则系统解决的核心问题：

• 一致性：无论是你还是队友使用 Cursor，生成的代码符合同一套规范
• 项目感知：让 AI 了解项目的技术栈、架构模式、禁用的库
• 减少重复说明：不需要在每个对话中重复"请用 TypeScript"、"不要用 var"
• 安全约束：防止 AI 生成不符合安全规范的代码

传统 .cursorrules 文件

.cursorrules 是早期 Cursor 版本（0.x）的规则方式：在项目根目录放置一个名为 .cursorrules 的文件，其内容会被自动注入到每次 AI 请求的系统提示词中。

# .cursorrules 示例（传统格式，仍受支持）

你是一位专业的 TypeScript 全栈工程师。请始终遵循以下规范：

## 技术栈
- 前端：Next.js 14 App Router + React 18 + TypeScript 5
- 样式：Tailwind CSS（不使用 styled-components 或 CSS Modules）
- 状态管理：Zustand（不使用 Redux）
- 数据获取：TanStack Query v5
- 后端：Node.js + Fastify + Prisma + PostgreSQL

## 代码规范
- 始终使用 TypeScript，禁止使用 any 类型（除非极特殊情况）
- 使用 const 优先，避免使用 var
- 异步函数使用 async/await，不使用 Promise.then() 链
- 所有函数必须有明确的返回类型注解
- 错误处理使用 try/catch，抛出自定义 Error 类

## 命名约定
- React 组件：PascalCase
- 普通函数：camelCase，动词开头（如 getUserById）
- 常量：UPPER_SNAKE_CASE
- 类型/接口：PascalCase，接口以 I 开头

## 测试
- 使用 Vitest + Testing Library
- 每个函数必须有对应的单元测试
- 测试文件放在 __tests__ 目录下

Project Rules（新一代规则系统）

Cursor 0.45+ 引入了 Project Rules，以 .cursor/rules/ 目录管理规则。每条规则是一个独立的 Markdown 文件（.mdc 格式），可以精确控制：

• 规则在何时触发（始终、手动、匹配文件时、Agent 专用）
• 规则适用于哪些文件（glob 模式匹配）
• 规则优先级（目录层级决定）

目录结构

my-project/
├── .cursor/
│   └── rules/
│       ├── general.mdc          # 通用规则（始终应用）
│       ├── typescript.mdc       # TypeScript 规范
│       ├── react-components.mdc # React 组件规范
│       ├── api-endpoints.mdc    # API 开发规范
│       ├── testing.mdc          # 测试规范
│       └── security.mdc         # 安全规范（Agent 专用）
├── src/
└── ...

规则类型详解

每个 .mdc 文件开头有 YAML frontmatter 控制规则行为：

• Always（始终应用） 无论用户打开什么文件、写什么提示词，规则始终注入系统提示。适合全局技术栈声明、公司编码规范等核心规则。alwaysApply: true
• Auto-Attached（文件匹配时自动附加） 当用户引用（@）或 Agent 读取匹配 glob 模式的文件时自动注入。如 *.test.ts 匹配时注入测试规范。globs: ["**/*.test.ts"]
• Agent-Requested（Agent 自主判断） 规则有描述说明，Agent 自行判断是否需要引入该规则。适合特定场景的专用规范（如"部署相关操作时参考此规则"）。
• Manual（手动引用） 只有用户在 Chat 中用 @规则名 显式引用时才生效。适合不常用但重要的规范文档。

全局规则配置

除项目级规则外，可以在 Cursor Settings → General → Rules for AI 中配置 全局规则， 这些规则对所有项目都生效，适合个人偏好设置。

## 全局规则示例（Cursor Settings → Rules for AI）

始终用中文回答，代码注释也使用中文。

回答时：
1. 先简要解释思路，再给出代码
2. 代码后面附上使用示例
3. 指出潜在的边界情况

生成代码时：
- 偏好函数式编程风格
- 优先考虑代码可读性，其次才是简洁性
- 复杂逻辑必须有注释说明

优质规则范例

通用项目规则（general.mdc）

---
description: "核心项目规范，始终应用"
alwaysApply: true
---

# 项目背景
这是一个 B2B SaaS 平台，核心功能是企业数字资产管理。
当前阶段：Beta 测试，用户数约 200 家企业。

# 技术栈
- Next.js 15 (App Router) + TypeScript 5.4
- Tailwind CSS + Radix UI（组件库）
- Prisma + PostgreSQL（数据库）
- NextAuth.js v5（认证）
- Resend（邮件服务）

# 架构原则
- Server Components 优先，仅在必要时使用 Client Components
- 数据库操作仅在 Server Actions 或 API Route Handlers 中进行
- 使用 Zod 进行所有输入验证
- 错误统一通过 src/lib/errors.ts 中的自定义错误类处理

# 禁止使用
- Redux（使用 Zustand 或 React Context）
- moment.js（使用 date-fns）
- lodash（使用原生 JS 或 remeda）
- CSS-in-JS（使用 Tailwind）

测试规则（testing.mdc）

---
description: "测试文件规范，当引用测试文件时自动应用"
globs: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"]
---

# 测试规范
使用 Vitest + @testing-library/react

## 测试结构
- 每个测试文件对应一个源文件
- 使用 describe/it 嵌套结构
- 测试描述用中文，描述 "应该..." 的行为

## Mock 规范
- 使用 vi.mock() mock 外部模块
- 数据库操作必须 mock，不连接真实数据库
- 使用 faker.js 生成测试数据，不使用硬编码数据

## 断言
- 使用 expect(result).toMatchObject() 验证对象
- 错误断言使用 await expect(fn()).rejects.toThrow()
- 异步测试必须 await

## 覆盖率要求
- 核心业务逻辑：>= 80%
- 工具函数：>= 95%

安全规则（security.mdc，Agent 专用）

---
description: "安全规范，Agent 在处理用户输入、认证、数据库操作时参考"
---

# 安全编码规范

## 输入验证
- 所有用户输入必须使用 Zod schema 验证
- 文件上传验证：类型白名单 + 大小限制 + 内容检测

## SQL 安全
- 禁止字符串拼接 SQL，始终使用 Prisma ORM
- 如必须使用原始 SQL，使用参数化查询

## 认证与授权
- 所有 API 路由必须验证 session
- 资源访问检查用户是否属于同一 organizationId
- 敏感操作（删除、导出）需要二次确认

## 密钥处理
- 不在代码中硬编码任何密钥
- 使用 process.env 读取，变量名必须在 .env.example 中声明
- console.log 不得输出任何包含用户数据或密钥的信息

## 响应安全
- API 响应不返回密码、token 等敏感字段
- 错误信息不暴露内部实现细节

团队规则共享

因为 .cursor/rules/ 是普通文件目录，可以 提交到 Git 仓库，所有团队成员共享同一套规则。 这是 Cursor 团队协作的核心优势之一。

团队规则管理建议

1. 规则文件加入 Git：git add .cursor/rules/，确保所有成员使用同一套规则
2. 规则变更走 Code Review：规则修改可能影响全团队的 AI 行为，应通过 PR 评审
3. 规则文件有版本历史：可以追溯规则是何时、为何变更的
4. 个人偏好用全局规则：个人习惯（如语言偏好）放在 Cursor Settings 的全局规则，不提交到仓库

# .gitignore — 注意规则文件应该提交，不要忽略
# 正确做法：
.cursor/   # ❌ 不要整个忽略 .cursor 目录

# 如果只想忽略特定文件：
.cursor/mcp.json   # ✅ 只忽略 MCP 配置（可能含密钥）
# .cursor/rules/ 目录应该提交