用Cursor Rules构建代码规范引擎：让AI替你守住团队编码底线

为什么需要这个

代码审查中最无聊的部分是什么？不是逻辑错误，不是架构问题——是”这个变量名不符合规范”、”缩进用了空格应该用Tab”、”没有写docstring”。

这些问题本不该浪费人类的时间。而Cursor Rules（`.cursor/rules`文件）正好可以替你处理这一切：它是一套用自然语言写的规则，Cursor的AI在生成或修改代码时会自动遵守。

本教程教你如何从零搭建一套团队级别的代码规范引擎，不再让代码风格问题出现在CR中。

什么是Cursor Rules

Cursor Rules是一组存放在项目`.cursor/rules`目录下的Markdown文件，每个文件包含一段或多段规则。当你让Cursor的AI写代码时，它会自动将这些规则注入到上下文中。

规则文件支持`alwaysApply`、`globs`（文件匹配模式）和`description`等元数据，让你可以精确控制哪些规则在什么场景下生效。

第一步：创建规则目录结构

mkdir -p .cursor/rules

推荐的结构：

.cursor/rules/
├── 00-global.md        # 全局规则，所有文件都生效
├── 10-python.md        # Python专用
├── 20-react.md         # 前端React专用
├── 30-git-commit.md    # Git提交规范
└── 99-security.md      # 安全检查（最高优先级）

文件名的数字前缀控制规则注入顺序——数字越小的规则越早注入，`99-`开头的安全规则最后注入（优先级最高时放前面也行，看你的偏好设置）。

第二步：编写全局规则

创建`.cursor/rules/00-global.md`：

---
alwaysApply: true
description: 全局代码规范，适用于所有文件类型
---

# 全局编码规范

## 命名规范
- 变量和函数使用驼峰命名（camelCase）或下划线命名（snake_case），取决于项目约定
- **一旦选定命名风格，整个文件保持一致**
- 常量使用全大写+下划线：`MAX_RETRY_COUNT`
- 布尔变量以 `is` / `has` / `should` 开头

## 注释规范
- 每个公共函数/类必须有docstring，说明用途、参数和返回值
- 复杂逻辑必须有行内注释解释"为什么"这样做，而非"做了什么"
- TODO注释格式：`# TODO(作者): 描述 - 截止日期`

## 代码结构
- 单个函数不超过50行（除非有充分理由）
- 重复代码必须抽取为共享函数
- 优先使用早返回（early return）减少嵌套层级
- 嵌套层级不超过3层

## 禁止事项
- 禁止提交包含API Key/密码/Token的代码
- 禁止使用 `console.log`（前端）/ `print`（生产代码）做调试
- 禁止注释掉的代码块（用Git历史追溯）

第三步：编写语言专用规则

创建`.cursor/rules/10-python.md`：

---
globs: ["**/*.py"]
description: Python代码规范
---

# Python编码规范

## 类型与导入
- 所有公共函数必须包含类型注解
- 导入顺序：标准库 → 第三方 → 本地模块，每组之间空一行
- 禁止使用 `from module import *`

## 错误处理
- 禁止裸 `except:` — 必须指定异常类型
- 自定义异常继承自项目基类，不是直接继承 `Exception`
- 外部API调用必须有 try/except + 重试逻辑

## Python特性
- 使用 `pathlib.Path` 替代 `os.path`
- 字符串格式化优先使用 f-string
- 数据类使用 `@dataclass` 而非普通类
- 上下文管理器通过 `with` 语句使用

创建`.cursor/rules/20-react.md`：

---
globs: ["**/*.tsx", "**/*.jsx"]
description: React/TypeScript前端规范
---

# 前端代码规范

## 组件
- 一个文件只导出一个组件
- 组件Props必须有TypeScript接口定义
- 优先使用函数组件 + Hooks

## 状态管理
- 状态放在最近的公共祖先中
- 避免prop drilling超过3层
- 使用 `useMemo` / `useCallback` 优化重渲染

## 样式
- 使用Tailwind CSS，禁止内联style对象
- 响应式设计：移动端优先

第四步：安全规则（最高优先级）

创建`.cursor/rules/99-security.md`：

---
alwaysApply: true
description: 安全规则，所有AI生成的代码必须遵守
---

# 安全硬约束

