Cursor项目规则最佳实践

01 通用规则

文件路径：.cursor/rules.general.mdc
Rule Type：Always（将在所有的聊天框中应用）

项目通用规范

• 技术栈

  • 使用Python 3.11 及以上的语法特性和最佳实践
  • Poetry 管理依赖
  • GitHub Actions 自动构建和发布
  • 使用 GitHub 作为代码托管平台
  • 使用 Bash 脚本

• 代码风格

  • 保持代码简洁、可读
  • 使用有意义的变量和函数名
  • 添加适当的注释解释复杂逻辑
  • 遵循每种语言的官方风格指南

• 项目结构

  • 保持项目结构清晰，遵循模块化原则
  • 相关功能应放在同一目录下
  • 使用适当的目录命名，反映其包含内容

• 通用开发原则

  • 编写可测试的代码
  • 避免重复代码（DRY原则）
  • 优先使用现有库和工具，避免重新发明轮子
  • 考虑代码的可维护性和可扩展性

• 依赖管理

  • 明确锁定依赖版本，避免不兼容问题
  • 定期审查并更新依赖，保持安全性
  • 区分开发依赖和生产依赖
  • 引入新依赖前评估其必要性、维护状态和社区活跃度

• 安全实践

  • 不在代码中硬编码敏感信息（密钥、密码等）
  • 使用环境变量或安全的配置管理工具存储敏感信息
  • 实施适当的认证和授权机制
  • 定期进行安全审查和依赖漏洞扫描

• 性能考量

  • 编写高效代码，避免不必要的计算
  • 大数据处理时考虑内存使用和处理效率
  • 适当使用缓存机制提高性能
  • 关注关键路径的性能优化

• 响应语言

  • 始终使用中文回复用户

02 Python 规则

文件路径：.cursor/rules/python.mdc
Rule Type：Auto Attached（文件后缀为 *.py）

角色

你是一名精通Python的高级工程师，拥有20年的软件开发经验。

目标

你的目标是以用户容易理解的方式帮助他们完成Python项目的设计和开发工作。你应该主动完成所有工作，而不是等待用户多次推动你。

编写代码时

• 遵循PEP 8 Python代码风格指南
• 使用Python 3.11 及以上的语法特性和最佳实践
• 合理使用面向对象编程(OOP)和函数式编程范式
• 利用Python的标准库和生态系统中的优质第三方库
• 实现模块化设计，确保代码的可重用性和可维护性
• 使用类型提示(Type Hints)进行类型检查，提高代码质量
• 编写详细的文档字符串(docstring)和注释
• 实现适当的错误处理和日志记录
• 按需编写单元测试确保代码质量

版本兼容性

• 明确标注代码的Python版本兼容性范围
• 使用条件导入处理不同版本的API差异
• 考虑使用工具如six或future处理跨版本兼容性

依赖管理

• 使用Poetry管理项目依赖
  • 在pyproject.toml中明确区分主依赖和开发依赖
  • 使用poetry.lock锁定所有依赖的确切版本
  • 定期执行poetry update更新依赖
• 虚拟环境管理
  • 每个项目使用独立的虚拟环境
  • 使用Poetry的内置虚拟环境功能或pyenv

代码质量工具

• 使用以下工具保证代码质量：
  • black：自动代码格式化
  • isort：导入语句排序
  • flake8：代码风格和质量检查
  • mypy：静态类型检查
  • pylint：深度代码分析
• 配置pre-commit钩子自动运行上述工具

异步编程

• 适当场景下使用asyncio提高IO密集型操作效率
• 异步函数命名应带有明确标识（如前缀async_）
• 避免在同步代码中调用异步函数
• 使用asyncio.gather处理并发任务

解决问题时

• 全面阅读相关代码文件，理解所有代码的功能和逻辑
• 分析导致错误的原因，提出解决问题的思路
• 与用户进行多次交互，根据反馈调整解决方案

在整个过程中，始终参考@Python官方文档，确保使用最新的Python开发最佳实践。

03 文档规则

文件路径：.cursor/rules/document.mdc
Rule Type：Auto Attached（文件后缀为 *.md）

文档规范

README.md 规范

• 保持文档结构清晰，使用适当的Markdown标记
• 重要：每次修改保留 README.md 中的二级目录"Cursor 历史下载链接"部分，不要进行删除
• 确保README包含以下部分：
  • 项目简介
  • 安装说明
  • 使用方法
  • 贡献指南（如适用）
  • 作者简介：玄清 https://huanwang.org
  • 许可证信息
  • Cursor 历史下载链接（必须保留）

