1. 项目概述：一个为 Cursor 编辑器量身定制的规则集

如果你和我一样，日常重度依赖 Cursor 这款 AI 驱动的代码编辑器，那你一定对它的“规则”（Rules）功能又爱又恨。爱的是，它能通过预设的指令，让 AI 助手（无论是 Claude 还是 GPT）在生成代码、重构代码时，遵循我们特定的编码风格、项目规范或安全要求，极大地提升了开发的一致性和效率。恨的是，手动编写和维护一套全面、有效的规则，既繁琐又容易遗漏，尤其是在多项目、多技术栈的环境下。

这就是 Kabi10/cursor-rules 这个开源项目诞生的背景。它不是一个简单的配置文件，而是一个经过精心设计和实战检验的规则集合，旨在为 Cursor 用户提供一套“开箱即用”的 AI 编码规范。你可以把它理解为一个“超级预设”，它封装了作者在大量实际开发场景中总结出的最佳实践、安全守则和效率技巧。直接导入这个规则集，就相当于为你的 Cursor 配备了一位经验丰富的“结对编程”导师，它能确保 AI 生成的代码不仅功能正确，而且风格统一、安全可靠、易于维护。

这个项目解决的核心痛点非常明确： 降低 AI 辅助编码的“心智负担”和“返工成本” 。在没有规则约束的情况下，AI 生成的代码可能风格各异，可能引入不安全的代码模式，也可能忽略项目的特定目录结构约定。 cursor-rules 通过一套预定义的规则，将这些不确定性降到最低，让开发者能更专注于业务逻辑本身，而不是反复纠正 AI 的格式或安全问题。

2. 规则集的核心设计哲学与架构拆解

2.1 从“约束”到“赋能”：规则的设计理念

初看 cursor-rules ，你可能会觉得它是一堆限制 AI 的条条框框。但深入使用后你会发现，它的设计哲学并非“限制”，而是“赋能”。好的规则不是扼杀 AI 的创造性，而是引导它在一个安全、高效、符合团队习惯的轨道上运行。

这个项目的规则设计遵循了几个关键原则：

1. 一致性优先 ：确保 AI 在整个项目生命周期中，对代码风格（如命名规范、缩进、引号使用）、文件组织方式（如组件存放位置、工具函数目录）的输出保持绝对一致。这避免了不同开发者或同一开发者在不同时间点，因 AI 的“自由发挥”而导致代码库风格混乱。
2. 安全兜底 ：将常见的安全反模式（如直接在代码中硬编码密钥、使用不安全的随机数生成器、存在 SQL 注入风险的字符串拼接）编写成否定性规则，主动拦截 AI 生成这类代码。这是一种“预防优于治疗”的思路，在代码诞生的源头就堵住漏洞。
3. 上下文感知 ：规则不是僵化的。项目中的规则会根据当前编辑的文件类型（ .js , .ts , .py , .vue 等）和项目结构（如是否检测到 package.json 、 requirements.txt ）动态调整其严格程度和建议内容。这使得规则集具备了一定的“智能”，而非一刀切。
4. 可读性与维护性 ：规则本身鼓励 AI 生成具有清晰注释、合理抽象和模块化的代码。它不仅仅关注“代码对不对”，更关注“代码好不好懂，好不好改”。

2.2 规则集的模块化架构

cursor-rules 并非一个单一的巨大文件，而是采用了模块化的组织方式，这体现了其良好的可维护性和可扩展性。通常，它的目录结构会类似于以下形式：

cursor-rules/
├── .cursor/
│   ├── rules/
│   │   ├── general.md          # 通用规则，适用于所有项目
│   │   ├── security.md         # 安全相关规则
│   │   ├── javascript.md       # JavaScript/TypeScript 特定规则
│   │   ├── python.md           # Python 特定规则
│   │   ├── vue.md              # Vue.js 特定规则
│   │   └── ...                 # 其他技术栈规则
│   └── rules.mdc               # 主规则文件，用于导入和组合其他规则
├── README.md
└── ... (其他项目文档)

这种架构的好处显而易见：

• 按需加载 ：你可以只启用你当前项目所需的技术栈规则，避免无关规则对 AI 造成干扰。
• 易于更新 ：当 JavaScript 的最佳实践更新时，你只需要修改 javascript.md ，而不会影响 Python 的规则。
• 便于协作 ：团队可以共同维护某个技术栈的规则文件，形成团队知识库。

主规则文件 rules.mdc 是这个架构的核心。它通常使用 Cursor 支持的指令（如 @include ）来引用其他规则文件。一个典型的 rules.mdc 内容可能如下：

