跳到主要内容

深入解析Cursor的.mdc文件：格式、来源与作用

当您开始使用 Cursor 这款强大的AI辅助代码编辑器时，可能会在项目中遇到一个特殊的目录 .cursor/rules/，里面存放着以 .mdc 为扩展名的文件。这些文件是什么？它们与我们熟知的 .md (Markdown) 文件有何不同？本文将结合官方文档和社区讨论，为您详细解析 .mdc 文件。

1. .mdc 文件是什么？​

在Cursor的生态系统中，.mdc 文件是专门用来定义 “AI规则 (AI Rules)” 的文件。

简单来说，它是一个结构化的文本文件，旨在为Cursor的AI提供持久的、可复用的上下文和指导。通过编写规则，您可以告诉AI在您的项目中应该遵循什么样的编码风格、架构模式、命名规范或特定的业务逻辑，从而让AI生成的代码更符合您的期望。

2. 来源与含义：MDC代表什么？​

根据Cursor社区论坛中引用的Cursor工程师 Michael Feldstein 的解释，.mdc 这个扩展名是 "Markdown Cursor" 的缩写。

它本质上就是一个Markdown文件，但Cursor赋予了它特殊的用途和处理方式，并为其指定了一个独特的扩展名。

3. 作用与目的：为什么要使用规则？​

大型语言模型（LLM）本身不具备跨多次交互的长期记忆。如果您每次都通过聊天重复相同的指令（例如“请使用小驼峰命名法”），效率会非常低下。.mdc 规则文件就是为了解决这个问题。

其核心作用包括：

  • 提供持久化上下文： 将项目的核心规范、编码风格、常用库的使用方法等固化下来，让AI在每次交互时都能获取这些背景信息。
  • 确保代码一致性： 在团队项目中，通过共享一套 .mdc 规则，可以保证所有成员（包括AI）生成的代码风格统一。
  • 提高AI准确性： 为AI提供清晰、具体的示例和指令，减少AI“猜”的成分，使其生成的代码更贴近项目需求。
  • 自动化工作流： 规则可以被设置为在特定条件下自动应用，从而简化您的工作流程。

4. 文件格式与结构​

一个 .mdc 文件由两个主要部分组成，它结合了YAML的元数据能力和Markdown的表达能力。

a. YAML Front Matter (头部元数据)​

文件顶部由三短划线 --- 包围的区域，就是我们所说的头部元数据。它使用YAML语法，其核心作用是作为给Cursor编辑器的“配置文件”，通过设置不同的字段来精确控制规则的应用时机和方式。

下面我们详细介绍几个关键的元数据字段：

  • description (描述)

    • 作用： 这是给AI看的、关于此规则用途的自然语言描述。一个清晰、准确的描述至关重要，因为它能帮助Cursor的AI在没有globs匹配或未被手动@引用时，根据聊天上下文的“相关性”来智能地决定是否应该应用此规则。这直接关系到 Agent Requested (AI请求) 这种应用方式。
    • 使用方法： 尽量用一两句话清晰地概括规则的核心内容和适用场景。
    • 示例： 
      ---
      description: '提供了与Stripe支付网关集成的标准函数、API调用方法和错误处理的最佳实践。'
      ---
      当您向AI提问“帮我写一段处理Stripe支付的代码”时，AI会因为“Stripe支付”这个关键词而智能地找到并应用这个规则。

  • globs (文件匹配模式)

    • 作用： 这是一个包含一个或多个文件路径匹配模式的列表，用于实现 Auto Attached (自动附加) 的应用方式。当您正在编辑或通过 @ 引用的文件路径与这里的模式匹配时，此规则会自动被激活。
    • 使用方法： 使用标准的glob模式语法。
      • * 匹配任意数量的字符（不包括路径分隔符 /）。
      • ** 匹配任意数量的目录层级。
      • ! 前缀表示排除模式。
      • {} 用于定义一个集合。
    • 示例： 
      ---
      globs:
        - "src/components/**/*.tsx"  # 匹配src/components目录下所有的.tsx文件
        - "src/utils/api.ts"         # 精确匹配这一个文件
        - "!src/utils/legacy_api.ts" # 使用 '!' 来排除特定文件
        - "src/{hooks,lib}/*.js"     # 匹配hooks和lib目录下的所有.js文件
      ---

  • alwaysApply (总是应用)

    • 作用： 一个布尔值（true 或 false），用于实现 Always (总是应用) 的应用方式。如果设置为 true，这个规则将成为一个全局规则，在您打开的任何文件中都会被无条件地激活。
    • 使用方法： 直接设置为 true。
    • 使用场景： 非常适合定义全局性的、项目范围的编码规范、AI回复风格、或通用的编程原则。
    • 示例： 
      ---
      alwaysApply: true
      ---
      (这通常用于类似“总是使用TypeScript”或“回复风格要简洁”这样的通用指令。)

  • name (名称)

    • 作用： 给规则起一个人类可读的名称。这个名称主要用于在Cursor的UI界面（如规则列表）中展示，方便用户识别。它也可能被用于 Manual (手动调用) 的场景，当您输入 @ 时，可以通过这个名称来搜索和引用规则。
    • 使用方法： 提供一个简短、描述性的标题。
    • 示例： 
      ---
      name: "React组件状态管理规范"
      ---

