Cursor Rules 完全指南：让 AI 生成符合规范的代码（附实战配置）

凌晨一点,我盯着屏幕上 Cursor 刚生成的代码,手指悬在回车键上方——第三次了。

第一次它用了 var 声明变量,第二次改成了类组件,这次居然直接把我的 TypeScript 类型全删掉了,还贴心地加了一堆 any。我深吸一口气,删掉代码,打算自己手写。

那一刻我突然意识到:AI 不是不够聪明,是我压根没告诉它「我的规则」。

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

说实话,刚开始用 Cursor 的时候,我以为 AI 应该「自己知道」什么是好代码。直到团队成员抱怨说”你让 Cursor 生成的组件为什么和咱们的风格完全不一样”,我才明白:AI 需要明确的规范。

这篇文章就是要帮你解决这个问题。花5分钟配置好 Cursor Rules,从此 AI 生成的代码完全符合你的项目规范——不再用错技术栈,不再违反编码风格,不再让你怀疑人生。

什么是 Cursor Rules?为什么需要它?

Cursor Rules 的本质:给 AI 定规矩

简单来说,Cursor Rules 就是一个配置文件,用来告诉 AI 你的编码规范。

就像公司给新员工发一本「开发手册」,里面写着:我们用什么技术栈、代码怎么命名、文件怎么组织。Cursor Rules 做的就是这个事——给 AI 发「入职培训手册」。

它的工作原理其实挺直接:当你和 Cursor 对话时,规则文件里的内容会自动附加到提示词中。AI 看到这些规则后,就知道「哦,这个项目要用 React Hooks,不能用类组件」,然后就照着规范生成代码。

不配置 Rules 会怎样?我的血泪教训

我第一次用 Cursor 做项目的时候,觉得自己捡到宝了——AI 写代码速度飞快。但三天后我发现问题大了:

代码风格完全混乱。有的文件用 camelCase 命名,有的用 PascalCase,还有几个文件用了蛇形命名法 snake_case。我自己都记不清哪个是哪个。

技术栈用错。我明明想要函数组件,结果 Cursor 给我生成了一堆 class Component extends React.Component。我试着跟它说「用 Hooks」,下一个文件又变回去了。

违反项目规范。团队要求所有函数都要写注释,Cursor 生成的代码干干净净——一行注释都没有。还有错误处理,明明规范要求必须 try-catch,结果 AI 直接裸奔调用 API。

那次之后我花了两天时间重构代码,改得我手都酸了。

配置 Rules 之后呢?真香

后来我花了5分钟配置了一个 .cursorrules 文件,写清楚:

• 技术栈是 React 18 + TypeScript
• 只用函数组件和 Hooks
• 命名统一用 camelCase
• 必须写类型定义,禁止 any

你猜怎么着?

从那天开始,Cursor 生成的每一个组件都符合规范。代码一致性提升了至少80%,我做 code review 的时间直接少了一半。团队成员看到后都问我「你怎么让 Cursor 这么听话的」。

真香。

数据不会骗人:根据社区最佳实践,合理配置 Rules 可以让代码一致性显著提升,减少后期重构成本。GitHub 上的 awesome-cursorrules 仓库已经有 2000+ star,说明这确实是开发者的刚需。

Cursor Rules 配置方法(2026最新)

先说重点:新旧配置方式的变化

如果你在网上搜 Cursor Rules 教程,可能会看到两种说法——有人说用 .cursorrules 文件,有人说用 .cursor/rules 目录。别慌,两个都对,只是时间不同。

旧方式(2025年之前):
直接在项目根目录创建一个 .cursorrules 文件,把所有规则写进去。简单粗暴。

新方式(2026年推荐):
在项目根目录创建 .cursor/rules 目录,然后在里面放多个 .mdc 文件。每个文件可以负责不同的规则类别。

官方已经明确建议迁移到新方式了,因为新方式更灵活——你可以按功能拆分规则,也可以设置不同的生效范围。不过旧方式目前还能用,只是未来某个版本会被废弃。

我的建议?如果是新项目,直接用新方式。如果是老项目,有空就迁移,不急。

两种规则级别:全局 vs 项目

Cursor 支持两个层级的规则,理解它们的区别很重要。

User Rules(全局规则)

这是你个人的编码偏好,对所有项目生效。

设置路径:File → Preferences → Cursor Settings → Rules → User Rules

适用场景:跨项目的通用规范。比如:

• 「我所有项目都用 TypeScript」
• 「我讨厌 var,统一用 const 或 let」
• 「所有异步操作都用 async/await,不用 .then()」

