1. 项目概述：一个可共享的 Cursor 规则仓库

如果你和我一样，日常开发重度依赖 Cursor 这类 AI 驱动的编辑器，那你肯定也遇到过类似的困扰：每次新建一个项目，或者在不同的项目间切换时，都得重新跟 AI 助手“交代”一遍你的编码习惯、项目规范和安全要求。比如，“Python 代码要符合 PEP 8”、“TypeScript 里别用 any ”、“Dockerfile 记得用非 root 用户”…… 说多了，自己都觉得烦。更麻烦的是，团队协作时，如何确保每个人使用的 Cursor 都能遵循同一套标准，而不是各写各的“方言”？这个名为 cursor-rules-repository 的项目，就是为了解决这个痛点而生的。

简单来说，这是一个开源的、可共享的 Cursor 规则仓库。它把针对不同技术栈（Python, TypeScript, React, Docker/Kubernetes）以及通用编程原则的最佳实践，编写成了 Cursor 能直接识别和应用的规则文件（ .mdc 格式）。你可以把它看作是一套可移植的“AI 结对编程规范手册”。通过简单的配置，无论是个人项目还是团队仓库，都能一键启用这套规则，让 Cursor 在代码补全、问题解答和代码重构时，始终在你的编码规范框架内进行建议，极大提升代码的一致性和质量。无论你是独立开发者想建立自己的标准，还是团队技术负责人希望统一编码风格，这个仓库都提供了一个极佳的起点和可扩展的框架。

2. 核心设计思路与规则架构解析

2.1 为什么需要集中化的规则管理？

在深入具体规则之前，我们先聊聊为什么这种集中化的规则管理方式有价值。Cursor 的规则功能本质上是上下文指令，它能让 AI 助手更了解你的项目背景和偏好。但默认情况下，这些规则是存储在本地 .cursor/rules 目录下的，与项目绑定。这就带来了几个问题：

  1. 复制成本高 ：每个新项目都要手动创建或复制规则文件。
  2. 同步困难 ：当某条最佳实践更新后（例如，React 推出了新的推荐模式），你需要手动更新所有项目的规则文件。
  3. 团队不一致 ：团队成员各自维护自己的规则，容易导致代码审查时出现风格冲突。

cursor-rules-repository 的核心思路，就是将规则文件视为一种“基础设施即代码”。通过 Git 仓库来管理它们，利用 Git 的版本控制、分支管理和协作能力，来解决上述问题。你可以通过 Git Submodule 或软链接等方式，让多个项目共享同一套规则源，更新时只需在源头操作一次，所有项目便能同步受益。

2.2 规则仓库的模块化设计

浏览仓库结构，你会发现它的设计非常清晰，采用了按技术栈分层的模块化设计：

  • 通用标准层 ( general-standards.mdc )：这是基石，包含了适用于所有编程语言的元规则。例如代码可读性、错误处理范式、测试理念、安全基线和 Git 提交规范。这层规则通常设置 alwaysApply: true ，确保在任何文件、任何会话中，AI 助手都秉持这些基本原则。
  • 语言特定层 ：针对不同语言生态进行深度定制。
    • python-standards.mdc ：聚焦于 Python 社区公认的 PEP 8、类型注解、异常处理和文档字符串（如 Google 风格）。
    • typescript-standards.mdc ：强调 TypeScript 的类型安全（杜绝 any ）、自定义错误类和异步模式。
    • react-patterns.mdc ：专注于 React 框架下的组件设计模式、Hooks 最佳实践和性能优化策略。
  • 基础设施层 ( docker-kubernetes.mdc )：覆盖容器化和编排领域的规范，如 Docker 的多阶段构建、镜像层优化、安全实践（非 root 用户运行）和 K8s 的资源管理。

这种分层结构的好处是职责分离。通用规则保障底线，特定规则提供精准指导。当你要为一个纯后端 Python 项目配置规则时，可以只引入通用层和 Python 层；对于一个全栈 TypeScript + React 项目，则引入通用、TypeScript 和 React 层。这种灵活性避免了规则冗余，也使得每一条规则都能写得更加具体和深入。

2.3 规则文件（.mdc）的结构与语法

