Cursor Rules深度实战2026：把AI编程助手调教成你的专属架构师

从"写代码的工具"到"懂业务的伙伴"

大多数人用Cursor的方式是这样的：打开文件，Ctrl+K或者Ctrl+L，描述需求，接受或修改输出。这没问题，但也只发挥了Cursor约30%的潜力。Cursor Rules（.cursor/rules目录下的规则文件）是让AI真正融入你的工作流的核心机制。有了精心设计的Rules，AI不再需要你每次都解释"我们用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（单元/集成），Playwright（E2E）## 代码原则1.类型安全优先：所有数据流必须有明确的TypeScript类型，禁止使用any2.错误处理：使用neverthrow库的Result<T, E>类型，禁止裸throw（除了边界层）3.函数纯化：业务逻辑函数尽量是纯函数，副作用隔离在专门的层4.依赖注入：不直接import数据库客户端，通过context/repository模式访问## 命名约定- 组件文件：PascalCase（UserProfile.tsx）- 工具函数：camelCase（formatDate.ts）- 常量：SCREAMING_SNAKE_CASE（MAX_RETRY_COUNT）- 数据库schema：snake_case（user_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 "react"import { Button } from "@/components/ui/button"import 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 "zod"import { createTRPCRouter, protectedProcedure } from "@/server/api/trpc"import { TRPCError } from "@trpc/server"export 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 }) })})```### 错误处理- 业务错误使用TRPCError（UNAUTHORIZED, 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真正的价值所在。