Cursor Rules与自定义配置完全教程

打造极致的AI编程环境，让你的编辑器真正"理解"你的项目

一、什么是Cursor Rules？

Cursor Rules是Cursor编辑器提供的一套配置系统，让你可以告诉AI助手关于项目的特定信息、编码规范、架构约束和工作偏好。简单来说，它就是你和AI之间的"沟通协议"——通过Rules，AI不再是通用的代码补全工具，而是一个真正理解你项目上下文的编程伙伴。

为什么需要Rules？

没有Rules的AI编程助手就像一个刚入职的新人：

不知道你的项目用什么框架
不了解你的代码风格偏好
不清楚你的项目结构
可能生成与现有代码风格冲突的代码

有了Rules，AI就像一个了解项目的老手：

知道该用什么库和API
遵循项目的编码规范
理解架构决策的上下文
生成的代码与现有代码无缝融合

二、.cursorrules文件基础

2.1 文件位置与基本结构

.cursorrules文件放在项目根目录下，对整个项目生效：

my-project/
├── .cursorrules          ← Rules文件
├── src/
├── package.json
└── ...

基本结构是纯文本，用自然语言编写：

# 项目概述
这是一个基于Next.js 14的电商平台前端项目。

# 技术栈
- 框架: Next.js 14 (App Router)
- 语言: TypeScript (严格模式)
- 样式: Tailwind CSS + shadcn/ui
- 状态管理: Zustand
- 数据获取: TanStack Query
- 表单: React Hook Form + Zod

# 编码规范
- 使用函数式组件，不使用class组件
- 组件文件使用PascalCase命名
- 工具函数使用camelCase命名
- 所有函数必须有TypeScript类型注解
- 优先使用const断言

# 项目结构
- src/app/ - App Router页面
- src/components/ - 可复用组件
- src/lib/ - 工具函数和配置
- src/hooks/ - 自定义Hooks
- src/stores/ - Zustand状态管理
- src/types/ - TypeScript类型定义

# 禁止事项
- 不要使用any类型
- 不要直接修改state
- 不要在组件内写内联样式（用Tailwind）
- 不要使用默认导出（用命名导出）

2.2 Rules的分层体系

Cursor支持多层级Rules，优先级从高到低：

1. 项目级Rules (.cursorrules)
   └── 当前项目生效

2. 全局级Rules (Cursor Settings → Rules)
   └── 所有项目生效

3. 语言级Rules
   └── 针对特定语言的规则

在Cursor中配置全局Rules：

打开Cursor Settings（Ctrl+, 或 Cmd+,）
导航到 General → Rules for AI
添加全局规则

2.3 Rules的优先级与合并

当多层Rules存在时，Cursor按以下方式处理：

项目级Rules覆盖全局级Rules中的冲突部分
更具体的规则覆盖更一般的规则
禁止性规则（"不要XXX"）通常具有更高优先级

三、高级Rules编写技巧

3.1 上下文注入

通过Rules注入项目的关键上下文，让AI理解你的架构决策：

# 架构决策记录 (ADR)

## ADR-001: 为什么选择App Router而非Pages Router
我们选择App Router是因为：
1. 需要React Server Components的性能优势
2. 嵌套布局对我们的页面结构很重要
3. Streaming SSR对首屏加载时间有显著改善

## ADR-002: 为什么用Zustand而不是Redux
1. 我们的全局状态比较简单，Redux太重了
2. Zustand的API更简洁，学习曲线低
3. Zustand天然支持TypeScript

## ADR-003: 数据库选型
- 主数据库: PostgreSQL (通过Prisma ORM)
- 缓存: Redis
- 搜索: Elasticsearch

当生成数据库相关代码时，必须使用Prisma Schema定义的模型。

3.2 代码风格约束

精确描述你的代码风格偏好：

# 代码风格指南