Cursor 的规则文件使用一种增强的 Markdown 语法，文件头由 YAML Front Matter 和正文内容组成。

文件头（Front Matter） 定义了规则的元数据：

---
description: “强制要求 Python 函数和方法必须包含类型注解和 Google 风格的文档字符串。”
globs: “**/*.py“  # 应用此规则的文件模式，支持 glob 语法
alwaysApply: false  # 为 true 时，无视 globs，全局应用
---
  • globs 是关键配置项。 **/*.py 表示匹配项目根目录下任何深度的所有 .py 文件。你可以根据需要精确控制，例如 src/**/*.ts 只匹配 src 目录下的 TypeScript 文件， **/test/**/*.js 只匹配所有 test 目录下的 JavaScript 文件。
  • alwaysApply 要慎用。通常只留给那些最根本、最通用的编程原则（如“优先使用有意义的变量名”）。将其用于语言特定规则可能会干扰其他语言的编辑会话。

正文内容 则是给 AI 助手的详细指令。一个高效的规则正文通常包含：

  • 清晰的章节 ：将相关要求分组，如“命名规范”、“错误处理”、“性能优化”。
  • 具体的指令 ：使用肯定、明确的语句。例如，“对于可能返回 None 的函数，返回值类型应注解为 Optional[YourType] ”。
  • 正反对比示例 ：这是最有效的部分。使用 ✅ GOOD: 和 ❌ BAD: 的格式，直观展示符合规范与不符合规范的代码。 
    # ✅ GOOD: 使用类型注解和详细的文档字符串
def calculate_total(items: List[Item], discount: float = 0.0) -> float:
    “““计算商品总价，支持折扣。
    Args:
        items: 商品项列表。
        discount: 折扣比例，范围 0.0 到 1.0。
    Returns:
        折后总价。
    Raises:
        ValueError: 当 discount 参数不在有效范围内时。
    “““
    if not 0.0 <= discount <= 1.0:
        raise ValueError(“Discount must be between 0.0 and 1.0“)
    subtotal = sum(item.price for item in items)
    return subtotal * (1 - discount)

# ❌ BAD: 缺乏类型信息，文档缺失，魔法数字
def calc(items, disc=0):
    if disc < 0 or disc > 1:
        raise Exception(“bad discount“)
    total = 0
    for i in items:
        total += i[‘price‘]
    return total * (1 - disc)
  • 原理说明（可选但推荐） ：在复杂规则后简要解释“为什么”，能帮助 AI（以及未来的阅读者）更好地理解意图。例如，“使用 Optional 而非 Union[YourType, None] 是社区更简洁的约定。”

3. 实战部署：如何将规则集成到你的项目

了解了设计思路后，我们来看看如何实际使用。项目提供了三种集成方式，各有适用场景。

3.1 方案对比与选型建议

方案 命令/操作 优点 缺点 适用场景
1. 克隆到项目 git clone ... && cp -r ... 最简单，一步到位，规则完全内化到项目。 规则更新困难，需手动同步；项目仓库会包含规则文件。 快速实验、一次性项目、或希望规则与项目强绑定的情况。
2. Git 子模块 git submodule add ... 推荐 。规则作为独立子模块，易于更新和跨项目共享；保持项目清洁。 初次设置稍复杂；需要团队成员都理解子模块操作。 团队协作项目 、长期维护的多个项目共享同一套规则。
3. 手动复制 下载后复制 .cursor/rules/ 目录 最灵活，不依赖 Git；适合高度定制化。 完全手动，无版本跟踪和自动更新能力。 网络受限环境、或需要对规则进行大量个性化修改且不打算回馈上游。

对于绝大多数情况，特别是团队项目， 我强烈推荐使用 Git 子模块方案 。它完美体现了“基础设施即代码”的思想，是平衡便利性与可维护性的最佳选择。

3.2 详细操作步骤（以 Git 子模块为例）

假设你有一个名为 my-awesome-project 的项目，现在要集成这套规则。

步骤一：添加规则仓库为子模块 在你的项目根目录下执行：

# 这会在当前目录下创建一个 .cursor-rules 文件夹，并将规则仓库克隆到其中
git submodule add https://github.com/pallavjha25/cursor-rules-repository .cursor-rules

