Cursor 中 MDC 规则的最佳实践与故障排除

MDC（Markdown Configuration）规则是 Cursor 强制执行编码标准、项目规范和 AI 行为准则的强大方式。正确配置后，它们能显著提升代码质量和一致性。本指南涵盖创建、组织和排除 MDC 规则故障的最佳实践。

什么是 MDC 规则？

MDC 规则是带有 YAML front matter 的 Markdown 文件，用于告诉 Cursor 在处理特定文件或特定上下文时如何表现。它们可以：

• 强制执行编码标准
• 定义项目架构模式
• 指定文档要求
• 控制特定文件类型的 AI 行为

文件格式要求

MDC 规则必须遵循以下确切格式：

---
description: '在此处填写规则描述'
globs: ['src/**/*.ts', 'tests/**/*.ts']
alwaysApply: false
---

# 规则标题

在此处填写规则内容...

## 具体指南

- 指南 1
- 指南 2

关键要求

要求	详情
扩展名	必须是 .mdc（不是 .md）
Front matter	必须使用 YAML 格式，位于 --- 分隔符之间
位置	必须位于 .cursor/rules/ 目录中
globs	此规则适用的文件模式数组
alwaysApply	布尔值 - 是否无需文件匹配即应用

命名约定

使用编号前缀系统进行组织：

.cursor/rules/
  001-core-coding-standards.mdc
  002-typescript-conventions.mdc
  003-react-patterns.mdc
  100-api-design.mdc
  101-database-models.mdc
  200-testing-requirements.mdc
  201-documentation-rules.mdc

编号系统

范围	类别	示例
001-099	核心规则（适用于所有文件）	编码标准、格式化
100-199	集成规则（特定领域）	API、数据库、认证
200-299	模式/角色规则	测试、文档
300-399	技术特定规则	React、Vue、Angular

编写有效的规则

具体且可操作

不好的示例：

编写优质代码。

好的示例：

## 错误处理

所有异步函数必须使用 try/catch 块：

```typescript
async function fetchUser(id: string): Promise<User> {
  try {
    const response = await api.get(`/users/${id}`);
    return response.data;
  } catch (error) {
    logger.error(`Failed to fetch user ${id}`, error);
    throw new UserNotFoundError(id);
  }
}

### 包含示例

始终展示正确和错误的示例：

```markdown
## 状态管理

✅ 应该：使用 React Query 管理服务器状态
```typescript
const { data, isLoading } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId)
});

❌ 不应该：使用 useEffect 获取数据

// 避免此模式
useEffect(() => {
  fetchUser(userId).then(setUser);
}, [userId]);

### 有效使用 Glob 模式

```yaml
# 应用于所有 TypeScript 文件
globs: ['**/*.ts', '**/*.tsx']

# 仅应用于后端代码
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']

# 应用于特定测试文件
globs: ['**/*.test.ts', '**/*.spec.ts']

# 排除某些文件
globs: ['src/**/*.ts', '!src/generated/**']

常见规则类别

1. 代码风格规则

---
description: '强制执行一致的代码风格'
globs: ['src/**/*.ts', 'src/**/*.tsx']
alwaysApply: true
---

# 代码风格标准

## 导入
- 分组导入：React、外部库、内部模块、类型
- 对 src/ 模块使用绝对导入
- 每组内按字母顺序排序

## 命名
- 组件：PascalCase（UserProfile）
- 钩子：camelCase，以 'use' 开头（useAuth）
- 常量：UPPER_SNAKE_CASE
- 文件：kebab-case（user-profile.tsx）

2. 架构规则

---
description: '强制执行整洁架构模式'
globs: ['src/**/*.ts']
alwaysApply: false
---

# 架构指南

## 层依赖关系
- 领域层：无外部依赖
- 应用层：仅依赖于领域层
- 基础设施层：依赖于应用层

## 文件组织

src/ domain/ # 业务逻辑、实体 application/ # 用例、DTO infrastructure/ # 数据库、API、外部服务 presentation/ # UI 组件

