前言：为什么你的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来控制规则作用域：
---
description: 前端React组件开发规范
globs: ["**/*.tsx", "**/*.jsx", "src/components/**"]
alwaysApply: false
---
# React组件开发规范
## 组件结构
...
三、高质量Rules模板
3.1 全栈TypeScript项目
---
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 Hooks lib/ # 工具函数和配置 stores/ # Zustand状态 types/ # TypeScript类型定义
### 后端结构（api/）
routers/ # FastAPI路由（按模块分文件） services/ # 业务逻辑层 models/ # SQLAlchemy模型 schemas/ # Pydantic模式 crud/ # 数据库操作 core/ # 配置和通用功能
## 生成代码时的注意事项
1. 前端组件总是生成对应的TypeScript类型
2. API接口同时生成前端类型和后端Schema
3. 数据库操作必须使用async/await
4. 所有新功能需要考虑错误状态和加载状态
5. 生成测试时使用Vitest（前端）和pytest（后端）
3.2 Python AI工程项目
---
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，避免threading
async 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 测试专用Rules
---
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.fixture
async 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 项目文档集成
# 项目架构（AI必读）
## 数据流向
用户请求 → API Gateway → FastAPI → Service层 →
Database/Cache → Service层 → 响应序列化 → 用户
## 关键设计决策
1. 使用CQRS模式：写操作走主库，读操作走只读副本
2. 缓存策略：Redis缓存热点数据，TTL=5分钟
3. 异步任务：耗时操作（邮件、报表）走Celery队列
## 注意事项（避坑）
- 用户表和订单表是分库的，跨库JOIN不可用
- 文件上传走OSS，不存本地磁盘
- 所有价格字段用Decimal，不用float（精度问题）
4.2 动态Rules（基于文件类型）
合理使用globs可以实现规则的智能激活：
---
globs: ["src/api/**", "api/**", "**/*.api.ts"]
---
# API层规范
所有API函数必须：
1. 有JSDoc注释说明参数和返回值
2. 使用统一的错误处理（apiErrorHandler）
3. 请求/响应类型从@/types/api导入
4. 不包含业务逻辑（只做数据转换和调用）
4.3 提示AI如何回答
## AI回答规范
### 代码生成
- 生成完整、可运行的代码，不要省略关键部分
- 涉及安全（认证/加密/SQL）必须提醒注意事项
- 给出代码后，主动说明关键设计选择
### 问题解答
- 直接给出最佳方案，不要列举N种可能
- 如果有多种方案，明确推荐其中一种
- 用中文回答，代码注释也用中文
### 代码审查
- 发现潜在bug时主动指出，不只是回答被问的问题
- 指出性能问题和安全隐患
- 如果代码可以更简洁，主动给出重构建议
五、Rules管理最佳实践
5.1 保持Rules的时效性
Rules需要随着项目演进而更新，建议：
- 每个Sprint结束时review一次Rules
- 踩坑时及时将经验写入Rules（"禁止XX操作，因为..."）
- 升级依赖后更新版本号
5.2 团队共享Rules
将.cursor/rules/目录提交到Git，让团队共享统一的AI配置：
# .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片段库
# 常用片段：React组件模板
生成React组件时使用以下模板：
interface XxxProps {
// props定义
}
export function Xxx({ }: XxxProps) {
return (
<div>
</div>
)
}
六、完整示例：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格式持续演进，请参考官方文档获取最新信息