## TypeScript 规范
```typescript
// ✅ 正确示例
interface UserProfile {
  id: string;
  name: string;
  email: string;
  avatar?: string;
}

const getUserById = async (id: string): Promise<UserProfile | null> => {
  // 实现
};

// ❌ 错误示例
// 不要使用:
function getUser(id: any) { ... }  // 禁止any
export default function Component() { ... }  // 禁止默认导出

React 组件规范

组件定义使用箭头函数
Props接口命名为 {ComponentName}Props
组件导出使用命名导出
使用forwardRef时显式标注ref类型

// 正确的组件写法
interface ButtonProps {
  variant: 'primary' | 'secondary' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  onClick?: () => void;
}

export const Button = ({ variant, size = 'md', children, onClick }: ButtonProps) => {
  return (
    <button
      className={cn(buttonVariants({ variant, size }))}
      onClick={onClick}
    >
      {children}
    </button>
  );
};

错误处理

所有async函数必须有try-catch
错误要记录到日志系统
用户友好的错误消息，不暴露技术细节


### 3.3 Agent模式优化

Cursor的Agent模式（`Ctrl+I` / `Cmd+I`）需要特别优化的Rules：

```markdown
# Agent模式规则

## 文件操作
- 创建新文件前，先检查是否已有类似功能的文件
- 修改文件时，保留现有的import语句顺序
- 删除代码前，先确认没有其他地方引用

## 依赖管理
- 安装新依赖前，先检查package.json是否已有类似功能的库
- 优先使用项目已有的依赖
- 新依赖必须支持TypeScript

## 测试要求
- 每个新功能必须伴随单元测试
- 测试文件放在同目录下的__tests__文件夹
- 测试文件命名为 {filename}.test.ts
- 使用Vitest作为测试框架

## Git规范
- commit message使用conventional commits格式
- 格式: type(scope): description
- type: feat, fix, docs, style, refactor, test, chore
- 示例: feat(auth): add Google OAuth login

## 代码生成偏好
- 生成代码时添加JSDoc注释
- 复杂逻辑添加行内注释
- 生成的函数长度不超过50行
- 优先使用早期返回（early return）减少嵌套

3.4 错误处理与边界情况

# 错误处理规范

