1. 项目概述：为你的AI编程伙伴制定“家规”

如果你和我一样，日常开发已经离不开像 Cursor 这样的 AI 编程助手，那你一定也经历过类似的“甜蜜烦恼”：它生成的代码，有时天马行空，有时又过于冗长，风格飘忽不定，需要你反复调整提示词才能得到满意的结果。这就像请了一位才华横溢但缺乏统一工作流程的实习生，你需要花大量时间去沟通和校对。今天要聊的这个项目—— DeGraciaMathieu/cursor-mdc-rules ，就是为解决这个问题而生的。它本质上是一套为 Cursor 定制的“代码生成规则”，你可以把它理解为给 AI 助手制定的“家规”或“编码规范”。这套规则的核心目标非常明确： 让 AI 生成的代码意图清晰、易于阅读、便于测试和维护，同时降低开发者的认知负担和代码的脆弱性 。无论你是独立开发者，还是团队协作，这套规则都能显著提升你与 Cursor 的协作效率，让 AI 生成的代码从一开始就更贴近你的项目标准和最佳实践。

2. 规则集的设计哲学与核心价值

2.1 为什么需要为AI制定规则？

在深入这套规则的具体内容之前，我们有必要先理解其背后的设计哲学。AI 模型，尤其是大型语言模型，本质上是基于海量数据训练出的概率生成器。它“知道”无数种写 for 循环、定义函数、处理异常的方式，但它并不知道 你的项目 具体偏好哪一种。如果没有约束，AI 会倾向于生成它认为“最普遍”或“最可能”的代码，这未必符合你项目的特定要求。

举个例子，你的团队可能约定使用 early return 来减少嵌套，提升可读性，但 AI 可能会生成一个深度嵌套的 if-else 链。又或者，你的项目要求所有数据库查询都必须使用参数化绑定来防止 SQL 注入，但 AI 可能会直接拼接字符串。这些不一致性就是“认知负担”和“脆弱点”的来源。每次审查 AI 生成的代码，你都需要在大脑中切换上下文，去判断这段代码是否符合规范，这消耗了本应用于思考业务逻辑的精力。

cursor-mdc-rules 这套规则集，就是将你（或团队）的编码偏好、最佳实践和安全准则，以一种机器可读的方式“教”给 Cursor。它让 AI 的创造力在一个安全、一致的框架内发挥，从而生成 开箱即用、符合标准 的代码。

2.2 规则的核心原则解析

根据项目描述，所有规则共享同一个目标，我们可以将其拆解为几个关键原则：

  1. 清晰传达意图 ：代码不仅是给机器执行的，更是给人读的。规则会引导 AI 使用有意义的变量名、函数名，保持函数功能单一，并通过代码结构本身来表明其目的，减少需要依赖注释才能理解的情况。
  2. 易于阅读和测试 ：规则会鼓励生成松散耦合、高内聚的代码块。这意味着函数更短小、职责更明确，输入输出清晰，从而使得单元测试的编写变得异常简单。同时，良好的命名和结构也让代码在数月后依然易于理解。
  3. 降低认知负荷 ：通过强制执行一致的代码风格（如缩进、括号位置、命名约定）和设计模式（如避免深度嵌套、使用 guard clauses），开发者阅读代码时无需在风格差异上分心，可以专注于业务逻辑本身。
  4. 减少脆弱点 ：规则会包含安全性和健壮性方面的引导，例如强制进行空值检查、提倡不可变数据、避免使用全局状态等。这些实践能从源头减少潜在的 bug 和安全漏洞。

这套规则源自在法国开发者社区中颇受好评的“PHP: The Readability Way”理念，其精髓在于将代码的可读性和可维护性置于首位，这与现代软件工程的核心诉求高度一致。

3. 规则集的获取与部署实操

3.1 一键获取规则文件

项目提供了极简的部署方式。你只需要在终端中，进入你的 项目根目录 ，执行以下命令：