执行后，你会发现项目根目录多了一个 .cursor-rules 文件夹，并且项目根目录的 .gitmodules 文件会被更新，记录这个子模块的信息。

步骤二：将规则文件链接到 Cursor 标准位置 Cursor 只会读取项目根目录下 .cursor/rules/ 里的规则。我们需要把子模块里的规则复制（或链接）过去。

# 复制规则文件到 .cursor 目录（如果 .cursor 不存在会自动创建）
cp -r .cursor-rules/.cursor .

现在，你的项目结构应该类似这样：

my-awesome-project/
├── .cursor/
│   └── rules/
│       ├── general-standards.mdc
│       ├── python-standards.mdc
│       └── ...
├── .cursor-rules/  # 子模块
│   ├── .cursor/
│   │   └── rules/  # 规则源文件
│   └── README.md
├── src/
├── .gitmodules
└── ...

重要提示 ：复制操作（ cp ）是一次性的。子模块更新后，需要重新执行这个复制命令来获取新规则。你可以将这个命令写进项目的 post-checkout Git Hook 或 package.json 的脚本中，实现半自动更新。

步骤三：提交更改 将子模块的添加和 .cursor 目录的初始规则文件提交到你的项目仓库。

git add .gitmodules .cursor
git commit -m “feat: integrate shared cursor rules via submodule“

3.3 验证规则是否生效

打开 Cursor，进入你的项目。打开一个 Python 文件（例如 main.py ），尝试让 Cursor 帮你写一个函数。你应该能观察到，它的建议会开始遵循 python-standards.mdc 里的规范，比如自动添加类型提示和文档字符串骨架。

你也可以在 Cursor 中通过命令面板（ Cmd/Ctrl + Shift + P ）搜索 “Cursor Rules”，查看当前激活了哪些规则，这是一个很好的调试方式。

4. 规则定制与扩展指南

开源仓库提供的规则是很好的起点，但每个团队和项目都有独特的需求。掌握规则定制和扩展，才能让这套工具真正为你所用。

4.1 如何修改现有规则

规则文件就是普通的 Markdown 文件，直接编辑即可。例如，你觉得默认的 Python 规则对行长的限制太严格（比如默认的 79 字符），你可以直接修改 .cursor/rules/python-standards.mdc 文件。

  1. 找到关于代码格式或 PEP 8 的章节。
  2. 将相关的指令修改为你的团队标准，例如：“遵循 PEP 8，但最大行宽可放宽至 100 字符。”
  3. 保存文件。

关键点 ：Cursor 会 自动热重载 规则文件。你保存修改后，通常几秒内，新的规则就会生效，无需重启编辑器。你可以立刻打开一个文件进行测试。

4.2 创建全新的项目专属规则

假设你的团队内部有一个自定义的配置管理库 @mycompany/config ，并且有特定的使用模式。你可以为此创建一个专属规则文件。

  1. 在 .cursor/rules/ 目录下新建一个文件，例如 mycompany-config.mdc 。

  2. 编写文件头和内容：

    ---