## API错误处理
```typescript
// 所有API调用必须使用统一的错误处理
import { ApiError } from '@/lib/api-error';

const fetchData = async <T>(url: string): Promise<T> => {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new ApiError(response.status, await response.text());
    }
    return response.json();
  } catch (error) {
    if (error instanceof ApiError) {
      // 已知错误，记录日志
      console.error(`API Error: ${error.status}`, error.message);
      throw error;
    }
    // 未知错误，记录详细信息
    console.error('Unexpected error:', error);
    throw new ApiError(500, '服务器内部错误');
  }
};

表单验证

所有用户输入必须验证
使用Zod定义验证schema
验证失败时显示友好的错误消息
前后端共享验证schema

边界情况

空数组/对象: 返回默认值或显示空状态
undefined/null: 使用optional chaining和nullish coalescing
数字溢出: 检查Number.isFinite
字符串长度: 截断而非报错


## 四、MCP Server集成配置

### 4.1 什么是MCP

MCP（Model Context Protocol）是Cursor支持的工具调用协议，允许AI直接调用外部工具和服务。

### 4.2 配置MCP Server

在项目根目录创建 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

4.3 常用MCP Server配置

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data.db"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-key"
      }
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

4.4 在Rules中引用MCP

# MCP工具使用指南

## 文件系统操作
- 读取/写入文件使用filesystem MCP
- 不要直接使用shell命令操作文件

## 数据库查询
- 查询PostgreSQL使用postgres MCP
- 查询结果限制在100行以内
- 不要执行DELETE或DROP操作，除非明确要求

## GitHub操作
- 创建Issue/PR使用github MCP
- commit前先检查git status
- PR标题使用conventional commits格式

## 搜索
- 需要搜索文档时使用brave-search MCP
- 搜索结果需要过滤和验证

五、多模型切换策略

5.1 模型选择指南

Cursor支持多个AI模型，不同场景适合不同模型：

# 模型使用策略

## 代码补全
- 默认使用: Claude 3.5 Sonnet（平衡速度和质量）
- 复杂重构: Claude 3.5 Sonnet（更好的上下文理解）
- 简单补全: Cursor Small（快速响应）

## 聊天/问答
- 架构设计: Claude 3.5 Sonnet（需要深度推理）
- Bug修复: Claude 3.5 Sonnet（需要理解上下文）
- 快速问答: Cursor Small（简单问题不需要大模型）

## Agent模式
- 复杂任务: Claude 3.5 Sonnet（需要规划和执行多步骤）
- 简单修改: Cursor Small（单文件小改动）

5.2 上下文窗口管理

# 上下文管理策略

## 上下文大小控制
- 简单任务: 使用当前文件上下文
- 中等任务: 添加相关文件（不超过5个）
- 复杂任务: 使用@codebase索引

## 上下文优化
- 优先使用@file引用具体文件
- 使用@folder引用目录结构
- 使用@codebase进行全局搜索
- 使用@web获取外部文档

## 注意事项
- 上下文越大，响应越慢
- 过多上下文可能导致AI"迷路"
- 关键信息放在Rules中比放在上下文中更可靠

六、项目级Rules模板库

6.1 前端项目模板

# 前端项目Rules模板

## 技术栈
- 框架: React 18 + Next.js 14 (App Router)
- 语言: TypeScript 5.x (strict mode)
- 样式: Tailwind CSS 3.x + shadcn/ui
- 状态管理: Zustand 4.x
- 表单: React Hook Form + Zod
- 测试: Vitest + React Testing Library

## 目录结构

src/ ├── app/ # Next.js App Router │ ├── (routes)/ # 路由组 │ ├── api/ # API Routes │ └── layout.tsx # 根布局 ├── components/ # 共享组件 │ ├── ui/ # 基础UI组件 │ └── features/ # 功能组件 ├── lib/ # 工具函数 ├── hooks/ # 自定义Hooks ├── stores/ # Zustand stores ├── types/ # 类型定义 └── styles/ # 全局样式


## 组件规范
- 组件使用命名导出
- Props接口命名为ComponentNameProps
- 复杂组件拆分为多个小组件
- 使用React.memo优化性能敏感组件

## 样式规范
- 使用Tailwind CSS类名
- 颜色使用设计系统中的token
- 响应式设计: mobile-first
- 暗色模式: 使用dark:前缀

## 性能要求
- 首屏加载时间 < 2秒
- 使用动态导入减少初始包大小
- 图片使用next/image优化
- 字体使用next/font优化

6.2 后端项目模板

# 后端项目Rules模板 (Node.js/Fastify)

## 技术栈
- 框架: Fastify 4.x
- 语言: TypeScript 5.x
- ORM: Drizzle ORM
- 数据库: PostgreSQL 15
- 缓存: Redis 7
- 认证: JWT + bcrypt
- 验证: Zod
- 测试: Vitest

## 目录结构

src/ ├── modules/ # 业务模块 │ ├── auth/ # 认证模块 │ │ ├── auth.controller.ts │ │ ├── auth.service.ts │ │ ├── auth.routes.ts │ │ └── auth.schema.ts │ └── users/ # 用户模块 ├── common/ # 公共模块 │ ├── middleware/ # 中间件 │ ├── utils/ # 工具函数 │ └── errors/ # 错误定义 ├── db/ # 数据库 │ ├── schema/ # Drizzle schema │ └── migrations/ # 迁移文件 └── config/ # 配置


## API规范
- RESTful设计
- 统一响应格式: { code, data, message }
- 分页: ?page=1&limit=20
- 过滤: ?status=active&sort=created_at:desc
- 错误码: 4xx客户端错误，5xx服务端错误

## 安全规范
- 所有输入必须验证（使用Zod）
- SQL查询使用参数化（Drizzle自动处理）
- 密码使用bcrypt加密（cost factor 12）
- JWT过期时间: access token 15分钟，refresh token 7天
- 敏感操作需要二次验证

## 数据库规范
- 所有表必须有id、created_at、updated_at字段
- 使用软删除（deleted_at字段）
- 外键必须有索引
- 查询必须有分页限制

6.3 全栈项目模板

# 全栈项目Rules模板

## 项目概述
这是一个monorepo全栈项目，使用Turborepo管理。

## 技术栈
### 前端
- Next.js 14 (App Router)
- TypeScript
- Tailwind CSS + shadcn/ui
- TanStack Query

### 后端
- Fastify
- Drizzle ORM
- PostgreSQL
- Redis

### 共享
- Zod schemas（前后端共享验证逻辑）
- TypeScript types
- 工具函数

## Monorepo结构

apps/ ├── web/ # Next.js前端 ├── api/ # Fastify后端 └── admin/ # 管理后台 packages/ ├── ui/ # 共享UI组件 ├── database/ # Drizzle schema和迁移 ├── validators/ # Zod验证schemas └── utils/ # 共享工具函数


## 开发规范
- 前后端共享的类型定义放在packages/中
- API调用使用统一的客户端封装
- 环境变量使用.env.local管理
- 使用changesets管理版本

6.4 数据科学项目模板

# 数据科学项目Rules模板

## 技术栈
- 语言: Python 3.11+
- 数据处理: Pandas, Polars
- 机器学习: Scikit-learn, XGBoost, PyTorch
- 可视化: Matplotlib, Plotly
- 实验跟踪: MLflow
- 代码质量: Ruff, mypy

## 目录结构

├── notebooks/ # Jupyter notebooks │ ├── exploration/ # 探索性分析 │ ├── modeling/ # 建模实验 │ └── reports/ # 最终报告 ├── src/ # 源代码 │ ├── data/ # 数据处理 │ ├── features/ # 特征工程 │ ├── models/ # 模型定义 │ ├── training/ # 训练流程 │ └── evaluation/ # 评估指标 ├── tests/ # 测试 ├── configs/ # 配置文件 └── data/ # 数据文件 ├── raw/ # 原始数据 ├── processed/ # 处理后数据 └── models/ # 训练好的模型


## 代码规范
- 所有函数必须有类型注解
- 使用dataclass或Pydantic定义数据结构
- 硬编码的参数提取到配置文件
- 随机种子必须固定以确保可复现性

## Notebook规范
- 单元格不超过50行
- 重要的中间结果保存到文件
- 使用%%time魔法命令追踪运行时间
- 清理所有临时变量和输出

## 模型训练规范
- 训练脚本必须接受配置文件参数
- 记录所有超参数和实验结果
- 模型保存时包含版本号和指标
- 使用MLflow跟踪实验

七、团队共享Rules规范

7.1 Git管理Rules文件

# 团队协作Rules管理

## .cursorrules文件管理
- .cursorrules文件纳入版本控制
- 团队成员共同维护和更新
- 重大修改需要PR review
- 定期审查和更新规则

## .cursor目录结构

.cursor/ ├── rules/ # 分模块的规则文件 │ ├── frontend.md # 前端规则 │ ├── backend.md # 后端规则 │ ├── testing.md # 测试规则 │ └── security.md # 安全规则 └── mcp.json # MCP配置


## 规则文件拆分
当.cursorrules文件过长时，拆分为多个文件：

主文件.cursorrules:
```markdown
# 项目概述
[简短描述]