curl -s https://raw.githubusercontent.com/DeGraciaMathieu/cursor-mdc-rules/main/download.sh | bash

这个命令做了两件事：

  1. curl -s ：静默模式下载位于 GitHub 上的 download.sh 脚本文件内容。
  2. | bash ：将下载的脚本内容通过管道传递给 bash 解释器并立即执行。

执行环境确认 ：在执行前，请确保你的系统已安装 curl 。对于 macOS 和大多数 Linux 发行版，这通常是预装的。Windows 用户如果使用 Git Bash 或 WSL，同样可以使用。

3.2 规则目录的定位与验证

执行完上述命令后，脚本会在 你当前所在的目录 中，创建一个名为 .cursor 的隐藏文件夹（如果不存在的话），并在其中创建 rules 子目录，最后将所有的规则文件（通常是 .mdc 文件）下载到该目录中。

因此，正确的项目结构应该是：

你的项目根目录/
├── .cursor/
│   └── rules/
│       ├── rule1.mdc
│       ├── rule2.mdc
│       └── ...
├── src/
├── package.json (或 composer.json 等)
└── ...

关键注意事项 ：

规则必须放置在项目根目录下的 .cursor/rules 路径中，Cursor 才会自动识别并应用它们。如果你把项目放在 ~/Documents/code/my-project ，那么规则路径就是 ~/Documents/code/my-project/.cursor/rules 。

如何验证 ：你可以通过 ls -la 命令查看当前目录下是否生成了 .cursor 文件夹，并进一步查看其内容。

# 在项目根目录执行
ls -la .cursor/rules/

你应该能看到一系列 .mdc 文件，这表示规则已成功部署。

3.3 Cursor 客户端的配置与生效

部署文件只是第一步，接下来需要在 Cursor 客户端中启用它们。

  1. 打开 Cursor ，并打开你已经部署了规则的那个项目。
  2. 点击左下角的设置（齿轮）图标，或者通过 Cmd + , (Mac) / Ctrl + , (Windows/Linux) 打开设置。
  3. 在设置中，找到 “Rules” 部分。通常，Cursor 会自动扫描项目中的 .cursor/rules 目录并加载找到的规则。
  4. 你应该能看到一个规则列表，每个规则旁边有一个开关。确保你想应用的规则处于 开启（Enabled） 状态。

生效机制 ：一旦规则启用，当你使用 Cursor 的 AI 功能（如自动补全、Chat 对话生成代码、编辑指令等）时，这些规则就会作为上下文的一部分被送入 AI 模型，从而影响其输出。AI 会尝试遵循这些规则来生成或修改代码。

4. 规则文件深度解析与自定义

4.1 理解 .mdc 规则文件格式

.mdc 文件是 Cursor 自定义规则的载体，其内容结构可读性很强。我们打开一个规则文件来看看（内容为示例）：

# 规则名称：Prefer Early Return

## 描述
鼓励使用提前返回（Guard Clauses）来减少嵌套，提升代码可读性。

## 指令
当编写条件判断时，优先检查错误或边界条件，并在条件满足时立即返回。避免深层嵌套的 `if-else` 结构。