3. 测试规则

---
description: '测试要求和模式'
globs: ['**/*.test.ts', '**/*.test.tsx']
alwaysApply: true
---

# 测试标准

## 必需的测试
- 所有工具函数的单元测试
- 所有 React 组件的组件测试
- API 端点的集成测试
- 关键用户流程的 E2E 测试

## 测试结构
遵循 AAA 模式：
1. Arrange：设置测试数据和模拟
2. Act：执行被测试的函数
3. Assert：验证结果

常见问题故障排除

问题 1：更改未保存

症状： 你编辑了 .mdc 文件并保存，但 Cursor 未应用更改。

解决方案：

1. 完全关闭 Cursor（不只是关闭窗口 - 退出应用程序）
2. 重新打开 Cursor
3. 更改现在应该已应用

原因： MDC 规则在 Cursor 启动时会被缓存。它们不会热重载。

问题 2：规则未应用

症状： Cursor 在编辑文件时忽略你的规则。

检查清单：

• 文件扩展名是 .mdc（不是 .md）
• 文件位于 .cursor/rules/ 目录中
• Front matter 具有有效的 YAML 语法
• globs 模式匹配你的目标文件
• Markdown 内容中没有语法错误

调试命令：

# 检查 Cursor 是否识别你的规则
ls -la .cursor/rules/
# 验证文件扩展名
file .cursor/rules/*

问题 3：规则冲突

症状： 多个规则给出矛盾的指令。

解决顺序：

1. 具有更具体 glob 模式的规则优先
2. 带有 alwaysApply: true 的规则首先被评估
3. 按字母顺序，后面的规则覆盖前面的规则

最佳实践： 使用 priority 字段（如果支持）：

---
description: '高优先级规则'
globs: ['src/**/*.ts']
priority: 100
---

问题 4：规则过长

症状： Cursor 不遵循长规则中的所有指令。

解决方案： 拆分为多个重点明确的规则：

.cursor/rules/
  001-general-style.mdc       # 简短、通用指南
  002-error-handling.mdc      # 专门针对错误处理
  003-performance.mdc         # 性能优化

高级技巧

条件规则

使用 globs 将不同规则应用于代码库的不同部分：

# 前端规则
globs: ['src/components/**/*.tsx', 'src/pages/**/*.tsx']
---
使用 React hooks 模式。优先使用函数组件。

# 后端规则
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']
---
使用依赖注入。遵循 SOLID 原则。

规则继承

创建基础规则并扩展它：

---
description: '基础 TypeScript 标准'
globs: ['**/*.ts', '**/*.tsx']
alwaysApply: true
---

# 基础 TypeScript 规则

- 使用严格 TypeScript 配置
- 没有正当理由不得使用 `any` 类型
- 对于对象形状，优先使用 `interface` 而非 `type`

---
description: 'React 特定扩展'
globs: ['src/**/*.tsx']
alwaysApply: false
---

# React 规则

除基础 TypeScript 规则外：
- 使用带 hooks 的函数组件
- Props 接口必须导出
- 谨慎使用 React.FC（优先使用显式 props 类型）

带变量的动态规则

某些高级设置支持模板变量：

---
description: '项目特定约定'
globs: ['**/*.ts']
---

# 项目约定

## API 基础 URL
使用：{{API_BASE_URL}}

## 认证
Token 请求头：{{AUTH_HEADER_NAME}}

快速参考：MDC 规则模板

---
description: ''
globs: ['']
alwaysApply: false
---

# 标题

## 第 1 节
- 指南 1
- 指南 2

## 第 2 节
```typescript
// 示例代码

参考资料

• 文档链接

## 相关资源

- [有效使用 Cursor 规则](using-cursor-rules-effectively.mdx)
- [Cursor 规则最佳实践](best-practices-for-cursor-rules.mdx)
- [CursorRules 设置指南](cursorrules-setup-guide.mdx)