# 规则文件索引
- 前端规则: .cursor/rules/frontend.md
- 后端规则: .cursor/rules/backend.md
- 测试规则: .cursor/rules/testing.md
- 安全规则: .cursor/rules/security.md

# 通用规则
[所有团队成员都需要遵守的规则]

规则审查流程

修改规则后提交PR
至少一名团队成员review
测试新规则对AI输出的影响
合并后通知团队更新


### 7.2 规则冲突解决

```markdown
# 规则冲突解决策略

## 优先级规则
1. 安全规则 > 功能规则 > 风格规则
2. 禁止性规则 > 推荐性规则
3. 具体规则 > 一般规则

## 冲突示例
### 冲突
- 规则A: "使用默认导出"
- 规则B: "使用命名导出"

### 解决
查看规则的优先级和适用范围。如果规则B是项目级规则，规则A是全局规则，
则项目内以规则B为准。

## 规则测试
- 修改规则后，测试AI的代码生成效果
- 确保规则不会产生矛盾的输出
- 记录规则变更的原因和效果

八、Cursor与Git/CI集成

8.1 Git Hooks集成

# Git集成规范

## Pre-commit Hooks
- 代码格式化: Prettier + ESLint
- 类型检查: tsc --noEmit
- 测试: 运行受影响的测试

## Commit Message规范
- 使用conventional commits格式
- 格式: type(scope): description
- 示例:
  - feat(auth): add OAuth2 login
  - fix(api): handle null response
  - docs(readme): update installation guide

## PR规范
- PR标题使用conventional commits格式
- PR描述包含: 改动原因、改动内容、测试方式
- 至少一名团队成员review
- CI通过后才能合并

8.2 CI/CD中的Cursor配置

# .github/workflows/ci.yml 示例
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint
      - run: npm run type-check

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run test

  build:
    runs-on: ubuntu-latest
    needs: [lint, test]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build

九、性能调优

9.1 Cursor性能优化

# 性能优化指南

## 索引优化
- 使用.cursorignore排除不需要索引的文件
- 排除node_modules、dist、.next等目录
- 大型数据文件不纳入索引

## .cursorignore示例

node_modules/ .next/ dist/ build/ *.min.js *.min.css *.map *.lock coverage/ .env .env.local


## 上下文优化
- 优先使用@file引用具体文件
- 避免@codebase用于简单任务
- 复杂任务分步骤进行
- 定期清理聊天历史

## 响应速度优化
- 简单任务使用小模型
- 减少Rules文件大小
- 避免过于复杂的规则
- 使用代码片段替代重复描述

9.2 Rules文件优化

# Rules文件优化

## 大小控制
- 主Rules文件不超过500行
- 使用简洁的语言，避免冗余
- 使用示例代码而非长篇描述
- 拆分到多个子文件

## 结构优化
- 使用清晰的标题层级
- 相关规则放在一起
- 使用代码块标注示例
- 定期清理过时规则

## 性能影响
- 过多规则会增加prompt长度
- 复杂规则可能导致AI理解困难
- 定期测试规则对AI输出的影响
- 移除效果不佳的规则

十、与Windsurf/Copilot对比

10.1 功能对比

功能	Cursor	Windsurf	GitHub Copilot
Rules系统	✅ 完整	✅ 有限	❌ 无
MCP支持	✅	❌	❌
Agent模式	✅ 强大	✅	✅ 有限
多模型支持	✅	✅	❌ 单一模型
代码库索引	✅	✅	✅
价格	$20/月	$15/月	$10/月

10.2 选择建议

# 工具选择建议

## 选择Cursor如果你：
- 需要精细的AI行为控制（Rules系统）
- 项目需要MCP工具集成
- 团队协作需要统一的AI配置
- 需要多模型切换

## 选择Windsurf如果你：
- 预算有限
- 不需要复杂的配置
- 偏好简洁的界面

## 选择Copilot如果你：
- 主要需要代码补全
- 已经在使用GitHub生态
- 不需要深度定制

十一、实战案例

11.1 从零配置一个React项目

让我们通过一个完整的案例，展示如何为一个React项目配置Rules：

步骤1：创建项目并初始化

npx create-react-app my-app --template typescript
cd my-app

步骤2：创建.cursorrules文件

# My App - AI Coding Rules

## 项目概述
这是一个任务管理应用，使用React 18 + TypeScript构建。

## 技术栈
- React 18
- TypeScript 5.x
- Tailwind CSS
- Zustand (状态管理)
- React Router v6
- Vitest (测试)

## 组件规范
- 使用函数式组件
- 使用命名导出
- Props使用interface定义
- 组件文件结构: imports → types → component → exports

## 样式规范
- 使用Tailwind CSS
- 颜色使用设计系统变量
- 响应式设计: mobile-first

## 状态管理
- 使用Zustand
- Store按功能模块拆分
- 使用immer处理不可变更新

## 测试规范
- 使用Vitest + React Testing Library
- 测试文件命名为ComponentName.test.tsx
- 测试用户行为而非实现细节

## 代码示例
```typescript
// 正确的组件写法
import { useState } from 'react';