规则应用方式总结​

应用方式主要配置方式描述
Always设置 alwaysApply: true规则在任何时候都自动生效。
Auto Attached设置 globs 列表当打开或引用的文件路径与globs模式匹配时，规则自动生效。
Agent Requested提供一个清晰的 description当用户的提问或代码上下文与规则的description语义相关时，AI会自动选择并应用该规则。
Manual依赖于文件名或 name 字段用户通过在聊天或编辑器中输入 @ 并选择规则名称，来手动、按需地激活规则。

b. Markdown 内容 (Main Content)​

在头部元数据之后的部分，就是您希望AI遵循的具体指令。这部分内容是用标准的Markdown语法编写的。

您可以在这里使用标题、列表、代码块、引用等所有Markdown功能，来清晰地向AI阐述：

  • 规则的具体内容： 例如，“所有函数都必须有JSDoc风格的注释。”
  • 代码示例： 提供清晰的“正确示例”和“错误示例”，这对AI的理解至关重要。
  • 逻辑解释： 解释为什么要有这条规则。

综合示例 (api-usage-rule.mdc):

---
name: "AIbaseAPI 使用规范"
description: "如何正确调用我们项目中的 AIbaseAPI，特别是错误处理部分。"
globs:
  - "src/services/**/*.ts"
---

# AIbaseAPI 使用规范

在调用 `AIbaseAPI` 时，必须使用 `try...catch` 结构来处理潜在的异常。

## 正确示例

```typescript
import { AIbaseAPI } from '@/api';

async function fetchData(id: string) {
  try {
    const response = await AIbaseAPI.getItem(id);
    return response.data;
  } catch (error) {
    console.error("获取数据失败:", error);
    // 在这里添加用户友好的错误处理逻辑
    return null;
  }
}
``` 
## 错误示例

```typescript
// 错误：没有错误处理
async function fetchData(id: string) {
  const response = await AIbaseAPI.getItem(id);
  return response.data;
}
```

5. 为何使用 .mdc 而非 .md？​

选择一个独特的 .mdc 扩展名，而不是直接使用通用的 .md，主要是出于以下两个原因：

  1. 功能区分 (Functional Distinction): 这帮助Cursor编辑器和用户清晰地识别出哪些文件是包含AI指令的“规则文件”，哪些是普通的文档（如 README.md）。
  2. 定制化编辑器体验 (Custom Editor Experience): 使用独特的扩展名可以让Cursor为这类文件提供一个定制的编辑器界面。例如，当您在 .mdc 文件中编辑时，Cursor可能会提供特殊的功能，比如通过 @ 符号轻松引用项目中的其他文件，或者对元数据部分进行语法高亮和智能提示。

6. 如何使用？​

使用规则的步骤如下：

  1. 创建目录： 在您项目的根目录下，创建一个名为 .cursor 的文件夹。
  2. 创建规则子目录： 在 .cursor 文件夹内，再创建一个名为 rules 的文件夹。最终路径应为 .cursor/rules/。
  3. 放置规则文件： 将您编写的所有 .mdc 规则文件都放在这个 rules 目录下。

Cursor会实时监控这个目录，自动发现并根据每个文件的元数据来应用这些规则。

希望这篇详细的解释能帮助您更好地理解和使用Cursor强大的 .mdc 规则功能。

最后于 更新