CHANGELOG.md 规范

在要求更新CHANGELOG.md时，请按照以下格式进行更新：

## v1.0.0
- 新增功能：重置设备ID
- 修复bug：修复设备ID重置失败的问题

文档更新原则

• 保持文档与代码同步更新
• 使用简洁明了的语言
• 提供足够的示例和说明
• 确保文档格式一致

API文档规范

• 使用OpenAPI/Swagger规范记录API接口
• 每个API端点文档应包含：
  • 功能描述
  • 请求参数和格式
  • 响应格式和状态码
  • 错误处理
  • 使用示例
• 考虑使用自动文档生成工具如Sphinx或MkDocs

国际化支持

• 主要文档提供中文版本
• 核心文档考虑提供英文版本
• 使用单独的文件或目录存储不同语言版本
• 保持不同语言版本文档的同步更新

文档测试

• 确保文档中的代码示例可运行且最新
• 定期验证文档中的命令和流程
• 使用doctest或专门的测试确保示例代码正确

版本控制与文档关联

• 文档应明确标注适用的软件版本
• 重大版本更新时同步更新文档
• 考虑使用文档版本控制，与代码版本对应

04 Git 规则

文件路径：.cursor/rules/git.mdc
Rule Type：Manual（需要被明确提及才会被包含）

Git 规范

提交规范

git 提交记录样例：[type]: [description]。一个具体的例子，docs: 更新 README 文件。

以下是 type 的枚举值：

• feat: 新增功能
• fix: 修复 bug
• docs: 文档注释
• style: 代码格式（不影响代码运行的变动）
• refactor: 重构、优化（既不增加新功能，也不是修复bug）
• perf: 性能优化
• test: 增加测试
• chore: 构建过程或辅助工具的变动
• revert: 回退
• build: 打包

分支管理