description: “规范 @mycompany/config 库的使用方式，确保配置加载的一致性和错误处理。“
globs: “**/*.{js,ts}“  # 假设在 JS/TS 项目中使用
alwaysApply: false
---
# @mycompany/config 使用规范

## 配置加载
必须使用 `createConfigLoader` 工厂函数，而非直接实例化 `Config` 类。

✅ GOOD:
```javascript
import { createConfigLoader } from ‘@mycompany/config‘;
const config = await createConfigLoader(‘app‘).load();

    ❌ BAD:

    import { Config } from ‘@mycompany/config‘; // 错误：不应直接导入
const config = new Config(‘app‘); // 错误：缺少异步加载和缓存机制

    错误处理

    调用 load() 方法时必须使用 try-catch，并记录特定的错误码。

    ✅ GOOD:

    try {
    const config = await createConfigLoader(‘app‘).load();
} catch (error) {
    if (error.code === ‘CONFIG_NOT_FOUND‘) {
        // 处理特定错误
        logger.warn(‘Using default configuration‘);
    } else {
        throw error; // 重新抛出未知错误
    }
}

  3. 保存文件。现在，当你在项目中打开任何 .js 或 .ts 文件时，这条关于内部库使用的专属规则就会激活，指导 AI 生成符合内部规范的代码。

4.3 规则编写的“避坑”心得

在编写和调试规则的过程中，我积累了一些经验教训：

  • 规则冲突 ：如果多个规则文件对同一件事给出了不同指令，Cursor 的行为可能不可预测。通常，后加载的规则或更具体的 glob 模式可能占优。解决方法是保持规则职责单一，避免重叠。如果确实需要覆盖，可以调整文件名（按字母顺序加载）或使用更具体的 globs 。
  • 性能考量 ：规则文件不是越大越好。过长的规则（比如超过 500 行）可能会轻微影响 Cursor 的初始响应速度。建议将大型规则按主题拆分成多个小文件。例如，将 python-standards.mdc 拆分为 python-formatting.mdc 、 python-typing.mdc 、 python-error-handling.mdc 。
  • 指令的明确性 ：避免使用模糊的指令，如“写出高质量的代码”。要具体，如“函数长度不应超过 30 行，若超过应考虑重构为多个小函数”。
  • 测试你的规则 ：创建一个小型测试文件，故意编写一些违反规则的代码，然后使用 Cursor 的“自动修复”或“询问 AI”功能，看它是否能根据你的规则给出正确的修正建议。这是验证规则有效性的最好方法。

5. 团队协作与规则维护工作流

将规则仓库用于团队，不仅仅是技术集成，更涉及工作流程的建立。

5.1 团队初始统一设置

  1. 确定规则基线 ：技术负责人或架构师可以 Fork 原仓库，基于团队的技术栈和规范，对通用规则进行初次定制（例如，统一缩进为 2 空格还是 4 空格，是否强制使用 async/await 等）。
  2. 建立团队规则仓库 ：将 Fork 后的仓库作为团队内部的“黄金标准”源。例如， github.com/my-org/our-cursor-rules 。
  3. 更新集成命令 ：在团队项目的 README 或内部 Wiki 中，将集成步骤中的仓库 URL 替换为团队内部的仓库地址。 
    git submodule add https://github.com/my-org/our-cursor-rules .cursor-rules
cp -r .cursor-rules/.cursor .

5.2 规则更新与同步流程

规则不是一成不变的。当引入新技术、发现更好的模式、或原仓库更新时，需要同步。

对于使用子模块的项目： 

# 1. 进入子模块目录，拉取最新更改（从团队源仓库）
cd .cursor-rules
git pull origin main
cd ..

# 2. 将更新后的规则文件复制到项目 .cursor 目录
cp -r .cursor-rules/.cursor .

# 3. 提交子模块指针的更新到主项目
git add .cursor-rules
git commit -m “chore: update cursor rules submodule to latest version“

你可以将这个流程编写成一个简单的脚本（如 update-rules.sh ），方便团队成员执行。

5.3 处理规则的分歧与演进

团队内对某条规则有不同意见怎么办？这正体现了 Git 工作流的优势。

  1. 创建特性分支 ：在团队规则仓库中，为有争议的修改创建一个分支，例如 feat/relax-line-length 。
  2. 进行修改与测试 ：在该分支上修改规则，并通知团队成员在各自的项目中临时切换到这个子模块分支进行体验和测试。 
    cd .cursor-rules
git fetch origin
git checkout feat/relax-line-length
cd ..
cp -r .cursor-rules/.cursor .
  3. 收集反馈与合并 ：经过一段时间的测试和讨论，如果达成共识，则通过 Pull Request 将特性分支合并到 main 分支。之后所有项目按常规更新流程即可获得新规则。
  4. 版本标签 ：对于重大的、可能不向后兼容的规则变更，可以在团队规则仓库中打上 Git 标签（如 v2.0 ）。这样，追求稳定的项目可以锁定在某个标签版本，而追求前沿的项目可以跟踪 main 分支。

6. 常见问题排查与效能提升技巧

在实际使用中，你可能会遇到一些问题。以下是一些常见情况的排查思路和解决方法。

6.1 规则未生效的排查步骤

如果你发现 Cursor 似乎没有遵循你设定的规则，可以按以下顺序检查：

  1. 检查规则文件位置 ：确认 .cursor/rules/ 目录确实位于 项目根目录 下，并且 .mdc 文件在其中。路径错误是最常见的原因。
  2. 检查文件头 globs ：确认你正在编辑的文件路径匹配规则中定义的 globs 模式。例如，一个针对 **/*.py 的规则对 .pyi （存根文件）或子目录下很深的 .py 文件都有效。你可以使用在线 glob 测试工具来验证匹配。
  3. 检查 Cursor 规则面板 ：在 Cursor 中按下 Cmd/Ctrl + Shift + P ，输入 “Cursor Rules”，查看当前激活的规则列表。如果列表为空或没有你的规则，说明加载有问题。
  4. 检查规则语法 ：确保 .mdc 文件的 YAML Front Matter 格式正确，没有缩进错误。特别是 --- 必须单独成行。
  5. 重启 Cursor ：虽然规则支持热重载，但偶尔编辑器状态可能异常。尝试完全关闭 Cursor 再重新打开项目。
  6. 查看项目设置 ：确保你没有在 Cursor 的项目设置或全局设置中意外禁用了规则功能。