interface TaskItemProps {
  task: {
    id: string;
    title: string;
    completed: boolean;
  };
  onToggle: (id: string) => void;
}

export const TaskItem = ({ task, onToggle }: TaskItemProps) => {
  return (
    <div className="flex items-center gap-2 p-2">
      <input
        type="checkbox"
        checked={task.completed}
        onChange={() => onToggle(task.id)}
      />
      <span className={task.completed ? 'line-through' : ''}>
        {task.title}
      </span>
    </div>
  );
};


**步骤3：配置MCP（可选）**

```json
// .cursor/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

步骤4：测试效果

现在在Cursor中打开项目，尝试让AI生成代码：

提示: 创建一个TodoList组件，支持添加、删除和标记完成功能

AI会根据你的Rules生成符合规范的代码。

11.2 优化现有项目的Rules

# Rules优化流程

## 步骤1: 分析现有代码
1. 查看项目的代码风格
2. 识别常用的模式和约定
3. 记录架构决策

## 步骤2: 编写初始Rules
1. 从模板开始
2. 添加项目特定的规则
3. 包含代码示例

## 步骤3: 测试和迭代
1. 让AI生成代码
2. 检查是否符合预期
3. 调整规则以改进结果

## 步骤4: 团队共享
1. 提交到版本控制
2. 团队成员测试
3. 收集反馈并优化

十二、常见问题解答

Q1: .cursorrules文件过大怎么办？

# 解决方案
1. 拆分到.cursor/rules/目录下的多个文件
2. 使用简洁的语言，删除冗余描述
3. 用代码示例替代长篇解释
4. 定期清理过时的规则

Q2: Rules不生效怎么办？

# 排查步骤
1. 确认文件位置正确（项目根目录）
2. 检查文件名是否正确（.cursorrules）
3. 重启Cursor
4. 检查Rules是否有语法错误
5. 确认规则没有被更高优先级的规则覆盖

Q3: 如何测试Rules的效果？

# 测试方法
1. 创建测试用例（固定的提示词）
2. 对比有Rules和无Rules的输出
3. 检查输出是否符合预期
4. 记录和比较不同版本的Rules效果

Q4: 团队成员的Rules偏好不同怎么办？

# 解决方案
1. 项目级Rules放在.cursorrules（团队共享）
2. 个人偏好放在全局Rules（个人设置）
3. 使用.cursor/rules/personal/目录（gitignore）
4. 定期讨论和协调团队规则

十三、进阶技巧

13.1 动态Rules

# 动态Rules示例

## 根据文件类型应用不同规则
当编辑src/components/目录下的文件时:
- 应用前端组件规范
- 使用React Hooks
- 添加PropTypes或TypeScript类型

当编辑src/api/目录下的文件时:
- 应用API规范
- 添加错误处理
- 使用统一的响应格式

当编辑*.test.*文件时:
- 应用测试规范
- 使用describe/it结构
- 添加适当的断言

13.2 Rules模板生成

# 自动生成Rules的脚本
import os
import json
from pathlib import Path


def generate_cursorrules(project_path: str, config: dict) -> str:
    """根据项目配置生成.cursorrules文件"""

    rules = []

    # 项目概述
    rules.append(f"# {config['project_name']} - AI Coding Rules\n")
    rules.append(f"## 项目概述\n{config['description']}\n")

    # 技术栈
    rules.append("## 技术栈\n")
    for tech in config['tech_stack']:
        rules.append(f"- {tech}")
    rules.append("")

    # 代码规范
    rules.append("## 代码规范\n")
    for rule in config['coding_rules']:
        rules.append(f"- {rule}")
    rules.append("")

    # 目录结构
    if 'directory_structure' in config:
        rules.append("## 目录结构\n```")
        rules.append(config['directory_structure'])
        rules.append("```\n")

    return "\n".join(rules)


