Cursor Rules 进阶配置：打造专属的 AI 编程助手

你有没有遇到过这种情况：同一个项目中，Cursor 有时生成的代码风格优雅，有时却又完全不符合你的习惯？明明在 .cursorrules 里写了一堆规则，AI 却好像「视而不见」？更让人头疼的是，换了项目又要重新配置一遍……

说实话，我第一次用 Cursor Rules 的时候也踩过这个坑。花了好几个小时写了规则，结果 AI 生成的代码还是老样子。后来才发现，问题不在于规则本身，而是我对这套系统的理解完全跑偏了。

这篇文章，我想跟你聊聊 Cursor Rules 的进阶玩法。不是那种「什么是 .cursorrules」的入门介绍，而是真正帮你把这套工具用起来、用好的实战经验。

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

领取 8.5 折优惠 →推广

一、Cursor Rules 核心概念重构

1.1 从 .cursorrules 到 .cursor/rules：规则系统的演进

如果你用 Cursor 有一段时间了，可能还在用传统的 .cursorrules 单文件。这玩意儿确实能用，但说实话，局限性挺明显的。

单文件的问题在哪？一是所有规则都挤在一个文件里，维护起来头疼；二是没法针对不同类型的文件设置不同的规则。举个例子，你的项目既有 React 组件又有 Python 脚本，想把规则分开写？单文件做不到。

2026 年 Cursor 推出了新的 .cursor/rules/ 目录结构，配合 MDC 格式，这些问题基本都解决了。

新的目录结构长这样：

.cursor/
└── rules/
    ├── base.mdc          # 基础规范
    ├── frontend.mdc      # 前端规则
    ├── backend.mdc       # 后端规则
    └── testing.mdc       # 测试规则

每个文件都是独立的规则模块，可以用 glob 模式指定作用范围。比如 frontend.mdc 只对 .tsx 文件生效，backend.mdc 只对 .py 文件生效。

迁移起来也不麻烦。老项目的 .cursorrules 还能用，新项目直接用新格式就行。如果你想把老项目升级，把单文件拆成多个 .mdc 文件就好，向后兼容，不用担心出问题。

1.2 三种规则类型的正确使用场景

Cursor 的规则系统分三种类型，很多人搞不清楚它们之间的关系。

Project Rules（项目规则） 放在 .cursor/rules/ 目录下，只对当前项目生效。适合写项目特有的东西，比如你用的是 React 18 + Tailwind，就把技术栈声明放这儿。团队其他人 clone 项目后，自动就能用上这些规则。

Team Rules（团队规则） 存在云端，团队成员共享。适合放团队的编码规范，比如「所有组件都用命名导出」「API 响应格式统一」。这个需要 Cursor 的 Team 版本才能用。

User Rules（用户规则） 在 Cursor 设置里配置，对你所有项目都生效。适合放个人偏好，比如你喜欢用 Tab 缩进还是空格，喜欢中文注释还是英文注释。

优先级是这样的：User Rules 优先级最高，然后是 Team Rules，最后是 Project Rules。也就是说，如果 User Rules 里写了「用空格缩进」，Project Rules 里写了「用 Tab 缩进」，最终会按 User Rules 来。

1.3 规则生效的底层逻辑

这块内容稍微技术一点，但理解了对你写规则很有帮助。

AI 在处理你的请求时，会把规则文件的内容作为上下文的一部分「喂」给模型。这意味着规则会占用 token。所以规则不是越长越好，写一堆废话只会浪费 token，效果反而不好。

文件模式匹配（globs）的工作原理跟 .gitignore 类似。写 ["**/*.tsx"] 就匹配所有 tsx 文件，写 ["app/api/**/*"] 就匹配 app/api 目录下的所有文件。

如果多个规则对同一个文件都生效怎么办？Cursor 会按文件名的字典序加载，先加载的规则优先级更高。所以你可以用数字前缀控制加载顺序，比如 00-base.mdc、01-frontend.mdc。

二、实战配置：从零到一的完整指南

2.1 基础配置：React + TypeScript 项目

先从一个简单的 React 项目开始。下面是一个完整的规则配置，你可以直接复制到 .cursor/rules/react.mdc：

---
description: React + TypeScript 项目规则
globs: ["**/*.{ts,tsx}"]
---

# 技术栈
- React 18+
- TypeScript 5.0+
- Tailwind CSS

# 代码风格
- 使用函数式组件，用 function 关键字声明
- 用 TypeScript 接口定义 Props
- 组件文件结构：exported component → subcomponents → helpers → types
- 使用命名导出，避免 default export