你可以把它理解成你个人的「代码洁癖」设置。

Project Rules(项目规则)

针对单个项目的特定规范,只在当前项目生效。

设置方式:

1. 在项目根目录创建 .cursor 文件夹
2. 在 .cursor 下创建 rules 文件夹
3. 在 rules 里面创建 .mdc 文件,比如 frontend.mdc 或 typescript-rules.mdc

适用场景:项目特定的技术栈和规范。比如:

• 「这是一个 Next.js 14 + TypeScript + Tailwind CSS 项目」
• 「API 接口统一使用 RESTful 规范」
• 「组件文件放在 components/ 目录,使用 PascalCase 命名」

优先级很清楚:项目规则 > 全局规则。如果冲突了,项目说了算。

规则生效范围:别让规则管太宽

这是2026年新版本的重要功能——你可以控制规则什么时候生效。

在 .mdc 文件里,你可以设置生效范围:

Always(始终生效):不管你在干啥,这个规则都起作用。适合最核心的规范,比如「禁止使用 var」。但慎用,设置太多 Always 规则会让 AI 的上下文变得很拥挤。

Auto Attached(自动附加):根据文件类型自动触发。比如你可以设置「.tsx 文件自动应用 React 规则」,「.py 文件自动应用 Python 规则」。这是我最推荐的方式。

Agent Requested(AI 自己判断):让 AI 根据对话内容决定是否需要这个规则。适合一些可选的辅助规则。

Manual(手动调用):只有你明确告诉 Cursor 使用这个规则时才生效。适合特殊场景,比如「性能优化专用规则」或「测试代码规则」。

我的实践经验:80% 用 Auto Attached,10% 用 Always,剩下 10% 根据情况选。

2026年1月的新功能:/rules 命令

刚刚(2026年1月8日),Cursor 发布了 CLI 更新,新增了一个超实用的命令:/rules。

现在你可以直接在 Cursor 的终端里输入 /rules,就能快速创建和编辑规则文件,不用手动去找文件夹了。对于经常调整规则的人来说,这个功能能省不少时间。

具体用法可以查看 Cursor 官方论坛的更新公告。

如何编写有效的 Cursor Rules?

这是最关键的部分。规则写得好不好,直接决定了 Cursor 能不能听话。

规则内容的三大类别

配置规则时,我建议分三个层面来写:

A. 技术与架构层面

先告诉 AI 这是个什么项目。

项目技术栈:
- 前端:React 18 + TypeScript 5.3
- 状态管理:Zustand
- 样式:Tailwind CSS 3.4
- 构建工具:Vite 5.0
- Node.js 版本:18+

还要说清楚架构规范:

架构规范:
- 前后端分离
- API 使用 RESTful 风格
- 文件夹结构:
  - components/ 存放可复用组件
  - pages/ 存放页面组件
  - utils/ 存放工具函数
  - hooks/ 存放自定义 Hooks

为什么要这么详细?

我吃过亏。之前只写了「用 React」,结果 Cursor 有时候生成 React 16 的写法,有时候生成 React 18 的写法。后来我把版本号写清楚,问题就消失了。

B. 代码规范层面

Railway - 现代化的部署平台，告别繁琐运维，让代码分钟级上线

立即开始 →推广

这部分是让代码风格统一的关键。

代码规范:

命名规则:
- 组件名:PascalCase (例:UserProfile)
- 文件名:kebab-case (例:user-profile.tsx)
- 变量和函数:camelCase (例:getUserData)
- 常量:UPPER_SNAKE_CASE (例:MAX_RETRY_COUNT)

代码风格:
- 只使用函数组件,不要用类组件
- 优先使用 const,其次 let,禁止 var
- 使用箭头函数,不用 function 关键字(除非需要 this)
- 所有组件必须有 TypeScript 类型定义

文件长度:
- 单个文件不超过 300 行
- 单个函数不超过 50 行

注释要求:
- 关键函数必须有 JSDoc 注释
- 复杂逻辑必须有行内注释
- 注释要说「为什么」,不是「做什么」

C. 质量与测试

错误处理:
- 所有异步操作必须有 try-catch
- API 调用失败要有用户友好的错误提示
- 不要吞掉错误,至少要 console.error

性能优化:
- 列表渲染必须有 key
- 大列表使用虚拟滚动
- 图片必须指定宽高,避免布局偏移

测试要求:
- 工具函数必须有单元测试
- 关键业务逻辑必须有测试覆盖

编写规则的黄金原则

原则1:具体、可执行、可验证

这是最重要的原则。

❌ 错误示例:「代码要写得好」「遵循最佳实践」「注意性能」

