1. 项目概述当Cursor遇上MDC一场关于代码质量的“规则革命”如果你和我一样深度依赖Cursor这类AI编程助手来提升开发效率那你一定也经历过这样的时刻AI生成的代码片段功能上没问题但风格上却五花八门有的命名随意有的缩进混乱有的甚至引入了团队早已废弃的旧API。每次合并代码前都得花大量时间手动“格式化”和“规整”这感觉就像请了个天才厨师但他做完菜不收拾厨房留下一片狼藉。DeGraciaMathieu/cursor-mdc-rules这个项目就是为了解决这个痛点而生的。它本质上是一套为Cursor AI助手定制的、基于Markdown的代码生成规则集我习惯称之为“AI编程的交通规则”。简单来说这个项目让你能告诉Cursor“嘿伙计以后给我写代码时请遵守这些规则。”这些规则覆盖了从代码风格如命名约定、缩进、到最佳实践如避免特定函数、优先使用新语法、再到项目特定约定如文件组织、导入语句顺序的方方面面。它通过一种结构化的Markdown文档.mdc文件来承载这些规则Cursor在生成代码时会参考这些文档从而输出更符合你个人或团队预期的、高质量的代码。这不仅仅是格式化更是将开发经验、团队规范“注入”到AI的创作过程中让AI从“能写代码”进化到“会写好代码”。2. 核心设计理念为什么是MDC而不仅仅是提示词在深入细节前我们先聊聊为什么需要这样一个专门的规则集而不是简单地在每次对话时给Cursor写长篇的提示词Prompt。这里涉及到几个关键的设计考量也是这个项目的精髓所在。2.1 从临时指令到持久化规则每次在Chat界面输入“请用PascalCase命名类用camelCase命名变量使用4个空格缩进……”不仅效率低下而且容易遗漏。cursor-mdc-rules将规则持久化为文件一旦配置对后续所有相关的代码生成请求都持续生效。这实现了规范的“一次定义处处应用”将开发者从重复的规范提醒中解放出来。2.2 结构化与可维护性纯文本提示词在规则复杂后难以维护和更新。MDCMarkdown for Cursor格式利用Markdown的标题层级、列表、代码块等元素将规则分门别类地组织起来。例如你可以有## Naming Conventions、## React Specific Rules、## Project Structure等章节结构清晰易于增删改查。这种结构化的方式使得团队协作维护一套统一的编码规范成为可能。2.3 上下文感知与精准应用一个优秀的规则引擎需要知道“什么时候用什么规则”。cursor-mdc-rules支持通过文件路径匹配、语言标识等方式让规则只在特定的上下文中生效。例如*.ts文件应用TypeScript规则components/*目录下的文件应用React组件规范而server/*目录则应用后端Node.js规则。这种精准性避免了规则冲突和误用确保了建议的针对性。2.4 超越格式化的深度约束Prettier、ESLint等工具擅长处理代码格式和静态语法问题。cursor-mdc-rules的野心更大它旨在影响AI的代码“生成逻辑”本身。例如规则可以规定“在React函数组件中优先使用useState而非useReducer除非状态逻辑非常复杂”或者“禁止使用var一律使用const或let”。这是在代码被“写出来”之前就施加的约束引导AI做出符合最佳实践的设计决策而不仅仅是事后的样式修正。3. 规则文件解析与编写实战理解了“为什么”我们来看看“怎么做”。cursor-mdc-rules的核心就是一个或多个.mdc文件。它的语法直观而强大下面我们拆解其核心组成部分并附上我实战中总结的编写技巧。3.1 基础结构从全局到局部一个典型的.mdc文件通常遵循以下层级结构# 项目全局编码规范 本规则适用于所有前端TypeScript/React项目。 ## 通用规则 ### 命名约定 - **变量/函数**: 使用 camelCase。 - **类/接口/类型别名**: 使用 PascalCase。 - **常量**: 使用 UPPER_SNAKE_CASE。 - **布尔变量**: 应以 is, has, can, should 等开头如 isLoading。 ### 代码风格 - 缩进2个空格针对本项目4空格团队请自行修改。 - 字符串统一使用单引号。 - 行尾使用分号;。 - 最大行宽100个字符。 ## TypeScript 特定规则 ### 类型注解 - 总是显式定义函数返回类型除非返回值类型非常明显如 return true。 - 避免使用 any 类型。如果必须使用需添加 // eslint-disable-next-line typescript-eslint/no-explicit-any 注释并说明理由。 - 优先使用 interface 定义对象类型除非需要使用联合类型或元组。 ### 模块导入 - 导入顺序1. 第三方库react, lodash 2. 项目内部绝对路径模块/components 3. 相对路径模块./utils 4. 类型导入import type。 - 禁止使用通配符导入import * as。 ## React 特定规则 ### 组件定义 - 使用函数组件和React Hooks。 - 组件文件命名PascalCase.tsx。 - 默认导出组件本身。 - 使用 Props 接口定义组件属性。 ### Hooks 使用 - 自定义Hook必须以 use 开头。 - 确保Hook的调用总是在React组件的顶层且不在条件语句中。注意以上只是一个示例片段。实际文件中你可以在每个规则点下提供更详细的解释甚至代码示例。Cursor在生成代码时会“阅读”这些内容并尝试遵循。3.2 高级技巧条件规则与上下文过滤这才是cursor-mdc-rules真正强大的地方。你可以在规则前加上特定的“条件”来控制其生效范围。1. 基于文件路径的规则在规则标题后使用符号指定路径模式。## 样式文件规则 **/*.module.css - 使用 CSS Modules 语法。 - 类名使用 camelCase。 - 禁止使用 ID 选择器和元素选择器。 ## API 层规则 src/services/**/*.ts - 所有函数必须是 async。 - 使用统一的错误处理拦截器 apiClient。 - 响应数据必须进行类型断言。这条规则意味着只有当Cursor在处理.module.css文件或src/services目录下的.ts文件时才会应用对应的规则集。2. 基于编程语言的规则在规则标题后使用#符号指定语言。## Python 数据类规则 #python - 优先使用 dataclass 装饰器。 - 类型提示是必须的。 - 为 __post_init__ 方法添加文档字符串。 ## Shell 脚本安全规则 #shell - 在所有脚本开头添加 set -euo pipefail。 - 变量引用必须加双引号$variable。 - 使用 [[ ]] 进行条件测试。3. 组合使用你甚至可以组合路径和语言实现更精细的控制。## 配置文件规则 config/*.json #json - 保持缩进为2个空格。 - 最后的项后不要有逗号。 - 键名使用双引号。3.3 实操心得如何编写有效的规则编写规则不是一蹴而就的而是一个迭代过程。以下是我的几点心得从痛点开始而非面面俱到不要试图一开始就制定一本完整的编码规范。从当前AI生成代码中最让你头疼的1-2个问题开始。比如AI总是用let声明不改变的变量那就先加一条“优先使用const除非变量需要重新赋值”的规则。规则要具体、可执行避免“写出高质量的代码”这种模糊要求。取而代之的是“函数长度不超过30行”、“组件属性超过5个时需使用对象解构”等具体指令。提供正反示例对于复杂的规则在Markdown中用代码块提供“好”和“坏”的对比示例能极大帮助AI理解你的意图。### 数组遍历 #javascript **推荐** (使用 forEach 或 for...of): javascript items.forEach(item process(item));不推荐(使用传统for循环):for (let i 0; i items.length; i) { process(items[i]); }分而治之为不同的项目、不同的技术栈创建不同的.mdc文件。比如react-project.mdc、node-api.mdc、python-scripts.mdc。在Cursor中可以根据上下文切换激活的规则文件。规则是活的定期回顾规则。有些规则可能过于严格影响了AI的创造力有些新的最佳实践需要补充进去。把它当成一个活的文档来维护。4. 在Cursor中集成与使用工作流拥有规则文件后下一步就是让Cursor认识并运用它们。根据Cursor的版本和设置主要有以下两种方式。4.1 方式一项目级配置推荐这是最持久和共享友好的方式。在你的项目根目录下创建一个名为.cursorrules的目录注意前面有点然后将你的.mdc文件放入其中。Cursor在打开该项目时会自动加载该目录下的所有规则文件。工作流示例mkdir .cursorrules将你的frontend-rules.mdc和backend-rules.mdc复制到.cursorrules/目录下。重启Cursor或重新打开项目。现在当你在项目中请求AI生成或编辑代码时Cursor就会自动参考这些规则。优势规则成为项目的一部分任何克隆该仓库并使用Cursor的开发者都会自动应用同一套规范极大促进了团队代码风格统一。4.2 方式二对话中引用你也可以在单个Chat对话中通过指令临时加载某个规则文件。在Chat输入框中你可以使用特殊的指令来引用规则。例如你可以输入请参考 /.cursorrules/frontend-rules.mdc 中的规则为我生成一个用户登录的React组件。或者如果规则文件不在项目内你也可以直接粘贴部分关键规则到对话中根据以下规则生成代码 - 使用TypeScript函数显示返回类型。 - 组件使用 PascalCase 命名。 - 使用 const 声明变量。 ...其余规则适用场景快速试验某条新规则或在未配置项目级规则的情况下进行一次性协作。4.3 规则生效的观察与调试如何知道规则起作用了一个明显的迹象是AI生成的代码会直接符合你的约定。但有时AI可能“忽略”或“误解”某条规则。这时需要调试检查规则语法确保Markdown格式正确条件过滤器#书写无误。检查上下文匹配确认你正在编辑的文件路径或语言是否匹配规则中设定的条件。简化与测试如果一条复杂规则不生效尝试将其拆分成更简单、更直接的几条规则逐一测试。提供更明确的指令在Chat中除了依赖规则文件你也可以用自然语言强化“请严格遵守我们规则文件中关于禁止使用any类型的规定。”在我的经验中大约90%的规则都能被Cursor很好地理解和应用。对于剩下的10%通常通过优化规则表述更具体、提供示例就能解决。5. 高级应用场景与生态扩展cursor-mdc-rules的玩法远不止于定义代码风格。我们可以用它来固化一些更高级、更工程化的实践。5.1 场景一强制架构模式对于采用清晰架构如Clean Architecture或领域驱动设计DDD的项目可以用规则来约束代码的放置位置和依赖方向。## 清洁架构层规则 src/features/*/domain/* - 此目录下只能包含实体Entity、值对象Value Object和领域服务Domain Service的代码。 - 禁止导入来自 infrastructure、application 或 presentation 层的任何模块。 - 所有类都应该是纯粹的不依赖任何外部框架或库。 ## 用例规则 src/features/*/application/use-cases/* - 每个文件只导出一个 Execute 方法。 - 必须注入仓储Repository接口而非具体实现。 - 所有错误必须转换为统一的 UseCaseError 类型抛出。这样当你在domain目录下请求AI生成代码时它就不会意外地引入一个HTTP客户端库。5.2 场景二安全与合规性检查将安全编码规范写入规则让AI成为第一道防线。## 安全规则 #javascript - 禁止使用 eval() 函数。 - 处理用户输入时必须进行转义或使用参数化查询针对数据库操作。 - 在创建动态正则表达式时避免使用用户输入直接构造 RegExp 对象。 ## 隐私规则 **/*.ts - 禁止在日志中打印完整的个人身份信息PII如邮箱、手机号。应使用掩码如 us**example.com。 - 访问 localStorage 或 sessionStorage 前必须检查功能可用性if (typeof window ! undefined)。5.3 场景三团队知识库集成规则文件可以成为团队最佳实践的活文档。新成员 onboarding 时除了阅读文档直接使用配置好规则的Cursor能在编码过程中无意识地学习和应用这些实践。代码审查要点将常见的代码审查意见转化为规则如“提交前必须处理所有TODO注释”、“组件属性必须添加JSDoc/TSDoc注释”。性能模式“在渲染列表时必须为每个项提供稳定的key”、“对于大型状态考虑使用useMemo和useCallback”。测试规范“单元测试文件名必须以.spec.ts或.test.ts结尾”、“使用describe和it块测试描述必须清晰”。5.4 生态展望共享规则库DeGraciaMathieu/cursor-mdc-rules项目本身提供了一个起点。社区完全可以在此基础上发展出针对不同框架、不同场景的共享规则库。想象一下你可以像安装npm包一样引入一个“cursor-rules-react-ts-best-practices”包它包含了React TypeScript社区公认的大量最佳实践规则瞬间将你的AI助手武装到牙齿。6. 局限、挑战与最佳实践尽管强大但我们需要清醒地认识到它的局限并找到与之和谐共处的方式。6.1 当前局限性非强制性Cursor的规则是“指导性”而非“强制性”的。AI有时会出于逻辑或创意原因偏离规则。它不能完全替代ESLint、Prettier等静态检查工具后者是代码提交前的硬性关卡。规则冲突如果多条规则存在冲突例如一个规则说用双引号另一个说用单引号AI的行为可能不可预测。需要保持规则集内部的一致性。理解偏差AI对自然语言规则的理解可能不完全符合人类预期。过于复杂或模糊的规则可能导致生成奇怪的代码。上下文长度限制规则文件内容会占用AI模型的上下文窗口。一个非常庞大的规则文件可能会挤占用于理解具体代码任务的上下文空间影响生成质量。6.2 应对策略与最佳实践与现有工具链协同将cursor-mdc-rules视为开发流程的“左移”环节——在代码生成阶段就引入规范。同时务必在项目中配置Prettier格式化、ESLint/TypeScript编译器静态检查和HuskyGit钩子形成一个从生成到提交的质量保障链条。Cursor规则引导AI写出好代码。Prettier统一代码格式。ESLint检查代码质量和潜在错误。Git Hook阻止不符合规范的代码提交。规则优先级与简化优先级先定义影响代码正确性、安全性和可维护性的核心规则如禁止any、强制错误处理再定义代码风格规则如引号、缩进。简化保持规则文件简洁。将过于风格化、个人偏好强烈的规则交给Prettier处理。Cursor规则应聚焦于AI需要“理解”并“决策”的部分。迭代与反馈将规则文件纳入版本控制。当发现AI持续违反某条规则时不是简单地责怪AI而是审视规则表述是否清晰并像修复bug一样去改进规则文件。鼓励团队成员提交对规则文件的改进建议。分场景配置不要试图用一个庞大的.mdc文件覆盖所有。为不同的子项目、包或目录结构创建针对性的小规则文件通过.cursorrules目录进行组织这样上下文更精准效果也更好。7. 个人实战经验与避坑指南在近几个月的深度使用中我积累了一些实战技巧也踩过一些坑希望能帮你更快上手。心得一规则命名与组织我在.cursorrules目录下的结构通常是这样的.cursorrules/ ├── 0-global.mdc # 最通用的规则如命名、注释 ├── 1-typescript.mdc # TS特定规则 ├── 2-react.mdc # React特定规则 ├── 3-api.mdc # API调用相关规则 └── 4-project-specific.mdc # 本项目特有约定通过数字前缀控制加载顺序如果需要的话并且文件名清晰表达了范围。global.mdc总是被加载其他文件则根据我工作的上下文动态产生影响力通过和#条件。心得二善用“禁止”与“优先”规则的语言很重要。“禁止使用X”比“避免使用X”更明确。“优先使用Y除非Z情况”则提供了灵活的指导。例如差“考虑使用可选链操作符。”好“访问可能为null或undefined的对象属性时必须使用可选链操作符?.。”心得三提供“逃生舱口”对于某些确实有例外情况的规则可以在规则中说明例外。这能减少AI的困惑。### 错误处理 - 异步函数必须使用 try...catch 进行错误处理或让错误向上层冒泡。 - **例外**在顶层的入口函数如React组件的事件处理器中可以使用 .catch() 或进行UI级别的错误展示。踩过的坑规则过载初期我恨不得把所有ESLint规则都搬进去结果导致AI生成代码时变得“畏手畏脚”速度变慢且有时产出过于刻板的代码。后来我大幅精简只保留最关键、最能提升长期可维护性的规则。路径条件错误我曾写了一条规则 src/components/**/*却忘了在Windows系统下Cursor可能使用反斜杠路径。使用**/*这种跨平台模式更安全。忽略AI的创造力有时AI会提出比我的规则更优雅的解决方案。我开始学会区分“必须遵守的规范”和“可以讨论的最佳实践”。对于后者我会和AI进行对话如果它的方案确实更好我会反过来更新我的规则文件。一个具体的成功案例 在我的一个Next.js项目中AI总是喜欢在API路由里写一堆内联的类型定义导致文件冗长。我添加了这样一条规则## API 响应类型 src/pages/api/**/*.ts - 为API响应定义统一的类型如 type ApiResponseT { success: boolean; data?: T; error?: string }。 - 在文件顶部或专门的 types.ts 文件中定义具体的响应数据类型如 type UserResponse {...}。 - 在路由处理函数中使用这些定义好的类型。之后AI生成的API路由代码立刻变得清晰多了类型定义被提取到合理的位置大大提升了代码的可读性和可维护性。DeGraciaMathieu/cursor-mdc-rules这个项目其价值不在于它提供了多少现成的规则而在于它提供了一种范式——一种将人类开发者的经验和智慧系统化地注入AI协作流程的范式。它让AI编程助手从一个需要时时叮嘱的“实习生”逐渐成长为一个理解并认同团队文化的“资深伙伴”。开始创建你的.mdc文件吧从一两条最让你难受的规则开始你会发现与Cursor的协作将变得前所未有的顺畅和高效。这不仅仅是关于代码格式更是关于如何塑造我们未来的开发工具链。