# React 最佳实践
- 优先使用 Server Components（如果用 Next.js）
- 状态管理用 useState 和 useReducer
- 副作用用 useEffect，记得写清理函数
- 用 React.memo 优化性能敏感的组件

# 错误处理
- 优先用 early return 模式
- 用 guard clauses 处理边界情况
- 给用户友好的错误提示，别直接抛原始错误

这个规则的结构很简单：先声明技术栈，让 AI 知道你在用什么框架；然后是代码风格，告诉 AI 你想要的写法；最后是最佳实践和错误处理，提供一些具体的指导。

2.2 进阶配置：Next.js 14 全栈项目

Next.js 项目会更复杂一些，因为涉及前后端。推荐用模块化的方式组织规则：

.cursor/
└── rules/
    ├── base.mdc          # 基础规范
    ├── api.mdc           # API 路由规则
    ├── components.mdc    # 组件规则
    ├── database.mdc      # 数据库规则
    └── testing.mdc       # 测试规则

来看 api.mdc 的例子：

---
globs: ["app/api/**/*.{ts,tsx}"]
---

# API 路由规范
- 使用 Route Handlers (app/api/)
- 所有响应用统一的 APIResponse 类型
- 用 Zod 验证请求参数
- 错误处理用 next-safe-action

# 响应格式
- GET 请求：返回 { success: boolean, data?: T, error?: string }
- POST 请求：验证输入 → 处理逻辑 → 返回响应
- 错误分类：验证错误、业务错误、系统错误，分别处理

这样做的好处是，API 相关的规则只会在你编辑 app/api/ 目录下的文件时生效。不会在你写组件的时候，AI 给你整一堆 API 相关的建议。

2.3 高级配置：Python FastAPI 后端项目

如果你的后端是用 Python 写的，规则写法会不太一样：

---
description: Python FastAPI 项目规则
globs: ["**/*.py"]
---

# 技术栈
- Python 3.12+
- FastAPI 0.100+
- SQLAlchemy 2.0
- Pydantic v2

# 代码风格
- 用 Black 格式化代码
- 用 isort 排序导入
- 写 type hints，别偷懒
- 函数命名用 snake_case

# FastAPI 最佳实践
- 用依赖注入管理数据库连接
- 用 Pydantic 模型验证输入
- 用 background tasks 处理异步任务
- 实现统一的错误处理中间件

# 数据库
- 用 SQLAlchemy 2.0 异步 API
- 用 Alembic 管理数据库迁移
- 实现软删除和审计日志

Python 项目的规则重点在于风格工具（Black、isort）和类型提示。AI 生成代码的时候会自动遵循这些规范。

2.4 团队协作配置：多人项目管理

如果你是团队 Tech Lead，想统一团队的编码风格，可以这样组织：

项目根目录/
├── .cursor/
│   └── rules/
│       ├── README.md           # 规则使用说明
│       ├── base.mdc            # 全局基础规范
│       ├── frontend.mdc        # 前端规则
│       ├── backend.mdc         # 后端规则
│       └── team-guidelines.mdc # 团队规范
└── .cursorrules                # 向后兼容（可选）

几个实践建议：

把规则纳入版本控制。这样每个人 clone 项目就能用，不用额外配置。

每个规则文件加注释说明。新人加入团队时，看看规则文件就能理解团队的编码规范。

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

立即开始 →推广

定期评审和更新规则。项目在演进，规则也需要跟着变。建议每个迭代复盘一下规则效果。

三、调试与优化：让规则真正生效

3.1 规则调试技巧

写了规则但 AI 不按规则来？这是最常见的问题。下面是我总结的诊断清单：

1. 检查文件位置

规则文件必须放在正确的目录：

• .cursor/rules/ 目录下（推荐）
• 或者项目根目录的 .cursorrules 文件

如果位置不对，AI 根本读不到。

2. 检查 glob 模式

globs 配置错了，规则就不会生效。在 Cursor 里打开一个文件，直接问 AI：「告诉我当前加载了哪些规则？」AI 会告诉你它看到了哪些规则。

3. 检查 YAML 格式

MDC 文件开头的 frontmatter 是 YAML 格式。缩进错了、冒号漏了，都会导致解析失败。

4. 检查规则冲突

多个规则可能互相冲突。看看是不是有两个规则对同一件事有不同的要求，合并一下就好。

3.2 规则优化策略

很多同学觉得规则写得越多越好。其实不是。规则太长，AI 反而「消化不良」。

原则一：精简至上

把最重要的规则放前面。AI 读规则也是从头读到尾，前面的内容更容易被记住。

原则二：具体明确

来对比一下：

模糊的写法：

# 代码风格
- 写简洁的代码
- 使用最佳实践
- 注意性能

