Cursor规则引擎深度解析：如何用MDC语法打造团队知识图谱

1. 规则引擎：团队知识管理的革命性工具

在技术团队协作中，知识碎片化一直是影响效率的顽疾。代码规范散落在Wiki文档里，技术决策埋没在会议记录中，项目约束隐藏在各种README文件角落——这种状态不仅让新人上手困难，也让老成员在跨项目协作时频繁踩坑。Cursor的规则引擎通过MDC（Markdown with Cursor）语法，将这些离散的知识点转化为可执行的AI规则，实现了团队知识的结构化与自动化应用。

与传统文档相比，MDC规则具备三个核心优势：

• 机器可读性：YAML元数据定义规则属性，Markdown正文描述具体约束，AI能直接理解并执行
• 动态生效：规则实时影响AI的代码生成、建议和审查，而非静态参考文档
• 版本可控：规则文件与代码库一起管理，变更可追溯

典型应用场景包括：

1. 新人 onboarding 时自动遵守代码规范
2. 架构守护（Architecture Guardrails）防止技术栈偏离
3. 跨项目统一技术决策执行
4. 自动化代码审查（AI Linting）

---
alwaysApply: true
description: "React组件规范"
globs: "src/components/**/*.tsx"
priority: 800
---
# 组件开发规范
1. 必须使用函数式组件+TypeScript
2. 禁止直接操作DOM，必须使用React Hook
3. 组件文件命名采用PascalCase

2. MDC语法详解：从文档到可执行规则

MDC语法巧妙结合了YAML的机器可读性和Markdown的人类可读性，形成独特的规则定义语言。一个完整的MDC文件包含两部分：

2.1 元数据区块（Frontmatter）

用---包裹的YAML区域，定义规则的技术属性：

---
# 规则是否全局应用
alwaysApply: false  

# 规则描述（AI会读取）
description: "API请求封装规范"

# 适用文件模式（支持glob语法）
globs: ["src/api/**/*.ts"]  

# 冲突时优先级（0-1000）
priority: 500  

# 自定义元数据（可选）
owner: "架构组"  
version: "1.2"
---

关键参数说明：

参数	必填	说明	示例
alwaysApply	是	是否自动应用规则	true/false
globs	否	目标文件匹配模式	["/*.ts", "!test/"]
priority	是	冲突时裁决优先级	0-1000整数

2.2 规则正文（Markdown）

使用标准Markdown语法编写具体约束，推荐结构：

# 一级分类标题
1. 通用要求
   - 子条款说明
   - 反面示例：`const a = 123`（错误）
   - 正面示例：`const a: number = 123`（正确）

# 二级分类标题
- 使用`@file`引用项目文件：
  ```ts
  // 正确：使用封装后的请求工具
  import request from '@file src/utils/request'

高级技巧：
- 使用代码块展示正反案例
- 通过`@file`直接关联项目中的参考实现
- 用表格对比不同场景下的合规要求

## 3. 规则类型与权限设计

Cursor支持多层次的规则体系，满足不同场景的管控需求：

### 3.1 项目规则（Project Rules）

存储在`.cursor/rules/`目录下的MDC文件，特点包括：
- 全团队共享，纳入版本控制
- 适用于项目级约束（如技术栈、架构规范）
- 修改需要代码评审流程

创建步骤：
1. 在Cursor设置中点击"Add Project Rule"
2. 命名规则文件（如`style-guide.mdc`）
3. 编辑并提交到代码库

### 3.2 用户规则（User Rules）

保存在本地`~/.cursor/rules/`的个人规则，特点包括：
- 仅影响当前用户
- 适用于个人编码习惯
- 格式更灵活（支持.txt/.md等）

冲突解决原则：
1. 同类型规则按priority排序
2. 项目规则 > 用户规则
3. 相同优先级时后加载的生效

> 提示：在团队协作中，建议将核心规范设为项目规则（priority≥500），个人偏好设为用户规则（priority≤300）

## 4. 规则的高级应用模式

### 4.1 上下文感知的规则激活

通过`globs`参数实现精准匹配：

```yaml
---
# 仅在前端组件文件生效
globs: "src/components/**/*.{tsx,jsx}"  

# 排除测试文件
exclude: "**/*.test.*"  
---

4.2 复合规则策略

多个规则文件协同工作示例：

1. base.mdc（priority: 300）：基础编码规范
2. react.mdc（priority: 600）：React特定规范
3. project.mdc（priority: 800）：项目特殊要求

4.3 动态规则引用

在聊天窗口使用@Cursor Rules触发规则应用：

@Cursor Rules 检查当前组件是否符合规范
@file src/components/UserForm.tsx

AI将：

1. 加载所有适用的MDC规则
2. 分析目标文件
3. 生成合规性报告

5. 实战：构建团队知识图谱

5.1 知识拆解与结构化

将传统文档转化为MDC规则的技巧：

原始需求： "API调用必须使用封装后的request工具，错误处理要统一格式"

MDC实现：

---
description: "API调用规范"
globs: "src/api/**/*.ts"
priority: 700
---
# 请求封装
1. 必须使用统一请求工具：
   ```ts
   // 正确
   import request from '@file src/utils/request'

错误处理

• 必须捕获并转换错误格式：

  // 标准格式
  interface ErrorResult {
    code: number;
    message: string;
    data?: unknown;
  }
  

### 5.2 规则版本演进

通过Git管理规则变更历史：
```bash
# 查看规则修改记录
git log -p -- .cursor/rules/

# 比较不同版本差异
git diff v1.0..main -- rules/

5.3 新人培养体系

典型onboarding流程：

1. 克隆代码库（含.cursor/rules）
2. 安装Cursor插件
3. 执行初始化命令：

   cursor @Cursor Rules 生成新人checklist
   

4. AI根据规则库生成：
   • 必读规范摘要
   • 示例代码练习
   • 本地环境检查项

6. 效能提升技巧与排错

6.1 调试规则生效情况

检查路径：

1. 确认文件匹配模式：

   # 测试glob模式
   ls src/**/*.ts | grep -v test
   

2. 查看规则加载顺序：

   cat .cursor/rules/*.mdc | grep priority
   

6.2 性能优化方案

当规则较多时：

• 按功能拆分为多个小规则
• 使用exclude减少不必要的文件扫描
• 复杂规则添加cache: true元数据

6.3 常见问题解决

症状：规则未生效

• 检查文件扩展名是否为.mdc
• 确认globs路径相对于项目根目录
• 尝试提高priority值

症状：AI建议不符合预期

• 确保规则描述清晰无歧义
• 添加更多正反示例
• 使用@Cursor Rules显式触发

在大型金融项目中，我们通过MDC规则将300+页技术规范浓缩为45条可执行规则，使代码审查耗时减少70%，新人产出合格代码的时间从2周缩短到3天。关键在于从"文档约束"转变为"AI即时守护"，让知识真正流动在开发流程中。