这种规则等于没说。AI 看到「最佳实践」,它怎么知道你说的是哪个实践?

✅ 正确示例:

• 「使用函数组件,不要用类组件」
• 「Props 使用 interface 定义,不用 type」
• 「异步操作必须用 async/await,不用 .then()」

看出区别了吗?好的规则是可以直接执行的指令,不是模糊的建议。

原则2:控制长度在 500 行以内

这是社区的最佳实践。规则太长,AI 理解起来困难,而且会占用大量上下文空间。

如果你发现规则文件超过 500 行了,说明该拆分了:

• frontend.mdc - 前端相关规则
• backend.mdc - 后端相关规则
• typescript.mdc - TypeScript 规则
• testing.mdc - 测试相关规则

原则3:用示例代码,不要只说不做

AI 最喜欢看例子。

❌ 只说不做:

组件要写成函数式,要有类型定义

✅ 提供示例:

组件示例:

interface UserCardProps {
  name: string;
  email: string;
}

export const UserCard = ({ name, email }: UserCardProps) => {
  return (
    <div className="user-card">
      <h3>{name}</h3>
      <p>{email}</p>
    </div>
  );
};

有了示例,Cursor 就知道你要的是什么样的代码。这招特别有效。

原则4:把最重要的规则放前面

AI 会优先关注靠前的内容。所以:

第一优先级:技术栈和版本
第二优先级:代码风格
第三优先级:文件组织
最后:可选的优化建议

常见错误,别踩坑

错误1:规则太宽泛

「遵循 React 最佳实践」——哪个最佳实践?2016年的还是2024年的?

改成:「使用 React Hooks,优先用 useState 和 useEffect,复杂状态用 useReducer」

错误2:规则互相冲突

「必须用 TypeScript」又说「允许使用 any 类型」——这不是自相矛盾吗?

AI 看到冲突的规则会困惑,最后可能两个都不遵守。

错误3:忘记指定版本

React 16 的类组件写法和 React 18 的 Hooks 写法差异很大。如果你只写「用 React」,AI 可能随机选一个版本的写法。

一定要写清楚:React 18.2+、TypeScript 5.3+、Node.js 18+。

错误4:规则写得像论文

有些人写规则喜欢长篇大论,解释为什么要这样做,列举各种理论依据。

别这样。AI 不需要你说服它,它只需要知道「做什么」。

❌ 「我们选择 TypeScript 是因为它提供了静态类型检查,可以在编译阶段发现错误,提升代码质量…」(后面还有300字)

✅ 「使用 TypeScript,禁止 any 类型」

简洁有力。

实战:为 React + TypeScript 项目配置规则

理论说得再多,不如来个真实的例子。

假设你要做一个 React + TypeScript 项目,技术栈是:

• React 18
• TypeScript 5.x
• Tailwind CSS 3.x
• Vite 5.x

团队规范要求:

阿里云 - 开发者上云首选，轻量服务器专享 8.5 折优惠，助力项目快速上线

领取 8.5 折优惠 →推广

• 只用函数组件
• 严格类型,禁止 any
• 统一的文件和命名规范
• 必须有错误处理

咱们一步步配置规则文件。

Step 1:创建规则文件

在项目根目录:

mkdir -p .cursor/rules
cd .cursor/rules
touch react-typescript.mdc

Step 2:定义技术栈

打开 react-typescript.mdc,先把技术栈写清楚:

# React + TypeScript 项目规则

## 技术栈

- React 18.2+
- TypeScript 5.3+
- Tailwind CSS 3.4+
- Vite 5.0+
- Node.js 18+

## 依赖管理

- 包管理器:pnpm
- 不要使用 npm 或 yarn

Step 3:代码风格规范

接着定义代码怎么写:

## 代码规范

### 组件规范

- 只使用函数组件,禁止类组件
- 组件名使用 PascalCase
- 文件名使用 kebab-case
- 使用命名导出,不用默认导出

示例:

// ❌ 错误
export default function userProfile() { }

// ✅ 正确
export const UserProfile = () => { }

### TypeScript 规范

- 所有组件必须有类型定义
- Props 使用 interface,不用 type
- 禁止使用 any,使用 unknown 或具体类型
- 函数返回值必须显式声明类型

示例:

// ✅ 正确的组件定义
interface UserCardProps {
  name: string;
  email: string;
  age?: number;
}

export const UserCard = ({ name, email, age }: UserCardProps): JSX.Element => {
  return (
    <div className="p-4 border rounded">
      <h3 className="text-lg font-bold">{name}</h3>
      <p className="text-gray-600">{email}</p>
      {age && <p>Age: {age}</p>}
    </div>
  );
};