# 项目 AI 编码规则

@include .cursor/rules/general.md
@include .cursor/rules/security.md

<!-- 根据项目类型动态包含 -->
@if(fileExists('package.json'))
@include .cursor/rules/javascript.md
@endif

@if(fileExists('requirements.txt'))
@include .cursor/rules/python.md
@endif

<!-- 自定义项目特定规则 -->
- 本项目所有 API 请求必须使用 `src/utils/request.js` 中封装的 `httpClient`。
- 所有组件必须存放在 `src/components/` 目录下，并按功能模块分子目录。

这种设计使得规则集既能提供强大的基础能力，又能灵活地适配不同项目的个性化需求。

3. 核心规则解析与实操要点

3.1 通用规则：奠定高质量代码的基石

通用规则是每个项目都应该具备的底层规范。 cursor-rules 中的通用规则通常涵盖以下几个方面，我们结合实例来看：

1. 代码风格与格式化： 规则会明确要求 AI 使用特定的缩进（如 2 个空格）、引号（单引号 ' 还是双引号 " ）、行尾分号等。例如：

规则示例 ：“生成 JavaScript/TypeScript 代码时，使用 2 个空格进行缩进，使用单引号 ' 定义字符串，语句末尾不加分号（除非必要）。”

为什么这么规定？ 统一的格式是代码可读性的基础。虽然 Prettier 或 Black 等工具可以事后格式化，但让 AI 在生成时就遵循规范，能减少格式化工具的“纠正”工作，并使生成的代码片段在聊天上下文或临时文件中也保持美观。

2. 命名约定： 强制推行一套命名规范，如变量和函数使用 camelCase ，类名使用 PascalCase ，常量使用 UPPER_SNAKE_CASE 。

规则示例 ：“函数名和变量名必须使用 camelCase 。类名、接口名、类型别名必须使用 PascalCase 。布尔变量或函数应以 is 、 has 、 can 等开头，如 isLoading 。”

实操心得 ：这条规则极大地提升了代码的“自解释性”。当你要求 AI “创建一个检查用户权限的函数”时，它会直接生成 canUserEditPost(userId, postId) 这样的函数名，而不是 checkPermission 之类模糊的名字。

3. 注释与文档： 要求 AI 为复杂的函数、类或算法添加清晰的 JSDoc/TSDoc 或 Python Docstring 风格注释。

规则示例 ：“所有导出（export）的函数、类和模块，必须包含完整的 JSDoc 注释，至少包括 @description 、 @param 和 @return 。”

注意事项 ：规则应平衡注释的完整性。避免要求 AI 为每个简单的 getter 或 setter 都写冗长的注释，这会导致信息噪音。好的规则会强调“为什么”（Why）和“边界条件”（Edge Cases），而不是重复“做什么”（What）。

3.2 安全规则：将隐患扼杀在提示词中

这是 cursor-rules 最具价值的模块之一。它直接将安全编码规范植入 AI 的“思维”过程。

1. 密钥与敏感信息： 最经典的规则就是禁止硬编码。AI 非常容易在示例代码中写出 const apiKey = 'sk-xxxx1234'; 。

规则示例 ：“绝对禁止在代码中硬编码任何密钥、密码、令牌或敏感配置。必须从环境变量（如 process.env.API_KEY ）或配置文件中读取。如果生成示例，请使用占位符如 'YOUR_API_KEY_HERE' 并明确提示用户需要替换。”

2. SQL 与 NoSQL 注入防护： 对于数据库操作，规则会强制要求使用参数化查询或 ORM 的安全方法。

规则示例 ：“进行数据库查询时，禁止使用字符串拼接方式插入用户输入。必须使用参数化查询（如 ? 占位符、 $1 ）或 ORM（如 Prisma、Sequelize）提供的安全查询方法。”

3. 依赖安全： 提醒 AI 注意依赖版本的安全性问题。

规则示例 ：“当建议安装 npm 包或 pip 包时，应优先建议已知的、维护良好的库。对于存在已知严重安全漏洞（CVE）的包版本，应主动警告并建议升级到安全版本。”

踩过的坑 ：我曾遇到过 AI 为一个快速原型建议使用一个已知存在原型污染漏洞的旧版本 lodash 。在集成这条规则后，AI 现在会主动说：“建议使用 lodash@^4.17.21 或更高版本，以避免 CVE-2021-23337 等漏洞。”

3.3 技术栈特定规则：深入框架细节

这部分规则展现了 cursor-rules 的深度。它不仅仅是语法检查，更是框架最佳实践的传递。