6.2 临时禁用与启用规则

有时，为了调试或处理一些特殊文件，你可能需要临时关闭某条规则。

  • 重命名法 ：最直接的方法是在文件系统中给规则文件加一个后缀，例如将 python-standards.mdc 重命名为 python-standards.mdc.disabled 。Cursor 会忽略不以 .mdc 结尾的文件。完成后改回来即可。
  • 修改 globs ：如果你只想对某个特定文件禁用，可以临时修改规则的 globs ，将其排除。例如，将 **/*.py 改为 **/*.py, !path/to/specific/file.py （注意：Cursor 的 glob 语法可能不完全支持所有否定模式，需测试）。
  • 使用 alwaysApply: false ：确保不是这条规则被误设为全局应用，导致在其他文件类型上也产生干扰。

6.3 提升 AI 遵循规则效果的技巧

规则写好了，但 AI 有时还是会“跑偏”。除了优化规则本身，还可以尝试：

  • 在聊天中明确引用规则 ：当你向 Cursor AI 提问或发出指令时，可以主动提及相关规则。例如：“请按照我们项目中的 react-patterns.mdc 规则，将这个类组件重构为函数组件，并使用 React.memo 进行优化。”
  • 提供更具体的上下文 ：在规则描述中，不仅说“要做什么”，也说“在什么情况下做”和“为什么”。AI 对上下文的理解越充分，输出越精准。
  • 迭代优化规则 ：将 AI 生成的不符合预期的代码，作为“❌ BAD”示例补充到规则中。这是一个持续改进的过程。规则库本身就是在与 AI 的互动中不断完善的。

6.4 与其他工具集成考量

Cursor 规则主要约束 AI 的代码生成和建议。它与你项目中可能已有的其他静态检查工具（如 ESLint, Pylint, Black, Prettier）是互补关系。

  • 分工 ：Cursor 规则偏向于“设计时”的指导和约束，关注代码意图、架构模式和高级别最佳实践。而 Linter/Formatter 是“检查/构建时”的工具，关注语法错误、格式细节。
  • 一致性 ：确保你的 Cursor 规则与团队的 ESLint 配置或 .prettierrc 等格式规范保持一致。例如，如果 Prettier 强制使用双引号，那么你的 typescript-standards.mdc 里关于字符串的规则也应该要求使用双引号，避免 AI 建议单引号然后又被格式化工具改掉，造成开发体验上的割裂。
  • 组合使用 ：理想的流程是：开发者借助 Cursor（受规则约束）高效编写出符合规范的代码草稿，然后由 Prettier 自动格式化，最后由 CI 流水线中的 Linter 进行最终检查。三者结合，能最大程度保障代码质量。

我个人在多个项目中实践这套方法后发现，初期投入时间制定和细化规则，会在项目的整个生命周期中带来巨大的回报。它减少了代码审查中关于风格的争论，降低了新成员的上手成本，并且让 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技术社区