## 示例（不良实践）
```javascript
function processUser(user) {
  if (user) {
    if (user.isActive) {
      // 主要的业务逻辑...
      return result;
    } else {
      return { error: 'User inactive' };
    }
  } else {
    return { error: 'User not found' };
  }
}

示例（良好实践）

function processUser(user) {
  if (!user) {
    return { error: 'User not found' };
  }
  if (!user.isActive) {
    return { error: 'User inactive' };
  }

  // 主要的业务逻辑...
  return result;
}

作用域

  • javascript
  • typescript
  • python

一个典型的规则文件包含以下几个部分：
-   **# 标题**：规则的名称。
-   **## 描述**：简要说明规则的目的。
-   **## 指令**：给 AI 的核心提示，告诉它应该怎么做。这是规则的“灵魂”。
-   **## 示例**：通过“不良实践”和“良好实践”的对比，让 AI 更直观地理解要求。这是非常关键的部分。
-   **## 作用域**：指定该规则适用于哪些编程语言。这可以防止 Python 规则干扰到你的 JavaScript 代码。

### 4.2 如何根据项目需求自定义规则

开源规则集是一个绝佳的起点，但每个项目都有其独特性。自定义规则能让 Cursor 更贴合你的团队。

**步骤一：创建自定义规则文件**
在你的 `.cursor/rules` 目录下，新建一个 `.mdc` 文件，例如 `our-team-js-conventions.mdc`。

**步骤二：编写规则内容**
假设你的团队要求所有异步函数名必须以 `Async` 后缀结尾，以便于区分。你可以这样写：

```markdown
# 规则名称：Async Function Naming Convention

## 描述
所有异步函数必须在名称后添加 `Async` 后缀，以明确标识其异步特性。

## 指令
当定义或生成一个 `async` 函数时，其名称必须以 `Async` 结尾。这对于返回 Promise 的函数同样适用。

## 示例（不良实践）
```javascript
async function fetchData() { ... }
async function getUser() { ... }

示例（良好实践）

async function fetchDataAsync() { ... }
async function getUserAsync() { ... }

作用域

  • javascript
  • typescript

**步骤三：组合与优先级**
你可以创建多个规则文件。Cursor 会综合所有启用的规则。如果规则间有冲突（极少发生），更具体、描述更详细的规则通常影响力更大。你可以通过调整指令的清晰度和示例的针对性来微调。

### 4.3 规则集的维护与更新

1.  **更新开源规则**：如果 `DeGraciaMathieu/cursor-mdc-rules` 仓库更新了，你可以重新运行下载脚本。**注意**：这会覆盖 `.cursor/rules` 目录下所有同名的文件。如果你的自定义规则与开源规则同名，会被覆盖。建议将自定义规则命名为不同的、易于识别的文件名。
2.  **版本控制**：强烈建议将 `.cursor/rules` 目录纳入你的项目版本控制（如 Git）。这样，团队所有成员都能共享同一套规则，保证代码风格的一致性。你可以在 `.gitignore` 中忽略 `.cursor` 目录下的其他缓存或临时文件，但保留 `rules/`。
3.  **分环境规则**：对于大型项目，你甚至可以考虑为不同部分设置不同规则。例如，在 `backend/.cursor/rules` 和 `frontend/.cursor/rules` 分别放置针对后端（Python/Go）和前端的规则。Cursor 会从当前打开文件所在目录向上搜索最近的 `.cursor/rules` 目录。

## 5. 实战应用：与Cursor协作的效率飞跃

### 5.1 在Chat对话中应用规则

当你打开 Cursor 的 Chat 面板并输入指令时，例如：“`帮我写一个函数，验证用户邮箱格式并返回布尔值`”，启用的规则会自动生效。

**没有规则时**，AI 可能生成一个包含多层嵌套、变量名随意的函数。
**应用了“清晰命名”、“提前返回”、“单一职责”等规则后**，AI 更可能生成如下代码：
```javascript
/**
 * 验证邮箱格式是否符合基本规范。
 * @param {string} email - 待验证的邮箱字符串
 * @returns {boolean} - 格式有效返回 true，否则返回 false
 */
function isValidEmailFormat(email) {
  if (typeof email !== 'string' || email.trim() === '') {
    return false;
  }

  // 简单的正则验证，实际项目可能需要更复杂的规则
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email.trim());
}

你可以看到，函数名清晰，有 JSDoc 注释，先进行参数基础检查（Guard Clause），逻辑简洁，返回明确。

5.2 在编辑指令（Edit Command）中应用规则

这是威力巨大的功能。选中一段冗长的、嵌套很深的代码，按下 Cmd/Ctrl + K 打开编辑指令框，输入：“ 用提前返回的方式重构这段代码，提高可读性 ”。

