前言：为什么你的Cursor体验不如别人？

同样是用Cursor，为什么有些人用得飞起，有些人却频繁纠错、反复解释？答案往往藏在一个被大多数人忽视的文件里：.cursorrules（新版叫.cursor/rules）。这篇文章将系统讲解Cursor Rules的设计哲学、最佳实践，以及如何用Rules构建一个真正"懂你"的AI编程助手。—## 一、Cursor Rules是什么？Cursor Rules是一套给AI编程助手的"系统级指令"——在每次对话开始之前，这些规则就已经被注入到AI的上下文中，让AI在整个项目中都遵循你的偏好和规范。没有Rules时的痛点：- 每次都要重复解释"我们用TypeScript，不要用JavaScript"- AI生成的代码风格前后不一致- AI不了解项目结构，给出通用而非针对性的建议- 每次对话都从零开始，无法积累项目知识有了Rules之后：- AI自动遵循项目技术栈和代码规范- 输出风格高度一致- AI"知道"项目架构，给出更精准的建议—## 二、Rules文件结构（2026最新规范）### 旧格式（仍支持）项目根目录/└── .cursorrules # 单文件，全局生效### 新格式（推荐）项目根目录/└── .cursor/ └── rules/ ├── global.mdc # 全局规则（所有文件生效） ├── frontend.mdc # 前端规则（.tsx/.vue文件生效） ├── backend.mdc # 后端规则（.py/.go文件生效） ├── testing.mdc # 测试规则（*.test.*文件生效） └── database.mdc # 数据库规则（SQL文件生效）````.mdc`格式支持frontmatter来控制规则作用域：markdown—description: 前端React组件开发规范globs: [“/*.tsx", "/.jsx", "src/components/“]alwaysApply: false—# React组件开发规范## 组件结构…---## 三、高质量Rules模板### 3.1 全栈TypeScript项目markdown—description: 全栈TypeScript项目全局规范alwaysApply: true—# 项目概述这是一个基于Next.js 15 + FastAPI的全栈SaaS应用。## 技术栈### 前端- Framework: Next.js 15 (App Router)- UI库: shadcn/ui + Tailwind CSS v4- 状态管理: Zustand- 数据请求: TanStack Query v5- 表单: React Hook Form + Zod- 类型: TypeScript strict mode### 后端- Framework: FastAPI 0.111± ORM: SQLAlchemy 2.0（async）- 数据库: PostgreSQL 16- 缓存: Redis 7- 任务队列: Celery + Redis- 认证: JWT（jose库）## 代码规范### 通用原则- 优先使用函数式编程，避免class（除非框架要求）- 变量/函数命名使用camelCase，类型/接口使用PascalCase- 文件命名：组件用PascalCase.tsx，工具函数用kebab-case.ts- 所有字符串使用单引号（Python双引号）- 缩进：2空格（Python 4空格）### TypeScript规范- 禁止使用any，用unknown替代- 接口优于类型别名（interface > type）- 所有函数必须有明确的返回类型- 使用satisfies操作符验证类型### 错误处理- 前端使用Error Boundary + TanStack Query的onError- 后端统一使用HTTPException，错误码定义在constants/errors.py## 项目结构### 前端结构（src/）app/ # Next.js页面（App Router）components/ # UI组件（原子组件放ui/，业务组件放business/）hooks/ # 自定义React Hookslib/ # 工具函数和配置stores/ # Zustand状态types/ # TypeScript类型定义### 后端结构（api/）routers/ # FastAPI路由（按模块分文件）services/ # 业务逻辑层models/ # SQLAlchemy模型schemas/ # Pydantic模式crud/ # 数据库操作core/ # 配置和通用功能## 生成代码时的注意事项1. 前端组件总是生成对应的TypeScript类型2. API接口同时生成前端类型和后端Schema3. 数据库操作必须使用async/await4. 所有新功能需要考虑错误状态和加载状态5. 生成测试时使用Vitest（前端）和pytest（后端）### 3.2 Python AI工程项目markdown—description: Python AI工程项目规范globs: [”/.py”, “notebooks/“]alwaysApply: false—# Python AI工程规范## 环境信息- Python: 3.11± 包管理: uv（不是pip）- 格式化: ruff（不是black）- 类型检查: mypy strict## 技术栈- LLM框架: LangChain 0.3+ / LangGraph 0.2± Embedding: text-embedding-3-large（OpenAI）- 向量数据库: Qdrant- HTTP客户端: httpx（异步）- 数据处理: pandas/polars- 配置管理: pydantic-settings## 代码风格### 类型注解# 所有函数必须有完整类型注解def process_documents( docs: list[Document], chunk_size: int = 512, overlap: int = 50,) -> list[TextChunk]: …### 异步编程# 优先使用async/await，避免threadingasync def retrieve_context( query: str, top_k: int = 5,) -> list[RetrievalResult]: …### 配置管理# 使用pydantic-settings，不要硬编码配置class Settings(BaseSettings): openai_api_key: str qdrant_url: str = “http://localhost:6333” model_config = SettingsConfig(env_file=”.env")## LangChain特定规范- 优先使用LCEL（|管道操作符）而非旧式Chain- 所有chain使用ainvoke进行异步调用- 使用structured_output而非手动解析JSON- 回调使用langsmith追踪，不用print调试## 禁止事项- 禁止直接print调试，使用loguru- 禁止同步调用LLM API（必须async）- 禁止硬编码API Key- 禁止使用deprecated的LangChain 0.1接口### 3.3 测试专用Rulesmarkdown—description: 测试编写规范globs: ["/.test.ts", "**/.spec.ts”, “/test_*.py", "tests/”]alwaysApply: false—# 测试规范## 前端测试（Vitest + Testing Library）### 测试文件结构describe(“ComponentName”, () => { // 按功能分组 describe(“渲染”, () => { it(“正常渲染不报错”, () => {…}) it(“传入props正确显示”, () => {…}) }) describe(“交互”, () => { it(“点击按钮触发回调”, async () => {…}) }) describe(“边界情况”, () => { it(“props为空时显示默认值”, () => {…}) })})### 断言规范- 使用toBeInTheDocument()而非toBeTruthy()- 优先用getByRole/getByLabelText，最后才用getByTestId- 异步操作使用waitFor + findBy## 后端测试（pytest）### 固定格式# 测试函数命名：test_动作_条件_期望结果async def test_create_user_with_valid_data_returns_201(): …async def test_create_user_with_duplicate_email_returns_400(): …### 必须使用fixture@pytest.fixtureasync def authenticated_client(async_client, test_user): “”“已登录的测试客户端”“” token = create_access_token(test_user.id) async_client.headers[“Authorization”] = f"Bearer {token}" return async_client### 测试覆盖率要求- 业务逻辑层（services/）: 90%以上- API路由层（routers/）: 80%以上- 工具函数（utils/）: 95%以上---## 四、进阶技巧### 4.1 项目文档集成markdown# 项目架构（AI必读）## 数据流向用户请求 → API Gateway → FastAPI → Service层 → Database/Cache → Service层 → 响应序列化 → 用户## 关键设计决策1. 使用CQRS模式：写操作走主库，读操作走只读副本2. 缓存策略：Redis缓存热点数据，TTL=5分钟3. 异步任务：耗时操作（邮件、报表）走Celery队列## 注意事项（避坑）- 用户表和订单表是分库的，跨库JOIN不可用- 文件上传走OSS，不存本地磁盘- 所有价格字段用Decimal，不用float（精度问题）### 4.2 动态Rules（基于文件类型）合理使用`globs`可以实现规则的智能激活：markdown—globs: [“src/api/", "api/”, “**/.api.ts"]—# API层规范所有API函数必须：1. 有JSDoc注释说明参数和返回值2. 使用统一的错误处理（apiErrorHandler）3. 请求/响应类型从@/types/api导入4. 不包含业务逻辑（只做数据转换和调用）### 4.3 提示AI如何回答markdown## AI回答规范### 代码生成- 生成完整、可运行的代码，不要省略关键部分- 涉及安全（认证/加密/SQL）必须提醒注意事项- 给出代码后，主动说明关键设计选择### 问题解答- 直接给出最佳方案，不要列举N种可能- 如果有多种方案，明确推荐其中一种- 用中文回答，代码注释也用中文### 代码审查- 发现潜在bug时主动指出，不只是回答被问的问题- 指出性能问题和安全隐患- 如果代码可以更简洁，主动给出重构建议---## 五、Rules管理最佳实践### 5.1 保持Rules的时效性Rules需要随着项目演进而更新，建议：1. 每个Sprint结束时review一次Rules2. 踩坑时及时将经验写入Rules（"禁止XX操作，因为..."）3. 升级依赖后更新版本号### 5.2 团队共享Rules将`.cursor/rules/`目录提交到Git，让团队共享统一的AI配置：bash# .gitignore中不要忽略rules目录# 明确添加到追踪git add .cursor/rules/git commit -m “feat: 添加Cursor Rules配置”### 5.3 Rules长度控制Rules不是越长越好——过长的Rules会占用过多上下文窗口，反而降低AI的有效响应质量。**经验值**：- 全局Rules：500-1000字符- 模块级Rules：300-500字符- 单个Rules文件不超过2000字符### 5.4 常用Rules片段库markdown# 常用片段：React组件模板生成React组件时使用以下模板：interface XxxProps { // props定义}export function Xxx({ }: XxxProps) { return (

)}---## 六、完整示例：AI编程项目的Rules配置.cursor/rules/├── global.mdc # 项目概述、技术栈、通用规范├── python-ai.mdc # Python/AI开发规范（.py）├── docker.mdc # 容器配置规范（Dockerfile, docker-compose）├── git-commit.mdc # 提交信息规范└── security.mdc # 安全相关（密钥、认证、注入防护）```合理配置Cursor Rules，能让AI编程助手从"懂点代码的机器"变成"真正了解你项目的搭档”。这是2026年做AI辅助编程不可忽视的生产力乘数。—本文规范基于Cursor 0.45+版本，Rules格式持续演进，请参考官方文档获取最新信息