### 命名规范

- 变量和函数:camelCase
- 组件:PascalCase
- 常量:UPPER_SNAKE_CASE
- 文件名:kebab-case
- CSS 类名:Tailwind 原子类,不写自定义 CSS

### 异步处理

- 所有异步操作使用 async/await
- 禁止使用 .then() 链式调用
- 必须有 try-catch 错误处理

示例:

// ✅ 正确
const fetchUserData = async (userId: string): Promise<User> => {
  try {
    const response = await fetch(`/api/users/${userId}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return await response.json();
  } catch (error) {
    console.error('Error fetching user:', error);
    throw error;
  }
};

Step 4:文件组织规范

## 文件组织

### 目录结构

src/
├── components/     # 可复用组件
├── pages/          # 页面组件
├── hooks/          # 自定义 Hooks
├── utils/          # 工具函数
├── types/          # TypeScript 类型定义
├── services/       # API 调用
└── constants/      # 常量定义

### 文件命名

- 组件文件:user-card.tsx
- 工具文件:format-date.ts
- 类型文件:user.types.ts
- Hook 文件:use-user-data.ts

### 导入顺序

1. React 相关
2. 第三方库
3. 项目内部组件
4. 工具函数
5. 类型定义
6. 样式

Step 5:质量要求

## 质量要求

### 错误处理

- API 调用必须有 try-catch
- 错误信息要对用户友好
- 记录错误日志

### 性能优化

- 列表渲染必须有 key 属性
- 避免在渲染函数中创建新对象或函数
- 使用 React.memo 优化不必要的重渲染
- 图片必须指定 width 和 height

### 代码质量

- 单个文件不超过 300 行
- 单个函数不超过 50 行
- 复杂逻辑必须有注释
- 关键函数必须有 JSDoc 注释

Step 6:完整的规则文件

把上面的内容整合起来,一个完整的 .cursor/rules/react-typescript.mdc 就完成了。

你可以在这个基础上根据项目需求调整。比如:

• 用 Redux 就加上 Redux 的规范
• 用 React Query 就加上数据获取的规范
• 有特殊的业务规则就补充进去

测试效果

配置完成后,试试让 Cursor 生成一个用户卡片组件:

你的提示:「创建一个用户卡片组件,显示用户名、邮箱和头像」

配置规则前,Cursor 可能给你生成:

export default function UserCard(props) {
  return <div>...</div>
}

配置规则后,Cursor 会生成:

interface UserCardProps {
  name: string;
  email: string;
  avatarUrl: string;
}

export const UserCard = ({ name, email, avatarUrl }: UserCardProps): JSX.Element => {
  return (
    <div className="p-4 border rounded shadow">
      <img src={avatarUrl} alt={name} className="w-16 h-16 rounded-full" width="64" height="64" />
      <h3 className="text-lg font-bold mt-2">{name}</h3>
      <p className="text-gray-600">{email}</p>
    </div>
  );
};

看,完全符合规范:

• ✅ 函数组件
• ✅ TypeScript 类型定义
• ✅ 命名导出
• ✅ Tailwind 样式
• ✅ 图片有宽高属性

一次到位,不用返工。

进阶技巧与常见问题

规则优先级:谁说了算?

当你配置了多层规则时,可能会遇到冲突。Cursor 的优先级规则是这样的:

项目规则 > 全局规则

如果你的全局规则说「用单引号」,但项目规则说「用双引号」,Cursor 会听项目的。

子目录规则 > 父目录规则

假设你的项目结构是这样:

project/
├── .cursor/rules/general.mdc
└── frontend/
    └── .cursor/rules/react.mdc

在 frontend/ 目录下工作时,react.mdc 的优先级更高。

手动调用 > 自动触发

如果你在对话中明确提到某个规则,那个规则会被优先考虑,即使它的生效范围设置是 Manual。

多规则文件管理:拆分的艺术

当项目变复杂,一个规则文件可能不够用。我的实践是这样拆分的:

.cursor/rules/
├── core.mdc              # 核心技术栈(Always)
├── frontend.mdc          # 前端规则(Auto Attached: *.tsx, *.ts)
├── backend.mdc           # 后端规则(Auto Attached: *.py, *.go)
├── testing.mdc           # 测试规则(Auto Attached: *.test.*)
└── performance.mdc       # 性能优化(Manual)

每个文件负责不同领域,清晰明了。

调试技巧:规则不生效怎么办?

问题1:不知道规则是否生效

打开 Cursor 的 Composer 或 Chat,问它:「你看到了哪些规则?」

Cursor 会告诉你当前加载了哪些规则文件。如果你的规则没出现,说明:

• 路径可能不对
• 生效范围设置可能不对
• 文件格式可能有问题

问题2:规则冲突

如果两个规则互相矛盾,Cursor 可能会「罢工」,两个都不遵守。

解决办法:

1. 检查规则文件,找出冲突点
2. 明确优先级,删除低优先级的规则
3. 或者在高优先级规则里明确说「覆盖其他规则」

问题3:AI 不遵守规则

有时候你明明写了规则,Cursor 还是我行我素。

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

可能的原因:

1. 规则太模糊:改成具体指令
2. 规则太长:AI 可能忽略靠后的内容,把重要规则放前面
3. 规则与你的提示冲突:如果你在对话中说「用类组件」,但规则说「用函数组件」,AI 会优先听你的对话内容

解决方案:

• 重写规则,增加示例代码
• 在对话中明确说「按照项目规则来」
• 把规则从 Auto Attached 改成 Always

获取现成规则:站在巨人的肩膀上

不想自己从零写规则?社区有大量现成资源。

awesome-cursorrules

GitHub 上最火的 Cursor Rules 仓库,2000+ star。涵盖:

• React、Vue、Angular 等前端框架
• Python、Go、Java 等后端语言
• Next.js、Astro、Nuxt 等全栈框架
• 还有 TypeScript、测试、Docker 等专项规则

直接复制你需要的规则文件,稍作调整就能用。

awesome-cursorrules-zh

专为中文开发者优化的规则库。特别贴心的是,它提供了「合并规则」的示例——比如把 React 和 FastAPI 的规则合并成一个全栈项目规则。

cursor.directory

在线规则库,网页版,支持在线预览和复制。涵盖 30+ 主流框架。

dotcursorrules.com

另一个在线资源站,有很多实战案例和最佳实践分享。

我的建议:先从社区规则开始,用一段时间后根据项目需求调整。不要一上来就自己从零写,浪费时间。

团队协作:让规则成为团队资产

如果你是团队开发,把规则纳入版本控制是个好主意。

1. 提交到 Git

把 .cursor/rules 目录提交到代码仓库:

git add .cursor/rules
git commit -m "Add Cursor rules for project standards"

这样团队成员拉取代码后,Cursor 自动加载项目规则,大家的 AI 行为保持一致。

2. 新成员入职培训

在项目 README 里加上这么一段:

## 使用 Cursor 开发

本项目配置了 Cursor Rules,位于 `.cursor/rules` 目录。

使用 Cursor 时,AI 会自动遵守这些规范:
- React 18 + TypeScript
- 函数组件 + Hooks
- Tailwind CSS 样式
- 严格的类型定义

如需调整规则,请先与团队讨论。

3. 定期 Review

技术栈会更新,规范会演进。建议每个季度 review 一次规则文件:

• 有没有过时的规则?
• 有没有新的最佳实践需要加入?
• 团队反馈哪些规则需要调整?

把规则当作活文档,不是一次性配置。

结论

说了这么多,其实核心就一句话:给 AI 定好规矩,它才能好好干活。

回想一下,你刚开始用 Cursor 的时候,是不是也经历过:

• 让它写个组件,结果风格乱七八糟
• 想让它用 TypeScript,它偷偷给你加 any
• 代码看起来很 AI,完全不像人写的

这不怪 Cursor,是我们没告诉它「我们的规矩」。

现在,你知道怎么做了:

1. 创建规则文件 — 新项目用 .cursor/rules,老项目先用 .cursorrules
2. 写清楚技术栈 — 版本号、框架、工具链,越具体越好
3. 定义代码规范 — 命名、风格、错误处理,给示例代码
4. 控制规则长度 — 500行以内,必要时拆分
5. 持续优化 — 规则不是一次性配置,要根据项目演进

现在就行动:

• 如果你还没配置过规则,花5分钟创建第一个规则文件
• 如果已经有规则了,检查一下是不是太模糊,加点示例代码
• 如果是团队项目,把规则提交到 Git,让大家一起遵守

一个月后,你会发现:

• Code review 时间少了一半
• 代码风格统一了
• 新人上手快了
• AI 真的成了你的得力助手

最后推荐几个资源,不用自己从零写规则:

• awesome-cursorrules - 2000+ star 的规则库
• awesome-cursorrules-zh - 中文开发者优化版
• cursorrules.org - 在线规则库

16 分钟阅读 · 发布于: 2026年1月10日 · 修改于: 2026年2月5日

Easton

技术开发