Cursor Rules在实际开发中的三种层级&实际应用（附20个常用Rules）

Cursor Rules在实际开发中的三种层级&实际应用（附20个常用Rules）

原创 蔡蔡啊 ai呀蔡蔡 2025年04月24日 17:19 广东

公众号

之所以单独出这篇内容，主要两个原因：

第一，之前提到 .cursorrules将被移除，大家现在就可以迁移使用Project Rules，控制代码更精准 ，也介绍了Project Rules的工具集（cursor.directory）和实际用法，但后面收到一些小伙伴反馈：

• cursor.directory的 Rules 都是英文的，有没有中文版？

• 在实际开发中还是不太会用Project Rules......

第二，虽然之前有分享过 如何根据不同项目写好一份合格的cursorrules? 但由于上下文限制，.cursorrules没法做到面面俱到，否则太长的.cursorrules很容易超出限制，导致单次对话非常低效。所以.cursorrules比较适合小型项目。如果你后续做中大型项目，并且要实现更细致和更高效的代码控制，那么 Project Rules 会比 .cursorrules更适合。

以下是具体内容：

---

一、Project Rules的三种层级

根据我们的实际开发场景，我们需要用到的 Rules（规则/规范）大致可以分为三个层级：

• 通用规范：适用于所有项目，不受编程语言和框架影响

• 编程语言规范：适用特定编程语言的最佳实践，遵循语言设计思想和惯例

• 框架规范：适用特定框架，确保与框架生态系统兼容和一致性

这三种规则层层递进，从通用性到特定性，共同构成完整的编码规范体系。

其实除了通用规范、编程语言规范和框架规范外，在企业级生产环境中，还有以下几个层级的规范（不过我们今天这篇内容不考虑这几种规则）：

• 团队/公司规范：针对特定企业/公司的约定和实践，比如内部库使用规则、代码审查标准等；

• 项目规范：针对特定项目的定制化规则；

• 领域规范：针对特定业务领域的最佳实践，比如金融、医疗、游戏开发等行业标准；

• 合规性规范：满足法律法规和行业标准的要求，比如GDPR、HIPAA、PCI DSS等；

• 可访问性规范：确保软件对所有用户可用的标准，比如WCAG等无障碍标准等；

二、如何撰写这三种层级的 Project Rules ？

为方便大家理解和使用，这里会沿用之前的.cursorrules的方法，按常见的开发项目类型进行介绍，包括网页开发、浏览器插件开发、iOS应用开发、安卓应用开发、微信小程序开发、Python脚本开发。

至于其它项目类型，如桌面端应用、Unity游戏开发等更多类型，大家后续遇到的时候根据这种撰写方法去实践即可。

2.1 通用规范

通用规范不受限于编程语言和框架，因此同样不受限于开发项目类型，大家可以先看一份通用项目规范示例：

