从写代码的工具到懂业务的伙伴大多数人用Cursor的方式是这样的打开文件CtrlK或者CtrlL描述需求接受或修改输出。这没问题但也只发挥了Cursor约30%的潜力。Cursor Rules.cursor/rules目录下的规则文件是让AI真正融入你的工作流的核心机制。有了精心设计的RulesAI不再需要你每次都解释我们用TypeScript的严格模式、“这个项目用PostgreSQL不用MySQL”、“错误处理要用Result类型”——它直接知道直接遵守。这篇文章基于大量实战经验讲透Cursor Rules的设计方法和最佳实践。## Rules的基本结构.cursor/rules/目录下可以有多个.mdc文件每个文件有自己的作用域.cursor/rules/├── global.mdc # 全局规则对所有文件生效├── typescript.mdc # TypeScript相关规则├── react.mdc # React组件规则├── api.mdc # API层规则├── testing.mdc # 测试规则└── database.mdc # 数据库操作规则每个.mdc文件的结构markdown---description: 这个规则文件的用途描述globs: [src/**/*.ts, src/**/*.tsx] # 作用域支持glob模式alwaysApply: false # 是否始终应用不管文件是否匹配---## 规则内容Markdown格式### 代码风格- 使用函数式组件- 避免class组件...globs字段决定了当AI打开哪些文件时这条规则会被激活。alwaysApply: true的规则在任何上下文都会生效适合全局原则。## 实战全局规则的设计全局规则应该包含项目级别的宪法——那些适用于整个代码库的原则markdown—description: 项目全局规则和技术栈约定alwaysApply: true—## 项目概述这是一个B2B SaaS产品面向企业客户核心功能是AI辅助的合同审查系统。## 技术栈-运行时Node.js 22 (LTS)TypeScript 5.4 严格模式-前端Next.js 15 React 19使用App Router-状态管理Zustand不用Redux不用Context for global state-样式Tailwind CSS v4组件库使用shadcn/ui-后端tRPC v11 Prisma v6 PostgreSQL 16-AI集成Vercel AI SDK v4主模型GPT-4o嵌入模型text-embedding-3-small-测试Vitest单元/集成PlaywrightE2E## 代码原则1.类型安全优先所有数据流必须有明确的TypeScript类型禁止使用any2.错误处理使用neverthrow库的ResultT, E类型禁止裸throw除了边界层3.函数纯化业务逻辑函数尽量是纯函数副作用隔离在专门的层4.依赖注入不直接import数据库客户端通过context/repository模式访问## 命名约定- 组件文件PascalCaseUserProfile.tsx- 工具函数camelCaseformatDate.ts- 常量SCREAMING_SNAKE_CASEMAX_RETRY_COUNT- 数据库schemasnake_caseuser_profiles表created_at字段## 禁止事项- 禁止在前端直接调用数据库必须通过API层- 禁止在组件中写业务逻辑提取到hooks或services- 禁止使用console.log使用logger工具- 禁止硬编码任何配置值使用环境变量## 实战针对特定技术的精细化规则### React组件规则markdown—description: React组件开发规范globs: [src/components//*.tsx, src/app//.tsx]—## 组件结构规范### 文件组织单一职责每个组件文件应该只包含一个主组件。子组件如果复杂提取到独立文件。### 组件模板tsx// 1. 导入外部库 → 内部模块 → 类型import { useState } from reactimport { Button } from /components/ui/buttonimport type { UserProfile } from “/types/user”// 2. Props接口定义明确、具体interface UserCardProps { user: UserProfile onEdit?: (userId: string) void className?: string}// 3. 组件实现export function UserCard({ user, onEdit, className }: UserCardProps) { // 4. hooks在最顶部 const [isExpanded, setIsExpanded] useState(false) // 5. 事件处理函数useCallback如有必要 const handleEdit () { onEdit?.(user.id) } // 6. 渲染 return ( div className{cn(“rounded-lg border p-4”, className)} {/… */} )}### 数据获取- 服务端组件Server Components用于静态或SSR数据- 客户端动态数据使用tRPC React Query自动集成- 不允许在组件中直接使用fetch必须通过tRPC或专门的API层### 性能- 列表渲染必须有唯一且稳定的key禁止用index- 大列表使用虚拟化tanstack/react-virtual- 图片使用next/image### API层规则markdown---description: tRPC API路由开发规范globs: [src/server/api/**/*.ts]---## tRPC Router规范### 基本结构\typescriptimport { z } from zodimport { createTRPCRouter, protectedProcedure } from /server/api/trpcimport { TRPCError } from trpc/serverexport const userRouter createTRPCRouter({ // 1. 列表查询query list: protectedProcedure .input(z.object({ limit: z.number().min(1).max(100).default(20), cursor: z.string().optional(), })) .query(async ({ ctx, input }) { // 始终通过ctx访问数据库 const users await ctx.db.user.findMany({ take: input.limit 1, cursor: input.cursor ? { id: input.cursor } : undefined, }) return { items: users.slice(0, input.limit), nextCursor: users.length input.limit ? users[input.limit].id : null } }), // 2. 创建/更新mutation update: protectedProcedure .input(UpdateUserSchema) // 使用共享的Zod schema .mutation(async ({ ctx, input }) { // 鉴权检查 if (ctx.session.user.id ! input.id !ctx.session.user.isAdmin) { throw new TRPCError({ code: “FORBIDDEN” }) } return ctx.db.user.update({ where: { id: input.id }, data: input.data }) })})### 错误处理- 业务错误使用TRPCErrorUNAUTHORIZED, FORBIDDEN, NOT_FOUND等- 不要暴露内部实现细节数据库错误等给客户端- 所有mutation要有输入验证Zod schema必须## 让AI遵循规则的技巧光写规则还不够还需要让AI真正理解和遵循**1. 给出反例不只是正例**markdown## 错误写法禁止tsx// ❌ 不要这样const handleClick async () { try { await updateUser(data) } catch (error) { console.error(error) // 不要用console }}## 正确写法tsx// ✅ 应该这样const handleClick async () { const result await updateUserSafe(data) // 返回Result类型 if (result.isErr()) { toast.error(result.error.message) logger.error(“Update user failed”, result.error) }}**2. 用具体场景而非抽象原则**不要写保持代码简洁。要写单个函数不超过30行如果超过提取子函数并明确命名。**3. 优先级标注**markdown## P0必须遵守生产阻断级- 所有外部输入必须经过Zod验证- 数据库操作必须在事务中处理如果涉及多表## P1强烈建议代码审查会标注- 函数圈复杂度不超过10- 每个函数只做一件事## P2建议可以在特殊情况下偏离- 避免深层嵌套超过3层考虑重构## 测量Rules的效果怎么知道你的Rules是否有效一个实用的方法1. 保存10个代表性的AI生成代码片段Rules之前2. 精心设计Rules后重新生成相同的代码片段3. 对比两次输出统计符合规范的比例在实践中好的Rules可以将需要修改才能合并的AI代码比例从60%降低到20%以下。这就是Cursor Rules真正的价值所在。