以 Vue.js 规则为例：

• 组件结构 ：要求单文件组件（ .vue ）按照 <template> -> <script> -> <style> 的顺序组织， <script> 部分使用 Composition API ( setup ) 语法。
• 状态管理 ：规定何时使用组件本地状态 ( ref )，何时使用 Pinia 全局状态。
• Props 定义 ：强制使用 TypeScript 的 defineProps 并声明详细类型，禁止使用运行时 props 数组声明。
• 样式规范 ：建议使用 scoped CSS 或 CSS Modules，并推荐像 Tailwind CSS 这样的工具。

规则示例（Vue） ：“在 .vue 文件中，使用 <script setup lang=“ts”> 语法。组件的 Props 必须使用 defineProps<{…}>() 进行类型化定义。样式部分默认添加 scoped 属性。”

为什么有效？ 当你在 Vue 项目中输入“创建一个显示用户列表的组件”时，AI 会直接生成一个符合你项目所有约定的、类型安全、结构清晰的 .vue 文件，而不是一个需要你大量重构的“通用”代码片段。这节省了大量对齐和修改的时间。

4. 如何将 cursor-rules 集成到你的工作流

4.1 基础安装与配置

集成 cursor-rules 非常简单，本质上就是将其规则文件复制到你项目的 .cursor 目录下。

步骤 1：获取规则集 你可以直接克隆仓库，或者更推荐的方式是，将其作为 Git Submodule 添加到你的项目中，便于同步更新。

# 在你的项目根目录下
git submodule add https://github.com/Kabi10/cursor-rules.git .cursor/rules-template

步骤 2：链接规则 进入 .cursor 目录（如果没有则创建），创建一个 rules.mdc 文件。这个文件是你的规则入口。你可以直接复制模板项目的主规则文件，或根据自己需求编写。

cd your-project
mkdir -p .cursor
cd .cursor
# 将模板中的主规则复制过来，或创建自己的
cp ../.cursor/rules-template/.cursor/rules.mdc ./rules.mdc

步骤 3：个性化定制 打开 rules.mdc ，根据你的项目情况编辑。最关键的是 @include 部分，确保引用的路径正确，并注释掉你不需要的技术栈规则。然后，在文件末尾添加你项目的特殊规则。

# My Project Rules
@include .cursor/rules-template/.cursor/rules/general.md
@include .cursor/rules-template/.cursor/rules/security.md

<!-- 我们是一个 React + TypeScript 项目 -->
@if(fileExists('tsconfig.json'))
@include .cursor/rules-template/.cursor/rules/javascript.md
<!-- 可以在这里或单独的 react.md 中覆盖/补充 React 特定规则 -->
- 使用 Functional Components with Hooks。
- 状态管理优先使用 `useState` 和 Context，复杂场景再考虑 Zustand。
@endif

<!-- 项目特定规则 -->
- 所有对后端 API 的调用必须通过 `src/libs/api-client.ts` 中的封装函数。
- 错误处理必须使用项目约定的 `ErrorBoundary` 组件和 `toast` 提示。

步骤 4：验证与生效 重启 Cursor（或重新加载项目），打开命令面板（Cmd/Ctrl + K），输入 /rules ，你应该能看到你定义的规则列表。在聊天或编辑器中，AI 的行为就会受到这些规则的约束。

4.2 高级用法：创建动态与上下文感知规则

Cursor 的规则语法支持简单的条件判断，这让我们可以创建非常智能的规则。

场景 1：根据文件路径应用不同规则 假设你的项目有 src/client/ 和 src/server/ 目录，对两者的代码要求不同。

@if(filePathMatches('src/server/'))
- 这里是后端代码，必须包含详细的错误日志记录（使用 `logger` 模块）。
- 所有数据库模型定义必须放在 `src/server/models/` 目录下。
@endif

@if(filePathMatches('src/client/'))
- 这里是前端代码，所有组件必须使用 `memo` 或 `useMemo` 进行性能优化考量。
- 禁止直接操作 DOM，必须使用 React 的 refs。
@endif

场景 2：集成项目级约定 你可以让规则读取项目的配置文件，如 package.json 中的 scripts ，或者 eslintrc 中的规则，让 AI 的建议与你的工具链保持一致。

<!-- 提示 AI 我们使用的代码质量工具 -->
- 本项目已配置 ESLint 和 Prettier，生成的代码应尽量通过其默认规则检查。
- 运行 `npm run lint:fix` 可以自动修复大多数风格问题。