# 项目通用开发规范## 1. 项目结构规范### 目录结构```project_name/├── docs/                 # 项目文档├── src/                  # 源代码│   ├── core/            # 核心功能│   ├── utils/           # 工具函数│   └── tests/           # 测试文件├── scripts/             # 脚本文件├── config/              # 配置文件├── .github/             # CI/CD 配置├── package.json         # 项目配置└── README.md           # 项目说明```### 组织原则- 保持项目结构清晰，遵循模块化原则- 相关功能应放在同一目录下- 使用适当的目录命名，反映其包含内容
## 2. 代码规范### 命名规范```类名：PascalCase（大驼峰）函数名：camelCase（小驼峰）或 snake_case常量：UPPER_SNAKE_CASE变量：camelCase 或 snake_case```### 代码质量原则- 遵循 SOLID 设计原则- 避免代码重复（DRY原则）- 保持代码简洁、清晰、易读- 考虑代码的可维护性和可扩展性### 异常处理- 合理使用异常处理机制- 提供清晰的错误信息- 记录必要的错误日志- 优雅处理边界情况
## 3. 文档规范### 代码注释```/** * 函数功能说明 *  * @param {参数类型} 参数名 - 参数说明 * @returns {返回类型} 返回值说明 */```### 项目文档- 及时更新 README 和技术文档- 使用中文编写文档- 包含必要的安装和使用说明- 记录重要的架构决策### 国际化准备- 代码注释使用中文- 错误信息和日志使用中文描述- 预留国际化支持的接口
## 4. 开发环境### 依赖管理- 使用项目对应语言的包管理工具- 锁定依赖版本，确保构建稳定性- 定期更新依赖，修复安全隐患- 优先使用现有库和工具，避免重新发明轮子
## 5. 版本控制规范### 基础配置- 使用 Git 作为版本控制系统- 设置合适的 .gitignore 文件- 保护主分支，实施分支权限控制### 分支管理- 采用规范的分支开发流程（如 Git Flow 或 Trunk Based Development）- 主分支保持稳定，开发在特性分支进行- 定期清理过期分支### 提交规范- 使用清晰的 commit 信息- 每个提交专注于单一功能或修复- 合理使用 tag 标记版本### 代码审查- 所有代码变更必须经过审查- 遵循代码审查清单- 及时响应审查意见- 确保代码质量和一致性
## 6. 测试规范### 测试原则- 遵循测试金字塔原则- 保持测试代码的整洁和可维护性- 避免测试代码重复- 关注测试覆盖率### 测试类型- 单元测试：测试独立功能单元- 集成测试：测试模块间交互- 端到端测试：测试完整业务流程- 性能测试：关键功能性能验证
## 7. 安全规范- 使用环境变量存储敏感配置- 避免在代码中硬编码敏感信息- 定期更新依赖包版本- 实施安全扫描

这份通用项目规范实际上包含了七种常见的规范，包括：项目结构规范、代码规范、文档规范、开发环境、版本控制规范、测试规范、安全规范。

大家如果看过之前这篇文章 Cursor项目后期维护全是坑？前期一定要做好项目和代码结构拆解，应该会记得代码结构的原则：模块化、职责分离、可扩展性、可读性。

而这七种项目规范，实际上也是在做类似的事：

1. 项目结构规范：

这其实就是之前那篇”代码结构拆解“主题文章的标准化，它定义了项目的目录结构和文件组织方式，确保代码、配置文件、文档等资源按照模块化、职责分离的原则存放，非常方便我们后续去快速定位、维护和拓展。

## 1. 项目结构规范### 目录结构```project_name/├── docs/                 # 项目文档├── src/                  # 源代码│   ├── core/            # 核心功能│   ├── utils/           # 工具函数│   └── tests/           # 测试文件├── scripts/             # 脚本文件├── config/              # 配置文件├── .github/             # CI/CD 配置├── package.json         # 项目配置└── README.md           # 项目说明```### 组织原则- 保持项目结构清晰，遵循模块化原则- 相关功能应放在同一目录下- 使用适当的目录命名，反映其包含内容

2. 代码规范

之前和企业开发人员在聊天的时候，他们经常戏称自己在公司系统里写代码是在💩上雕花，因为一套系统中融合了很多不同程序员的风格迥异的代码，他们不仅阅读起来麻烦，而且改起来也很费劲。

和Cursor结对编程，其实也是类似的，如果你没有进行代码规范，那你就相当于每次都在不同程序员的代码上进行编写，久而久之，就会遇到前面提到的问题。

因此代码规范的优点很明显：

• 提升可读性：统一的命名和格式让代码像“同一人编写”，降低阅读难度。

• 减少错误：规范的异常处理和设计原则可以降低 bug 概率。

• 便于维护：清晰的代码结构和逻辑便于后期修改和扩展（和前面是一致的）。

• 支持自动化：可以使用静态分析工具（如 ESLint、Pylint）检查代码质量。

## 2. 代码规范### 命名规范```类名：PascalCase（大驼峰）函数名：camelCase（小驼峰）或 snake_case常量：UPPER_SNAKE_CASE变量：camelCase 或 snake_case```### 代码质量原则- 遵循 SOLID 设计原则- 避免代码重复（DRY原则）- 保持代码简洁、清晰、易读- 考虑代码的可维护性和可扩展性### 异常处理- 合理使用异常处理机制- 提供清晰的错误信息- 记录必要的错误日志- 优雅处理边界情况