1. 项目概述为你的 Cursor AI 注入“团队灵魂”如果你是一名 Web 开发者尤其是深耕于 PHP、Drupal 或现代前端技术栈的工程师那么你很可能已经体验过 Cursor AI 带来的生产力飞跃。它能帮你生成代码片段、重构函数、甚至编写测试。但你是否也遇到过这样的困扰AI 生成的代码风格与团队规范不符或者它给出的安全建议不够全面又或者它总是忘记为你的 Drupal 模块补上合适的文档注释这些问题本质上是因为 AI 助手缺乏对特定项目上下文和团队约定的深度理解。abderrahimghazali/cursor-rules这个项目就是为了解决这个痛点而生的。它不是另一个代码库而是一套精心设计的“规则集”你可以将其理解为 Cursor AI 的“行为准则”或“团队规范手册”。通过将这些.mdc格式的规则文件安装到你的项目根目录下的.cursor/rules文件夹中你就在无形中为你的 AI 结对编程伙伴进行了一次“岗前培训”。这套规则的核心价值在于标准化和自动化。它覆盖了从代码风格、Git 提交规范、测试要求到针对 PHP/Drupal、JavaScript、React、Vue 等技术的具体最佳实践乃至基于 OWASP Top 10 的深度安全审查规则。想象一下当你让 Cursor 创建一个新的 React 组件时它会自动遵循你预设的组件模式、导入规范和 PropTypes 定义当你编写一个 Drupal 表单 API 时AI 会提醒你进行适当的 CSRF 令牌保护和输入验证。这相当于将团队里最资深的架构师、最严谨的安全专家和最注重细节的 Code Reviewer 的经验固化成了随时待命的 AI 提示。2. 核心规则集深度解析与选型指南面对项目中超过 50 个规则文件直接全部安装可能并非最佳选择。理解其分类和设计哲学能帮助你进行精准的“按需装配”让 AI 的辅助既强大又高效避免规则冲突或过度提示带来的干扰。2.1 规则架构与设计哲学这套规则集采用了分层和模块化的设计思想主要分为四大板块核心规则、Web 开发规则、Python 规则以及开发流程规则。其设计遵循了几个关键原则上下文感知每条规则都通过文件路径模式如**/*.php,**/*.jsx限定了其生效范围确保 PHP 的规则不会干扰到 JavaScript 文件前端构建优化建议只出现在webpack.config.js或vite.config.ts附近。正向引导与即时纠偏规则不仅仅是“禁止”某些操作更多是“建议”更好的做法。例如当它检测到你在写setTimeout时可能会提示“考虑使用clearTimeout清理以避免内存泄漏”并提供代码示例。安全左移将安全审查嵌入到编码阶段是这套规则最亮眼的特点之一。针对 OWASP Top 10 的每一条都有对应的 Drupal、JavaScript 和 Python 规则。这意味着在你写出$_GET[‘id’]并直接拼接到 SQL 语句中的那一刻AI 就会高亮警告并建议使用参数化查询或 Drupal 的数据库 API。2.2 关键规则模块详解2.2.1 核心规则奠定协作基础这是无论什么技术栈都建议安装的基石。git-commit-standards.mdc: 强制使用约定式提交Conventional Commits。当你执行 Git 提交时AI 会引导你写出feat:,fix:,docs:这样结构清晰的消息并自动关联变更范围。这对于生成 CHANGELOG 和自动化版本管理至关重要。testing-guidelines.mdc: 确保测试与生产代码分离并鼓励为新增功能编写测试。它会识别何时你在修改核心逻辑却未更新相应测试文件。improve-cursorrules-efficiency.mdc: 这条规则有点“元”它专门优化你与 Cursor 本身的交互识别低效或模糊的提问方式并建议更精确的指令从而提升你使用 AI 的效率。2.2.2 Web 开发规则你的全栈技术顾问这是规则集的精华所在针对性极强。前端专项javascript-standards.mdc/react-patterns.mdc/vue-best-practices.mdc: 分别提供了 ES6 规范、React 函数式组件与 Hooks 最佳实践、Vue 3 组合式 API 和script setup的使用指南。例如在 React 中它会倾向于推荐使用useState,useEffect而非过时的 Class 组件。accessibility-standards.mdc: 强调 WCAG 可访问性。当你在写 JSX 或 HTML 时如果图片缺少alt文本或按钮没有明确的aria-labelAI 会立即提示。build-optimization.mdc: 针对 Webpack/Vite 配置提供代码分割、Tree Shaking、缓存策略等优化建议帮助你构建出性能更优的包。后端与 Drupal 专项php-drupal-best-practices.mdc: 这是 Drupal 开发者的“圣经”。它强制要求使用 Drupal API如\Drupal::service()、遵循 Drupal 编码标准如函数命名、注释格式、以及正确使用插件系统、实体 API 和表单 API。drupal-database-standards.mdc: 任何直接写 SQL 的操作都会触发这条规则强烈建议你使用 Drupal 的数据库抽象层db_select,db_insert等或 Entity Query以确保查询的安全性和可移植性。安全规则矩阵 这是将 OWASP Top 10 具体到代码层面的典范。以A03: Injection注入为例drupal-injection.mdc: 会检查所有用户输入点如\Drupal::request()-query-get()是否在被用于数据库查询、系统命令或反序列化前经过了正确的过滤或参数化处理。javascript-injection.mdc: 重点关注 DOM 型 XSS。当你使用innerHTML或document.write()时它会警告你优先考虑textContent或确保对动态内容进行正确的转义。python-injection.mdc: 对 Python 中的 SQL 拼接、命令执行os.system,subprocess和模板渲染如 Jinja2进行安全警示。DevOps 与基础设施docker-compose-standards.mdc/lagoon-yml-standards.mdc: 如果你使用 Docker 和 Lagoon一个基于 Kubernetes 的 Drupal 部署平台这些规则能确保你的服务定义、环境变量和健康检查配置符合最佳实践避免在本地或云端部署时踩坑。2.3 如何根据项目选型纯前端项目 (React/Vue)安装核心规则 前端专项规则 javascript-*安全规则。Drupal 后端项目安装核心规则 php-drupal-*规则 drupal-*安全规则 devops规则如果使用 Docker/Lagoon。全栈项目安装核心规则 所有相关的 Web 开发规则。可以利用标签系统进行精细筛选。Python 项目安装核心规则 python-*规则。团队通用基线即使项目技术栈不同为所有仓库统一安装核心规则和git-commit-standards.mdc能极大提升团队协作的一致性。实操心得不要一次性启用所有规则。建议从一个小的子集开始如核心规则你主要技术的规则在真实编码中观察 AI 的提示是否准确、有用。如果某些规则频繁产生“噪音”例如在一个不关心特定代码风格的历史项目中可以暂时禁用或调整它。规则是为你服务的工具而非束缚。3. 安装、配置与深度定制实操官方提供了便捷的安装脚本但为了在生产环境中稳定、可控地使用我们需要理解其背后的机制并进行适当的定制。3.1 安装流程详解与避坑最推荐的交互式安装命令是curl -s https://raw.githubusercontent.com/abderrahimghazali/cursor-rules/master/install.php -o install.php php install.php运行后脚本会询问你是否安装.cursorignore文件。强烈建议选择“是”。这个文件会忽略node_modules,vendor,*.log等目录和文件能显著提升 Cursor 的文件索引和 AI 响应速度避免无关的第三方代码污染上下文。关键参数解析--tags “language:php category:security”: 这是最强大的功能之一。通过标签过滤你可以仅安装 PHP 相关的安全规则。所有规则都按language:,framework:,category:,standard:等维度打标具体标签定义参考项目内的TAG_STANDARDS.md文件。--destinationcustom/path: 你可以将规则安装到全局目录如~/.cursor/rules/这样所有项目都能共享。但更推荐项目级安装因为不同项目的规范可能不同。--debug: 如果安装失败或未按预期下载规则使用此参数查看详细过程通常能发现网络或权限问题。常见安装问题排查只有核心规则被安装这通常发生在使用curl … | php管道命令且网络不稳定时。安装脚本需要从 GitHub 下载规则文件管道命令的非交互模式在遇到网络错误时可能静默失败。解决方案使用两行命令的交互式安装或确保网络通畅后重试。PHP 环境问题确保你的 PHP 版本在 7.4 以上且启用了curl和openssl扩展。在 Windows 上如果未将 PHP 加入系统 PATH可能需要使用完整路径如C:\php\php.exe install.php。企业代理限制如果处在公司内网可能需要为 PHP 配置代理。可以尝试先手动下载install.php文件然后运行php -d http_proxyhttp://your-proxy:port install.php。3.2 规则的工作原理与生效机制Cursor AI 在分析你的项目时会读取.cursor/rules目录下的所有.mdc文件。.mdc文件本质是一种结构化的提示词Prompt模板它通常包含When (触发条件)通过文件路径模式glob patterns定义规则在哪些文件上生效。Context (上下文)提供相关的代码片段、框架知识作为背景。Instruction (指令)核心部分告诉 AI 应该做什么、避免什么、如何检查。Example (示例)给出正面和反面的代码例子让 AI 更好地理解意图。例如一条简单的代码风格规则可能这样写When: editing **/*.js files Context: We use ES6 and prefer const over let. Instruction: When declaring variables that wont be reassigned, use const instead of let. Only use let if the variable needs to be reassigned later. Example: // Bad let userName ‘John’; // Good const userName ‘John’;当你在.js文件中将const改为let时Cursor 就可能弹出提示建议改回去。3.3 高级定制打造属于团队的规则官方规则集是一个绝佳的起点但每个团队都有独特的“方言”和规范。定制化是发挥其最大威力的关键。步骤一复制并修改现有规则找到最接近你需求的官方规则文件复制一份到你的.cursor/rules目录并重命名例如my-company-js-standards.mdc。然后你可以修改When条件限定到你们公司的特定项目路径。在Instruction部分加入你们内部的 API 调用规范、特定的工具库使用方式等。在Example部分替换成你们项目中的真实代码片段。步骤二创建全新的团队专属规则假设你们团队规定所有 API 响应必须包裹在一个标准的ResponseWrapper对象里。你可以创建api-response-wrapper.mdcWhen: editing **/api/**/*.ts files or **/services/**/*.js files Context: All API response data must be wrapped in a standard format for consistent client-side handling. Instruction: When writing functions that return data to the client, ensure the response is wrapped in the standard ResponseWrapper object with success, data, message, and code fields. Do not return raw data or inconsistent structures. Example: // Bad - returning raw data export async function getUser(id) { const user await db.user.findUnique({ where: { id } }); return user; // Inconsistent, sometimes might be null } // Good - using standard wrapper export async function getUser(id) { try { const user await db.user.findUnique({ where: { id } }); if (!user) { return { success: false, data: null, message: ‘User not found’, code: 404 }; } return { success: true, data: user, message: ‘’, code: 200 }; } catch (error) { return { success: false, data: null, message: error.message, code: 500 }; } }步骤三管理规则优先级与冲突如果多个规则对同一段代码提出了不同建议可能会造成困惑。目前Cursor 的规则引擎按文件加载顺序或某种内部权重处理。一个实用的方法是保持规则的高度特异性。用更精确的文件路径来限定规则范围减少重叠。例如将全局的 JavaScript 规则放宽而为**/components/**/*.jsx创建更严格的 React 组件规则。注意事项自定义规则后务必在团队内进行同步和评审。可以将这些自定义的.mdc文件放入团队的一个内部 Git 仓库并编写一个简单的安装脚本让新成员一键获取。避免每个人手动复制粘贴导致规则版本不一致。4. 实战场景从零开始用规则驱动 Drupal 模块开发让我们通过一个完整的场景看看这套规则如何在实际的 Drupal 模块开发中发挥作用。假设我们要创建一个名为 “Event Logger” 的简单模块用于记录特定内容类型被查看的事件。4.1 初始化与规则引导安装好php-drupal-best-practices.mdc和git-commit-standards.mdc等规则后我们开始创建模块。创建模块结构当我们在终端输入mkdir -p modules/custom/event_logger时Cursor 可能不会干预。但当我们创建event_logger.info.yml文件时AI 会基于规则提示我们填写完整的元数据name: ‘Event Logger’ type: module description: ‘Logs views of specific content types.’ core_version_requirement: ^9 || ^10 package: ‘Custom’ # AI 可能会提示Consider adding configure key if your module has a configuration form.编写第一个 Hook 实现我们创建event_logger.module文件并开始输入function event_logger_。此时AI 会基于 Drupal 编码标准自动补全为function event_logger_page_attachments_alter(array $attachments) {并提示“Remember to add proper docblock comments.” 当我们按下回车它甚至可能自动生成一个注释模板/** * Implements hook_page_attachments_alter(). */ function event_logger_page_attachments_alter(array $attachments) { // AI 提示Use dependency injection if you need services. For simple hooks, this is fine. }4.2 安全规则介入防止漏洞现在我们需要在hook_entity_view中记录日志。我们开始编写function event_logger_entity_view(array $build, EntityInterface $entity, DisplayPluginBase $display, $view_mode) { if ($entity-bundle() ‘article’) { $uid \Drupal::currentUser()-id(); $message “User $uid viewed article {$entity-id()}”; // 计划写入数据库 } }就在我们准备写\Drupal::database()-insert(‘event_log’)-fields([…])-execute();时drupal-injection.mdc和security-practices.mdc规则被触发了。AI 会高亮$uid和$entity-id()并给出警告“Potential Security Concern: Directly embedding user or entity IDs into a string for logging could be acceptable, but ensure the log destination is secure and not exposed to users. For database operations, always use proper query placeholders to prevent SQL injection, even if the data seems safe.”同时php-drupal-best-practices.mdc会提示“Consider using the LoggerChannelFactory service for standardized logging instead of direct database writes.” 并给出代码示例// 在模块文件中注入服务 use Drupal\Core\Logger\LoggerChannelFactoryInterface; // … 在 hook_entity_view 中 $logger \Drupal::service(‘logger.factory’)-get(‘event_logger’); $logger-info(‘User uid viewed article nid’, [‘uid’ $uid, ‘nid’ $entity-id()]);这不仅避免了潜在的安全风险还引导我们使用了更符合 Drupal 范式的日志系统。4.3 提交代码与规范检查开发完成后我们执行git add .和git commit。此时git-commit-standards.mdc规则开始工作。如果我们直接输入git commit -m “added logging function”Cursor 会在编辑器中弹出提示建议我们使用约定式提交格式并可能提供一个模板feat(event_logger): add entity view logging for articles - Implements hook_entity_view to track article views - Uses LoggerChannelFactory for secure and standardized logging - Adds basic configuration schema for future settings Refs: #123它提醒我们区分feat、fix、docs等类型并清晰描述变更内容。4.4 创建测试与文档当我们创建tests/src/Functional/EventLoggerTest.php文件时testing-guidelines.mdc规则被激活。它会引导我们继承正确的测试基类如BrowserTestBase并建议编写测试方法来验证日志是否在查看文章时被正确记录。同时readme-maintenance-standards.mdc会提醒我们更新README.md文件描述模块的新功能。5. 效能评估、常见问题与进阶技巧5.1 规则效能评估与优化引入规则后如何判断它是否真的提升了效率量化指标代码审查往返次数记录在引入规则前后一个功能从提交到通过 Code Review 所需的修改次数。理想情况下因基础规范如命名、安全问题导致的返工会减少。常见缺陷密度统计在测试或预发环境中发现的、本可以由规则拦截的缺陷如 SQL 注入风险点、未处理的异步错误数量是否下降。AI 交互效率观察你向 Cursor 发出的指令是否更精准、得到的代码是否更符合预期减少了“重写”或“调整”的提示次数。主观感受团队新成员是否更快地写出了符合规范的代码在处理不熟悉的技术栈如为 Python 项目添加安全特性时是否感觉更有信心、更有方向如果感觉规则带来了干扰例如在快速原型阶段提示过多可以临时禁用将某个规则的.mdc文件暂时移出.cursor/rules目录。调整严格度编辑规则文件将某些Instruction从强制的“必须”改为建议的“考虑”。使用.cursorignore将某些频繁触发但不重要的文件或目录如自动生成的配置文件加入忽略列表。5.2 常见问题与解决方案速查表问题现象可能原因解决方案Cursor 没有任何规则提示1. 规则未正确安装到.cursor/rules目录。2. Cursor 未加载项目规则检查设置。3. 当前文件类型不在任何规则的When条件内。1. 检查.cursor/rules目录下是否有.mdc文件。2. 重启 Cursor 或重新打开项目。3. 检查规则文件的路径匹配模式。规则提示不准确或错误1. 规则指令过于宽泛或存在歧义。2. 项目上下文特殊规则不适用。1. 定位具体规则文件细化其When条件或Instruction。2. 考虑禁用或修改该规则或为其添加例外条件。AI 响应变慢1. 启用了过多规则且作用在大型文件上。2..cursorignore未配置导致 AI 索引了node_modules等巨型目录。1. 按需安装规则禁用对大型文件如 minified 的.js生效的规则。2. 确保.cursorignore文件存在并正确配置。规则之间发生冲突两条规则对同一段代码给出了相反的建议。检查两条规则的触发条件通过更精确的文件路径限定其范围。通常更具体的规则应覆盖更通用的规则。自定义规则不生效1. 文件格式或语法错误。2. 文件名不是.mdc后缀。3. 规则未放置在正确的子目录或 Cursor 未识别。1. 检查.mdc文件语法确保是有效的 Markdown/文本。2. 确保文件名以.mdc结尾。3. 将其放在.cursor/rules/下或参考官方规则的结构建立子目录。5.3 进阶技巧构建团队规则知识库规则版本化将你的.cursor/rules目录纳入 Git 仓库管理。这样规则的更新和迭代就像代码一样可以进行版本控制、Code Review 和回滚。与 CI/CD 集成虽然 Cursor 规则主要在 IDE 中运行但其精神可以延伸到 CI。例如你可以编写一个简单的脚本检查项目中的.cursor/rules目录是否包含最新的安全规则集将其作为 CI 流水线的一个检查点。规则研讨会定期如每季度组织团队会议回顾规则的有效性。哪些规则帮助最大哪些成了摆设有没有新的常见错误需要新增规则来防范这能将规则集演变成活的、集体智慧的产物。跨编辑器兼容性思考虽然规则是为 Cursor 设计的.mdc格式但其核心——结构化的编码约定、安全清单、最佳实践——是通用的。你可以考虑将其中关键条款特别是安全部分提取出来转化为 ESLint 规则、PHPStan 配置或 SonarQube 质量门禁实现从开发到集成的全流程守护。最终cursor-rules项目的精髓不在于那几十个文件而在于它倡导的一种工作流将团队的最佳实践和血泪教训转化为可执行、可传承的自动化检查点。它让 AI 不再是那个偶尔会“胡说八道”的聪明助手而是成为了一个深刻理解你项目脉络、时刻守护代码质量的资深搭档。开始安装并定制你的第一套规则你会发现与 AI 协作编程的体验从此大不相同。