# 使用示例
config = {
    "project_name": "My E-commerce App",
    "description": "基于Next.js的电商平台",
    "tech_stack": [
        "Next.js 14 (App Router)",
        "TypeScript (strict)",
        "Tailwind CSS",
        "Prisma ORM",
        "PostgreSQL"
    ],
    "coding_rules": [
        "使用函数式组件",
        "使用命名导出",
        "所有函数必须有类型注解",
        "错误处理使用try-catch"
    ]
}

rules_content = generate_cursorrules(".", config)

with open(".cursorrules", "w") as f:
    f.write(rules_content)

print("Rules文件已生成！")

13.3 Rules验证工具

# 验证Rules文件的有效性
import re
from pathlib import Path


def validate_cursorrules(file_path: str) -> dict:
    """验证.cursorrules文件的有效性"""
    issues = []
    warnings = []

    content = Path(file_path).read_text()

    # 检查文件大小
    if len(content) > 10000:
        warnings.append(f"文件过大 ({len(content)} 字符)，建议拆分")

    # 检查是否有标题
    if not re.search(r'^#+\s', content, re.MULTILINE):
        issues.append("缺少标题结构")

    # 检查是否有代码示例
    if '```' not in content:
        warnings.append("建议添加代码示例")

    # 检查是否有禁止事项
    if '不要' not in content and '禁止' not in content and '避免' not in content:
        warnings.append("建议添加明确的禁止事项")

    return {
        "valid": len(issues) == 0,
        "issues": issues,
        "warnings": warnings,
        "size": len(content)
    }