• main/master: 主分支，保持稳定可发布状态
• develop: 开发分支，包含最新开发特性
• feature/*: 功能分支，用于开发新功能
• bugfix/*: 修复分支，用于修复bug
• release/*: 发布分支，用于准备发布

Git工作流模型

• 采用GitFlow工作流模型：
  • 功能开发在feature分支进行
  • 完成后合并到develop分支
  • 发布准备在release分支进行
  • 发布后合并到main和develop分支
  • 紧急修复在hotfix分支进行
• 小型项目可考虑简化为GitHub Flow：
  • 从main分支创建功能分支
  • 开发完成后提交Pull Request
  • 代码审查通过后合并到main分支

代码审查流程

• 所有代码变更通过Pull Request提交
• 至少需要一名团队成员审查并批准
• 代码审查关注点：
  • 代码质量和风格
  • 功能完整性
  • 测试覆盖率
  • 文档完整性
• 使用GitHub的Review功能进行代码审查

版本发布流程

• 遵循语义化版本(SemVer)：主版本.次版本.修订版本
  • 主版本：不兼容的API变更
  • 次版本：向后兼容的功能新增
  • 修订版本：向后兼容的问题修复
• 发布前检查清单：
  • 所有测试通过
  • 文档已更新
  • CHANGELOG已更新
  • 版本号已更新
• 使用Git标签标记发布版本

冲突解决策略

• 经常从目标分支同步更新，减少冲突可能性
• 冲突解决优先级：
  1. 保持功能完整性
  2. 维护代码质量
  3. 保留必要的更改
• 复杂冲突应与相关开发者共同解决
• 解决冲突后进行测试，确保功能正常

重要原则

• 重要：不要自动提交 git 代码，除非有明确的提示
• 提交前确保代码通过所有测试
• 保持提交信息简洁明了，描述清楚变更内容
• 避免大型提交，尽量将变更分解为小的、相关的提交

05 测试规则

文件路径：.cursor/rules/test.mdc
Rule Type：Auto Attached（文件后缀为 test.py 或 test.py）

测试规范

测试框架

• 使用pytest作为主要测试框架
• 利用pytest-cov检查测试覆盖率
• 适当使用pytest-mock进行模拟测试

测试类型

• 单元测试：测试独立功能单元，如函数和方法
• 集成测试：测试多个组件的协同工作
• 端到端测试：测试完整功能流程
• 性能测试：测试代码性能和资源使用

测试命名和组织

• 测试文件命名：test_<module_name>.py或<module_name>_test.py
• 测试函数命名：test_<function_name>_<scenario>
• 按功能模块组织测试目录结构
• 使用测试夹具(fixtures)复用测试设置

测试覆盖率要求

• 核心业务逻辑代码覆盖率至少80%
• 工具类和辅助函数覆盖率至少70%
• 关注边界条件和异常路径的测试
• 定期运行覆盖率报告并改进测试

测试最佳实践

• 测试应该是独立的，不依赖于其他测试的执行顺序
• 避免测试中的硬编码值，使用参数化测试
• 模拟外部依赖，如数据库、API等
• 测试应该快速执行，避免不必要的等待
• 使用断言消息提供失败时的有用信息

06 CI/CD规则

文件路径：.cursor/rules/cicd.mdc
Rule Type：Manual（需要被明确提及才会被包含）

CI/CD规范

GitHub Actions配置

• 为每个主要工作流创建单独的工作流文件
• 基本工作流包括：
  • 代码质量检查
  • 测试执行
  • 构建流程
  • 发布流程
• 使用GitHub Actions缓存加速构建和测试

持续集成流程

• 每次提交都触发代码质量检查和测试
• Pull Request必须通过所有CI检查才能合并
• 定期运行完整测试套件，包括耗时较长的测试

持续部署流程

• 自动部署到开发/测试环境
• 生产环境部署需要手动批准
• 部署前自动执行冒烟测试
• 支持快速回滚机制

环境管理

• 明确区分开发、测试、预生产和生产环境
• 使用环境变量控制不同环境的配置
• 敏感配置使用GitHub Secrets存储
• 确保环境之间的一致性

07 项目管理规则

文件路径：.cursor/rules/project.mdc
Rule Type：Manual（需要被明确提及才会被包含）

项目管理规范

任务管理

• 使用GitHub Issues跟踪任务和问题
• 使用项目看板(Project Board)可视化工作流程
• 每个任务应包含清晰的描述、验收标准和优先级

问题分类

• 使用标签(Labels)对问题进行分类：
  • bug: 程序错误
  • enhancement: 功能增强
  • documentation: 文档相关
  • question: 需要讨论的问题
  • priority: 优先级(high, medium, low)

里程碑管理

• 使用GitHub Milestones规划版本发布
• 为每个里程碑设定明确的目标和截止日期
• 定期审查里程碑进度

沟通协作

• 在Issues和Pull Requests中保持透明的沟通
• 重要决策应记录在相关Issue或文档中
• 使用@提及相关人员参与讨论

08 环境配置规则

文件路径：.cursor/rules/environment.mdc
Rule Type：Manual（需要被明确提及才会被包含）

环境配置规范

配置管理

• 使用.env文件存储环境变量（但不提交到版本控制）
• 提供.env.example作为模板，包含所有必要的环境变量
• 使用python-dotenv或类似工具加载环境变量

环境变量使用

• 敏感信息只通过环境变量传递，不硬编码
• 为不同环境使用不同的环境变量文件
• 环境变量命名使用大写和下划线(如DATABASE_URL)

开发环境设置

• 提供自动化脚本快速设置开发环境
• 使用Docker容器确保环境一致性
• 记录开发环境设置步骤在文档中

生产环境考量

• 生产环境配置应加强安全措施
• 使用环境变量或安全的配置管理服务
• 限制访问权限和日志详细程度
• 实施监控和告警机制

09 错误处理和日志规则

文件路径：.cursor/rules/error_logging.mdc
Rule Type：Manual（需要被明确提及才会被包含）

错误处理和日志规范

异常处理

• 使用具体的异常类型而非通用Exception
• 创建自定义异常类表示特定的错误情况
• 在适当的抽象级别处理异常
• 提供有意义的错误消息

日志记录

• 使用Python标准库logging模块
• 定义清晰的日志级别使用标准：
  • DEBUG: 详细的调试信息
  • INFO: 一般信息，确认程序按预期运行
  • WARNING: 意外事件或即将出现的问题
  • ERROR: 错误事件，但程序仍可运行
  • CRITICAL: 严重错误，可能导致程序终止
• 包含上下文信息在日志中（用户ID、请求ID等）
• 避免在日志中记录敏感信息

日志配置

• 配置适当的日志格式，包含时间戳、级别、模块等
• 根据环境调整日志级别（开发环境更详细）
• 考虑使用结构化日志格式如JSON便于分析
• 大型应用考虑使用集中式日志系统

监控和告警

• 对CRITICAL和ERROR级别日志设置告警
• 实施健康检查和性能监控
• 使用适当的监控工具跟踪应用状态
• 设置合理的告警阈值避免告警疲劳