Cursor Rules 项目规范

.cursorrules 是 Cursor 的项目级配置文件，让 Cursor AI 自动遵守你项目的约定。

跟 Claude Code 的 CLAUDE.md 对应

Cursor 用 .cursorrules、Claude Code 用 CLAUDE.md、Codex 用 AGENTS.md，三家文件互不通用，但概念一致。

文件位置

项目根/
├── .cursorrules               ← Cursor 启动自动读
├── .cursorrules.local         ← 本地覆盖（加 .gitignore）
└── .cursor/
    └── rules/                 ← 多文件规则（新版 Cursor）
        ├── frontend.mdc
        ├── backend.mdc
        └── tests.mdc

单文件版（.cursorrules）

# 项目：MyApp

## 技术栈
- Next.js 14 (App Router)
- TypeScript strict mode
- Tailwind CSS
- Prisma + PostgreSQL

## 编码规范
- 缩进 2 空格
- 单引号字符串
- 不用 default export（除非 Next.js 强制要求）
- React 组件用 PascalCase，hooks 用 use 前缀
- API 路由放 src/app/api/，按 REST 命名

## 测试
- 用 Vitest，文件名 *.test.ts
- 测试覆盖率 ≥ 80%
- 不直接调真实数据库，用 prisma-mock

## Tailwind
- 用 cn() 工具合并 className
- 避免任意值（arbitrary values），改用 tailwind.config 扩展
- dark mode 用 dark: 前缀

## Git
- 提交格式：feat/fix/refactor/docs/test: <desc>
- 分支：feature/<task-id>-<desc>

## 严禁
- 不要碰 src/legacy/
- 不要改 prisma/migrations/*.sql
- 不要 console.log 提交（提交前 grep 检查）

多文件版（.cursor/rules/*.mdc）

新版 Cursor 支持按场景分文件，每个文件 frontmatter 指定何时激活：

.cursor/rules/frontend.mdc

---
description: React/Next.js 前端代码规范
globs: ["src/app/**/*.tsx", "src/components/**/*.tsx"]
alwaysApply: false
---

写 React 组件时：
- 用 'use client' 声明客户端组件
- props 类型显式声明，不用 any
- 用 cn() 合并 className
- 状态用 useState/useReducer，复杂场景用 zustand

.cursor/rules/api.mdc

---
description: API 路由规范
globs: ["src/app/api/**/*.ts"]
alwaysApply: false
---

写 API 路由时：
- 用 Zod 验证 input
- 错误返回标准格式 {error: {code, message}}
- 用 Prisma 时记得加 select/include 避免泄露
- 鉴权用 src/lib/auth.ts 的 getSession()

.cursor/rules/tests.mdc

---
description: 测试编写规范
globs: ["**/*.test.ts", "**/*.test.tsx"]
alwaysApply: false
---

写测试时：
- describe 名要清楚（"用户登录后" 不是 "test 1"）
- 用 beforeEach 重置 mock
- assert 用 expect().toEqual()，不用 toBe（对象比较）
- 边界条件单独测

globs 决定哪些文件被编辑时激活该规则，alwaysApply: true 则永远激活。

实战例子

TypeScript 严格项目

# TypeScript Strict Rules

- 不允许 any（用 unknown 然后 narrowing）
- 所有函数必须有返回类型注解
- React props/state 必须有显式类型
- 不允许 // @ts-ignore（用 // @ts-expect-error 并写明原因）
- 严禁 Object.assign，用对象 spread

类型设计：
- 优先 type，特殊场景用 interface（extends 时）
- 共享类型放 src/types/
- API 返回类型从 Zod schema 推导（z.infer）

错误处理：
- 函数失败用 Result<T, E> 模式，不要 throw
- 顶层 try-catch 只在 API handler / 事件处理

Python 项目

# Python Project Rules

环境：
- Python 3.11+
- Poetry 管理依赖
- pre-commit 钩子

风格：
- ruff 默认配置 + isort
- 类型注解：函数签名 100% 注解
- docstring：Google 风格

测试：
- pytest + pytest-asyncio
- coverage ≥ 85%
- fixture 放 conftest.py

工具偏好：
- pydantic v2（不要 dataclass for API models）
- httpx（不要 requests）
- structlog（不要 logging）
- typer（不要 click / argparse）

严禁：
- print 调试（用 logger）
- 全局可变状态
- mutable default args

Go 项目

# Go Project Rules

风格：
- gofmt + goimports（保存自动）
- 包名小写无下划线
- error wrap 用 fmt.Errorf("ctx: %w", err)

代码组织：
- cmd/<binary>/main.go
- internal/<pkg>/<file>.go
- 不要 pkg/ 目录（除非真要给外部用）

错误处理：
- 显式 if err != nil
- 不要 panic，除非 init 阶段
- errgroup 处理并发错误

工具偏好：
- chi（不要 gin/echo）
- sqlx（不要 ORM）
- zerolog（不要 logrus）

高级：使用 @rule 引用

要审查代码时，遵循 @rule:frontend.mdc
要写 API 时，遵循 @rule:api.mdc

Cursor 会按需载入对应规则。

跨工具通用规则

如果你既用 Cursor 又用 Claude Code，规则不重复写：

# 在项目根放统一规则
echo "<rules content>" > RULES.md

# Cursor 引用
echo "见 RULES.md" > .cursorrules

# Claude Code 引用
echo "## 编码规范\n详见 [RULES.md](./RULES.md)" >> CLAUDE.md

# Codex 引用
echo "## 编码规范\n详见 [RULES.md](./RULES.md)" >> AGENTS.md

.cursorignore

类似 .gitignore，告诉 Cursor 哪些文件不要给 AI 看：

node_modules/
dist/
.next/
.env*
*.lock
public/uploads/

找现成的 .cursorrules

资源	内容
PatrickJS/awesome-cursorrules	各种语言/框架的 cursorrules 模板
cursor.directory	Cursor 规则在线检索

.cursorrules vs CLAUDE.md vs AGENTS.md

	Cursor	Claude Code	Codex
文件	.cursorrules / .cursor/rules/*.mdc	CLAUDE.md	AGENTS.md
项目级	✅	✅	✅
全局级	❌	~/.claude/CLAUDE.md	~/.codex/AGENTS.md
多文件	✅（新版）	❌	❌
按 glob 激活	✅	❌	❌
何时加载	编辑/对话时	启动时	启动时

Cursor 的 glob 激活机制最灵活；Claude Code/Codex 加载更稳定。最佳实践：项目里三个文件都有，让任何工具都能识别约定。