重要提示 ：动态规则非常强大，但不宜过度复杂。规则文件本身应保持较高的可读性和可维护性。如果逻辑过于复杂，考虑将其拆分为多个小的、专注的规则文件，然后在主文件中按条件包含。

5. 实战问题排查与效能提升技巧

即使配置了完善的规则，在实际使用中也可能遇到 AI“不听话”或者规则冲突的情况。以下是一些常见问题及我的解决经验。

5.1 常见问题速查表

问题现象	可能原因	排查与解决方案
AI 完全忽略某条规则	1. 规则语法错误。 2. 规则过于复杂或模糊，AI 无法理解。 3. 规则与其他规则冲突，被覆盖。	1. 检查 .mdc 文件语法，确保 @include 路径正确，Markdown 列表格式正确。 2. 将复杂规则拆解为简单、明确的指令。用肯定句代替否定句（如“必须使用…”优于“不要使用…”）。 3. 检查规则顺序，后面的规则可能覆盖前面。将最基础、最重要的规则放在前面。
AI 在部分文件中遵守规则，在另一些文件中不遵守	1. 动态条件（ @if ）判断有误。 2. 文件类型未被规则覆盖。	1. 检查 fileExists 或 filePathMatches 的条件逻辑。在规则开头添加一条测试规则（如 - 当前文件路径是：{{filePath}} ）来调试。 2. 为未被覆盖的文件类型（如 .mdx , .sql ）添加通用规则或创建特定规则文件。
规则生效，但严重拖慢了 AI 响应速度	1. 包含的规则文件过多、过大。 2. 规则中包含了需要网络请求或复杂计算的指令。	1. 精简规则 ：只包含当前项目真正需要的规则。定期清理无用规则。 2. 避免外部依赖 ：规则中不要引用需要联网获取内容的指令。所有内容都应是本地静态文本。
团队中不同成员规则效果不一致	1. 本地 .cursor/rules.mdc 文件未提交到版本控制。 2. 成员使用的 Cursor 版本或 AI 模型不同。	1. 将 .cursor/rules.mdc 和必要的规则文件加入 Git （注意排除包含个人密钥的本地自定义规则）。确保团队统一。 2. 在项目 README 中约定推荐的 Cursor 版本和 AI 模型（如 Claude 3.5 Sonnet）。

5.2 提升规则效能的独家技巧

1. 从“规则”到“提示词”的互补 ：规则（Rules）是全局的、被动的约束。对于一次性的、复杂的特定任务，应在聊天中主动使用更精确的“提示词”（Prompts）。例如，规则可以规定“使用 async/await”，但当你需要重构一个复杂的回调地狱函数时，应该在聊天框详细描述背景和期望目标。 规则定基调，提示词指方向。

2. 善用“否定规则” ：除了规定“必须做什么”，更要明确“禁止做什么”。 cursor-rules 的安全模块大量使用了否定规则。例如，“禁止使用 eval() ”、“禁止使用 innerHTML 直接插入未转义的用户输入”。这种规则非常强硬且有效，能直接拦截高危代码模式。

3. 为规则添加“解释” ：在复杂的规则后面，用括号简要说明原因，这不仅能帮助未来的你理解，有时也能让 AI 更好地“理解”规则的意图。例如：“- 使用 const 声明不会被重新赋值的变量（这有助于提高代码可读性和避免意外错误）。”

4. 定期复审和更新规则 ：技术栈在更新，最佳实践在演进。每个季度或每个重大项目阶段后，花点时间回顾一下你的规则集。是否有新的框架特性（如 React 的新 Hook）需要纳入？是否有某条规则在实际使用中显得多余或过于苛刻？保持规则的活力。

5. 创建“项目脚手架”规则 ：对于经常创建的同类型新项目（如全栈应用、Chrome 插件、NPM 包），可以编写一套专门的“初始化”规则。当你在新文件夹中启动 Cursor 时，这套规则可以指导 AI 帮你快速生成 package.json 、基础目录结构、配置文件等，极大提升项目启动效率。

我个人最深的一个体会是， cursor-rules 这类工具的价值，随着使用时间的增长而愈发凸显。它最初节省的是你“调整代码格式”的几分钟，后来节省的是“排查安全隐患”的几小时，最终它塑造的是一种稳定、可预测的 AI 协作体验。它让 Cursor 从一个“有时很聪明的代码建议工具”，真正变成了一个理解你项目上下文、遵循你团队规范的“标准化开发伙伴”。花时间打磨一套属于自己的规则集，可能是你对 AI 编码工具最高回报率的一项投资。