AI 会根据“Prefer Early Return”规则，将你选中的代码块重构成扁平结构。这比手动重构快得多，而且能保证符合团队规范。

5.3 在自动补全和代码生成中应用规则

即使是在你日常打字时，规则也在默默工作。当你开始输入 async function fetch... ，AI 的自动补全建议可能会倾向于 fetchDataAsync 。当你在 if 语句里写条件时，它可能会提示你先写错误情况的返回。

6. 常见问题与排查技巧实录

6.1 规则未生效的排查步骤

  1. 检查路径 ：这是最常见的问题。绝对确保 .cursor/rules 目录位于你 当前打开的 Cursor 项目根目录 下。你可以在 Cursor 的文件资源管理器中查看顶部路径。
  2. 检查规则开关 ：打开 Cursor 设置 (Cmd/Ctrl + ,) 的 Rules 部分，确认目标规则已启用（Toggle 为蓝色）。
  3. 检查作用域 ：确认你正在编写的文件类型（如 .js , .py ）是否在规则的作用域（Scope）定义之内。
  4. 重启 Cursor ：有时更改规则后，重启 Cursor 客户端可以确保新规则被完全加载。
  5. 查看规则文件语法 ：确保你的 .mdc 文件是有效的 Markdown 格式，特别是代码块要用反引号正确包裹。

6.2 规则冲突或效果不理想

  1. 规则过于宽泛 ：如果一条规则指令太模糊，如“写出高质量的代码”，AI 可能无法准确执行。规则指令应具体、可操作，如“函数长度不超过20行”、“使用具名导出而非默认导出”。
  2. 示例不够典型 ：不良实践和良好实践的对比示例必须清晰、有代表性。模糊的示例会导致 AI 学习到错误模式。
  3. 调整指令权重 ：在指令中使用更强调的语言，如“必须”、“总是”、“禁止”，可以增强规则的约束力。相反，使用“建议”、“可以考虑”则约束力较弱。
  4. 分而治之 ：不要试图用一条规则解决所有问题。将大的编码规范拆分成多条单一职责的规则（如命名规则、格式规则、安全规则），效果更好，也便于管理。

6.3 性能与最佳实践

  1. 规则数量 ：并非越多越好。加载数十条规则可能会轻微影响 Cursor 的初始响应速度，因为所有规则内容都需要作为上下文发送给 AI。建议只启用对你当前项目真正重要的规则。
  2. 项目特定规则 ：对于公司内部或特定技术栈的项目，建立自己的规则仓库是值得的。你可以 fork 原项目，在其基础上增删改，形成适合自己团队的版本。
  3. 与 Linter/Formatter 配合 ：Cursor 规则主要指导 AI 的 生成逻辑 ，而像 ESLint、Prettier、Black 这类工具负责代码的 静态格式 。两者是互补关系。理想的工作流是：Cursor 根据规则生成结构良好、意图清晰的代码，然后由格式化工具统一代码风格。

在我个人的深度使用中，引入这套规则后，最直观的感受是与 Cursor 的沟通成本大幅降低。我不再需要频繁地在提示词中重复“请使用驼峰命名”、“请检查空值”、“函数不要太长”这些基本要求。AI 生成的代码初稿质量显著提高，审查时更多是关注业务逻辑是否正确，而非代码风格问题。这就像为你的 AI 助手进行了一次精准的“岗前培训”，让它真正理解了你的工作习惯和项目标准，从而成为更得力的合作伙伴。

# 代码规范
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

DeepSeek-V4 RAG 分块策略优化：512 vs 1024 token 的实测边界与工程取舍

avatar DeepSeek技术社区
cover

企业知识库问答中的权限迷宫：如何用 DeepSeek 实现文档级 ACL 下沉与安全召回

avatar DeepSeek技术社区
cover

RAG 文档预处理：为什么 90% 的失败案例源于切分策略不当

avatar DeepSeek技术社区