## 数据安全
- 🔴 绝不生成包含真实API Key、密码、Token的代码
- 🔴 用户输入必须经过验证和清理再使用
- 🔴 SQL查询必须使用参数化（禁止字符串拼接）

## 输入输出
- 所有用户输入默认不可信
- 文件路径操作必须防范路径遍历攻击
- 日志中不得记录密码、Token等敏感信息

## 依赖
- 不推荐使用最后更新超过2年的依赖包
- 新增依赖前先检查是否有更轻量的替代方案

第五步：Git提交规范

创建`.cursor/rules/30-git-commit.md`：

---
globs: ["**/*"]
description: Git commit信息规范（AI辅助生成commit message时参考）
---

# Commit规范

- 格式: `<type>(<scope>): <subject>`
- Type: feat/fix/docs/style/refactor/test/chore
- Subject使用祈使句，首字母小写，不加句号
- 示例: `feat(auth): add JWT refresh token support`

第六步：验证规则是否生效

在Cursor中打开Composer（Cmd+I / Ctrl+I），输入：

写一个处理用户登录的Python函数

观察AI生成的代码是否：

– ✅ 有类型注解

– ✅ 有docstring

– ✅ 使用了参数化查询

– ✅ 没有硬编码密码

– ✅ 异常处理指定了类型

如果某个规则没生效，检查：

– 规则文件是否在`.cursor/rules/`目录下

– `globs`模式是否匹配当前文件

– 规则的描述是否清晰无歧义

常见问题

Q: 规则太多导致AI输出变慢？

A: 保持每条规则简洁。如果某个项目的`.cursor/rules`文件总大小超过50KB，考虑用`globs`精确匹配，让不相关的规则不被注入。

Q: 团队有人不遵守规则？

A: 除了Cursor Rules，还应该在CI中加自动化检查（`ruff` / `eslint` / `sqlfluff`），形成”AI生成时遵守 + CI检查时拒绝”的双重保障。

Q: Cursor和Claude Code的规则通用吗？

A: 不通用。但规则描述的规范内容是一致的——你只需要把同一套规范翻译成不同工具的规则格式。这也是为什么建议把规范本身写成与工具无关的描述，然后分别映射到Cursor Rules和Claude Rules。

Cursor Rules vs ESLint/Prettier：边界在哪里

很多团队已经有ESLint、Prettier、ruff等自动化检查工具。那Cursor Rules还有必要吗？

答案是：它们解决不同的问题，而且互为补充。

ESLint/Prettier/ruff是”事后检查”——代码写完了，工具告诉你哪里不符合规范。而Cursor Rules是”事前预防”——AI在生成代码的那一刻就已经遵守了规范，从源头上避免了不合规代码的产生。

打个比方：Linter是质检员，在生产线上检查成品；Rules是产线设计图，确保生产出来的每个产品都符合规格。

两者结合的最佳实践是：

1. Rules覆盖语义层面的规范（命名、注释、错误处理、安全约束）——这些ESLint管不了

2. Linter覆盖语法层面的规范（缩进、引号、分号、导入排序）——这些Rules可以不管

3. CI中两者都跑，形成”AI预防 + 工具兜底”的完整保障

团队推广策略

如果你想把Cursor Rules推广到整个团队，避免”只有你一个人在用”的局面：

第一步：选3条最痛的规范。 不要一上来就扔50条规则。选出团队CR中重复出现次数最多的3个问题——比如”缺少类型注解”、”日志打印了敏感信息”、”import顺序混乱”——作为第一批规则。

第二步：用数据说话。 记录推行前一周CR中”格式/规范类评论”的数量，推行后再记录一周。把数据放在团队会议上——当大家看到规范问题减少了70%时，自然愿意配合。

第三步：建立反馈机制。 在`.cursor/rules/`目录里放一个`FEEDBACK.md`，让团队成员记录”某条规则太严格了”或”这种场景规则没覆盖到”。定期Review并调整规则。

**核心思路：** 代码规范的价值不在”写出来”，而在”被遵守”。Cursor Rules把规范从文档变成了AI的行为约束——你不需要在CR里花时间指出格式问题，因为AI在生成代码的那一刻就已经遵守了。把人的精力留给真正重要的逻辑和架构审查。

— END —
LC 智趣厅 · 科技与生活的交点
ihygg.cn