Skip to Content
工程化实践3. 制定 Cursor RulesRules 编写最佳实践

Cursor Rules 编写最佳实践

让 AI 严格执行你项目的独特要求

本文假设你已了解 Rules 的工作原理，包括 Rules 类型、应用方式和文件结构。

核心理念

Cursor Rules 的唯一使命是：让 AI 生成的代码符合你项目的独特规范。

很多人误以为 Rules 应该包含各种”最佳实践”和通用知识。实际上，大模型已经知道这些内容。你需要告诉 AI 的是：在这个项目里，我们这样做。

⚠️

反面教材：GitHub 上的”Rules 大全”

awesome-cursorrules  是 GitHub 上的热门项目，但其中大量 Rules 都是废话。例如它的 react.mdc ：

  • “Use functional components with hooks” - AI 早就知道这是现代 React 的标准
  • “Write clean, readable code” - 这种空话对 AI 毫无价值
  • “Follow React best practices” - 太模糊，等于没说

这些通用建议不仅浪费 token，还会稀释你真正需要的项目独特 Rules。不要照抄这些模板，只写你项目里独有的硬性规定。

常见误区正确做法
❌ “使用有意义的变量名”✅ “变量命名使用 camelCase，组件使用 PascalCase”
❌ “遵循 React 最佳实践”✅ “所有页面组件放在 src/pages/，使用默认导出”
❌ “写干净的代码”✅ “使用 @/ 作为导入路径前缀，避免 barrel exports”

六大核心原则

原则核心要点反面示例正确示例
1. 极度具体只写项目独有的强制规范”使用 TypeScript""避免 any，用 unknown”
2. 短小精悍1-3 行/条，不超过 200 行冗长的日期格式化说明formatDate() from @/lib/date-time-utils.ts
3. 分文件匹配按主题拆分，用 globs 限定作用域所有 Rules 塞在一个文件api-rules.mdc 只管 src/clients/**
4. 提供示例附上 import 和代码示例”使用 SWR 获取数据”完整的 useSWR 代码片段
5. 快速迭代从 3-5 条痛点 Rules 开始一次性写 500 行”完美 Rules”发现问题立即补充
6. 工具链验证让 AI 自动执行 lint/test没有验证步骤要求 npm run build 通过

1. 极度具体、可直接执行

只写项目独有的强制规范，避免泛泛的描述。

// ❌ 模糊的 Rules
- 使用 TypeScript 进行类型安全开发
- 遵循组件化设计原则
 
// ✅ 具体的 Rules
- 避免使用 `any`，不确定类型时使用 `unknown`
- 使用 interface 定义对象形状，使用 type 定义联合类型
- 导出函数必须指定返回类型

2. 短小精悍，狠砍废话

每条 Rule 1-3 行，单个 .mdc 文件控制在 100-200 行以内。

大模型已知的常识不需要重复。比如 “函数应该职责单一” 这种，AI 早就知道了。

// ❌ 冗长的说明
日期格式化说明：在本项目中，我们统一使用特定的日期格式化方法来确保
所有日期显示的一致性。当您需要格式化日期时，请务必使用我们封装的
工具函数，而不是直接使用原生 API 或第三方库...
 
// ✅ 简洁的 Rule
- 日期格式化使用 `formatDate()` from `@/lib/date-time-utils.ts`
- 金额格式化使用 `formatMoney()` from `@/lib/money-utils.ts`

3. 分文件、精准匹配

在 .cursor/rules/ 目录下按主题拆分 Rules 文件，使用 globs 限定作用域。关于 Rules 的四种应用方式，请参考 Rules 应用方式。

Rules 文件作用范围何时触发
global-rules.mdcalwaysApply: true始终生效
routing-rules.mdcglobs: src/pages/**编辑页面文件时
api-rules.mdcglobs: src/clients/**编辑 API 客户端时
ui-rules.mdcglobs: *.tsx编辑组件文件时
# global-rules.mdc - 核心规范始终生效
---
alwaysApply: true
---
 
# api-rules.mdc - 只在编辑 API 相关文件时生效
---
globs: src/clients/**
alwaysApply: false
---

4. 提供具体示例

附上 import 位置和示例代码，减少 AI 猜测，统一项目规范。

// ❌ 只说不做
- 使用 SWR 进行数据获取
 
// ✅ 给出完整示例
## SWR Integration
 
import useSWR from 'swr'
import { getUserInfo, getUserInfoKey } from '@/clients/user/get-user-info'
 
const { data, error, isLoading } = useSWR(
  getUserInfoKey(id),
  () => getUserInfo(id)
)

5. 从少到多，快速迭代

不要试图一开始就写完美的 Rules。

阶段做法
起步添加 3-5 条当前最痛的 Rules
测试立即测试 AI 输出效果
迭代根据问题补充或调整

当你发现 AI 反复犯同一个错误时，就是添加新 Rule 的时机。

6. 工具链配置

让 AI 在完成任务后自动执行工具链验证。

## Quality Standards
 
- Ensure `npm run lint` and `npm run build` passes before commits
- Run `npm test` to verify changes don't break existing functionality

Rules 结构模板

关于 .mdc 文件的完整格式规范，请参考 Rules 文件结构。一个完整的 Rules 文件通常包含以下部分：

---
globs: src/components/**
alwaysApply: false
---
 
# [Rule 名称]
 
## [分类1]
- 具体 Rule 条目
- 另一条 Rule
 
## [分类2]
 
### 示例
代码示例...
 
## 相关文件
- `@/lib/xxx.ts` - 描述
- `@/types/xxx.ts` - 描述

团队协作

Project Rules 必须提交到 Git，这样可以：

  • 确保团队所有成员使用相同的 Rules
  • Rules 变更有历史记录可追溯
  • 新成员能快速了解项目规范
.cursor/
└── rules/
    ├── global-rules.mdc
    ├── routing-rules.mdc
    ├── ui-rules.mdc
    └── api-rules.mdc

参考示例

查看我们收集的完整 Rules 示例：

下一步

了解了编写原则后，接下来我们看看在开发过程中何时编写这些 Rules。

最后更新于:
Rules 的工作原理Rules 迭代与沉淀