# 使用
result = validate_cursorrules(".cursorrules")
if result["valid"]:
    print("✅ Rules文件有效")
else:
    print("❌ Rules文件有问题:")
    for issue in result["issues"]:
        print(f"  - {issue}")

for warning in result["warnings"]:
    print(f"⚠️ {warning}")

十四、总结

Cursor Rules是提升AI编程效率的关键工具。通过合理配置Rules，你可以：

统一团队规范：确保AI生成的代码符合团队标准
提升代码质量：通过规则约束减少低质量代码
加速开发流程：AI更好地理解项目上下文
降低沟通成本：新人通过Rules快速了解项目规范

关键要点

从简单开始：先添加基本的技术栈和编码规范
持续迭代：根据AI输出效果不断优化规则
团队协作：Rules文件纳入版本控制，团队共同维护
平衡详细度：规则要足够详细但不能过于冗长

下一步行动

为你的项目创建一个基础的.cursorrules文件
测试AI的代码生成效果
根据结果迭代优化规则
与团队分享和协作维护

本教程涵盖了Cursor Rules的核心概念和实践技巧。随着Cursor的持续更新，Rules系统也会不断进化。建议定期查看官方文档，了解最新的功能和最佳实践。

Cursor Rules与自定义配置完全教程

教程简介

Cursor Rules与自定义配置完全教程

一、什么是Cursor Rules？

为什么需要Rules？

二、.cursorrules文件基础

2.1 文件位置与基本结构

2.2 Rules的分层体系

2.3 Rules的优先级与合并

三、高级Rules编写技巧

3.1 上下文注入

3.2 代码风格约束

React 组件规范

错误处理

3.4 错误处理与边界情况

表单验证

边界情况

4.3 常用MCP Server配置

4.4 在Rules中引用MCP

五、多模型切换策略

5.1 模型选择指南

5.2 上下文窗口管理

六、项目级Rules模板库

6.1 前端项目模板

6.2 后端项目模板

6.3 全栈项目模板

6.4 数据科学项目模板

七、团队共享Rules规范

7.1 Git管理Rules文件

规则审查流程

八、Cursor与Git/CI集成

8.1 Git Hooks集成

8.2 CI/CD中的Cursor配置

九、性能调优

9.1 Cursor性能优化

9.2 Rules文件优化

十、与Windsurf/Copilot对比

10.1 功能对比

10.2 选择建议

十一、实战案例

11.1 从零配置一个React项目

11.2 优化现有项目的Rules

十二、常见问题解答

Q1: .cursorrules文件过大怎么办？

Q2: Rules不生效怎么办？

Q3: 如何测试Rules的效果？

Q4: 团队成员的Rules偏好不同怎么办？

十三、进阶技巧

13.1 动态Rules

13.2 Rules模板生成

13.3 Rules验证工具

十四、总结

关键要点

下一步行动

相关教程

Python入门完全教程

Java基础编程教程

Go语言实战教程

Python编程入门完全教程

目录

快速导航