具体的写法：

# 代码风格
- 用函数式组件，避免 class 组件
- 用 early return 模式，减少嵌套
- 用 React.memo 包装性能敏感组件
- 避免在循环里写内联函数

第二种写法，AI 明确知道该怎么做。第一种写法，AI 只能「猜」。

原则三：分层组织

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

查看定价 →推广

按「技术栈 → 代码风格 → 最佳实践 → 错误处理」的顺序组织。逻辑清晰，AI 也容易理解。

原则四：持续迭代

规则不是写完就完事了。用一段时间，看看 AI 生成的代码质量有没有变好，不好的地方再调整。

3.3 规则效果评估

怎么知道规则有没有用？看这几个指标：

• 一次通过率：AI 生成的代码，你直接能用的比例有多高？
• 风格一致性：不同时间生成的代码，风格是不是统一？
• Bug 数量：规则生效后，Bug 有没有变少？
• 开发效率：写代码是不是更快了？

记录一下这些指标，对比规则使用前后的变化，你就知道规则是不是真的在帮你。

四、2026 年最新实践：MDC 格式与模块化

4.1 MDC 格式深度解析

MDC 是 Cursor 推出的新规则格式，比传统的 .cursorrules 灵活很多。

文件结构长这样：

---
description: 规则描述（可选）
globs: ["文件匹配模式"]
alwaysApply: false（可选，默认 false）
---

# 规则内容
具体的规则内容写在这里...

description 是给人看的，方便理解这个规则的用途。

globs 是文件匹配模式，决定规则在哪些文件生效：

• ["**/*.tsx"] — 匹配所有 tsx 文件
• ["app/api/**/*"] — 匹配 app/api 目录下的所有文件
• ["*.test.{ts,tsx}"] — 只匹配测试文件

alwaysApply 设为 true 时，规则会始终生效，不受文件匹配限制。一般不建议用，会浪费 token。

4.2 模块化规则架构

大型项目推荐用更细粒度的模块化结构：

.cursor/
└── rules/
    ├── 00-base.mdc           # 基础规范
    ├── 01-tech-stack.mdc     # 技术栈声明
    ├── 02-code-style.mdc     # 代码风格
    ├── 10-frontend/          # 前端规则（子目录）
    │   ├── react.mdc
    │   └── tailwind.mdc
    ├── 20-backend/           # 后端规则（子目录）
    │   ├── api.mdc
    │   └── database.mdc
    └── README.md             # 规则使用文档

数字前缀控制加载顺序。00- 开头的先加载，10- 的后加载。这样你可以确保基础规范先生效。

子目录支持更细粒度的管理。前端规则放 10-frontend/，后端规则放 20-backend/，找起来方便。

4.3 规则生成工具推荐

不想从头写规则？有几个社区工具可以帮忙：

cursor.directory — 在线规则库，有各种框架的模板，可以直接复制。

cursorrules.org — 交互式规则生成器，回答几个问题，自动生成规则文件。

awesome-cursorrules — GitHub 上的精选规则集合，有 100 多个模板，覆盖 20 多种框架。

不过我建议，从模板开始，但要根据项目定制。别照搬，理解规则背后的原理，才能写出真正适合自己的规则。

五、总结与行动建议

5.1 快速上手清单

如果你现在就想开始，按这个步骤来：

第一步：确定项目类型。React？Next.js？Python？还是别的？

第二步：从社区模板选一个相近的。cursor.directory 或者 awesome-cursorrules 都有。

第三步：根据项目特点定制。改改技术栈版本，加一些你自己的习惯。

第四步：测试效果。写几段代码，看看 AI 生成的代码是不是更符合你的预期。

第五步：团队共享。如果效果好，把规则提交到版本控制，让团队一起用。

5.2 避坑指南

最后说几个我踩过的坑：

规则太笼统 — AI 不知道你想要什么。写得具体一点。

规则文件太长 — 200 行以内就好，太长 AI 读不完。

不测试就用 — 先小范围验证，确认有效再全面铺开。

从不更新 — 项目在变，规则也要跟着变。定期复盘一下。

5.3 进一步学习资源

想深入了解的话，这些资源可以看看：

• Cursor 官方文档 — 最权威的说明
• awesome-cursorrules — 社区精选规则
• Cursor 社区论坛 — 问题讨论和经验分享

现在就打开你的项目，给它配置第一个 Cursor Rules 吧。从简单的开始，慢慢完善。你会惊讶地发现，AI 变得越来越「懂你」了。

12 分钟阅读 · 发布于: 2026年3月20日 · 修改于: 2026年3月22日

Easton

AI与智能