AI 2026年4月5日 2 分钟阅读

Cursor Rules 完全指南：用自定义规则让 AI 编程助手遵循团队代码规范的实战教程

tinyash 0 条评论

引言

在团队开发中，保持一致的代码风格和规范一直是个挑战。随着 AI 编程助手的普及，如何让 AI 生成的代码符合团队标准成为了新的痛点。Cursor 的 Rules 功能正是为解决这个问题而生——它允许你定义自定义规则，让 AI 助手在生成代码时自动遵循团队的编码规范、架构约定和最佳实践。

本文将深入讲解 Cursor Rules 的配置方法、实际应用场景以及高级技巧，帮助你打造真正懂团队规范的 AI 编程助手。

什么是 Cursor Rules？

Cursor Rules 是 Cursor IDE 中的一项强大功能，允许用户通过自然语言或结构化配置定义 AI 助手的行为准则。这些规则会在 AI 生成代码时被自动参考，确保输出符合预期。

核心特性

  • 项目级规则：.cursorrules 文件可纳入版本控制，团队共享
  • 上下文感知：规则会根据当前文件和操作类型智能应用
  • 优先级系统：支持全局规则、项目规则、文件级规则的层级覆盖
  • 自然语言定义：用人类可读的方式描述期望行为

为什么需要 Cursor Rules？

在没有规则约束的情况下，AI 助手可能会：

  • 生成与团队风格不符的代码格式
  • 使用团队禁止的库或模式
  • 忽略项目的架构约定
  • 产生不一致的命名规范
  • 写出缺乏必要注释或文档的代码

通过精心设计的 Rules，这些问题都能得到有效解决。

基础配置：创建你的第一个 Rules 文件

文件位置

Cursor Rules 文件通常放置在项目根目录，命名为 .cursorrules：

your-project/
├── .cursorrules
├── src/
├── package.json
└── README.md

基础模板

以下是一个适用于 TypeScript/Node.js 项目的入门规则配置：

# 项目规则

## 代码风格

- 使用 2 空格缩进，不使用 Tab
- 字符串优先使用单引号，模板字符串除外
- 函数使用箭头函数语法
- 避免使用 `any` 类型，必要时使用 `unknown`

## 命名规范

- 变量和函数使用 camelCase
- 组件和类使用 PascalCase
- 常量使用 UPPER_SNAKE_CASE
- 私有成员以下划线 `_` 开头

## 错误处理

- 所有异步操作必须使用 try-catch 包裹
- 禁止静默捕获错误，必须记录或抛出
- 使用自定义错误类区分错误类型

## 注释要求

- 公共 API 必须有 JSDoc 注释
- 复杂逻辑需要行内注释说明意图
- TODO 注释必须包含负责人和日期

在 Cursor 中启用规则

  1. 打开 Cursor 设置（Cmd+, 或 Ctrl+,）
  2. 进入 “AI” 标签页
  3. 确保 “Use .cursorrules file” 选项已启用
  4. 规则文件会自动被 AI 助手读取

实战场景：为不同技术栈配置 Rules

React/Next.js 项目

# React/Next.js 项目规则

## 组件规范

- 所有组件必须是函数组件，使用 TypeScript
- 使用 React.FC 类型定义组件 Props
- 组件文件按功能组织：`components/feature/ComponentName.tsx`
- 每个组件文件只导出一个默认组件

## Hooks 使用

- 自定义 Hooks 必须以 `use` 开头
- Hooks 逻辑抽取到 `hooks/` 目录
- 避免在循环或条件语句中调用 Hooks

## 状态管理

- 优先使用 React Query 处理服务端状态
- 本地状态使用 `useState` 或 `useReducer`
- 避免不必要的 Context 使用

## 样式规范

- 使用 Tailwind CSS 进行样式编写
- 复杂样式抽取到 `styles/` 目录
- 禁止使用内联 style 属性

## 性能优化

- 大型列表必须使用虚拟滚动
- 图片必须使用 Next.js Image 组件
- 组件使用 `React.memo` 进行记忆化（当 Props 稳定时）

## 测试要求

- 组件必须包含单元测试
- 使用 React Testing Library
- 测试文件与被测文件同目录

Python/FastAPI 项目

# Python/FastAPI 项目规则

## 代码规范

- 遵循 PEP 8 风格指南
- 使用 Black 格式化代码
- 类型注解是必须的（使用 typing 模块）
- 函数必须有 docstring

## 项目结构

project/
├── app/
│   ├── api/          # API 路由
│   ├── core/         # 核心配置
│   ├── models/       # 数据模型
│   ├── schemas/      # Pydantic 模型
│   └── services/     # 业务逻辑
├── tests/
└── main.py

API 设计

  • 所有端点必须有响应模型定义
  • 使用依赖注入处理认证和数据库会话
  • 错误响应使用统一格式

数据库

  • 使用 SQLAlchemy 2.0 异步 API
  • 模型定义在 models/ 目录
  • 迁移使用 Alembic 管理

日志

  • 使用 structlog 进行结构化日志
  • 所有请求必须记录访问日志
  • 错误必须包含堆栈跟踪
### Go 项目

```markdown
# Go 项目规则

## 代码组织

- 遵循 Go 标准项目布局
- 每个包有清晰的单一职责
- 接口定义在使用方包内（接受接口，返回结构体）

## 错误处理

- 错误是返回值的一部分，必须检查
- 使用 `fmt.Errorf` 和 `%w` 进行错误包装
- 定义哨兵错误用于错误类型判断

## 命名

- 包名简短且全小写
- 导出标识符使用 PascalCase
- 私有标识符使用 camelCase
- 缩写保持全大写（如 HTTP、URL）

## 测试

- 测试文件与被测文件同目录
- 测试函数以 `Test` 开头
- 使用表驱动测试处理多场景

## 并发

- 使用 context 处理超时和取消
- goroutine 启动必须有退出机制
- 使用 sync 包进行同步

高级技巧：让 Rules 更智能

1. 使用示例代码

在规则中提供示例代码，让 AI 更准确理解期望：

## API 响应格式

所有 API 响应必须遵循以下格式：

```typescript
// ✅ 正确示例
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
  };
  timestamp: string;
}

// ❌ 避免直接返回数据
return res.json(users);

// ✅ 正确做法
return res.json({
  success: true,
  data: users,
  timestamp: new Date().toISOString()
});

### 2. 定义禁止模式

明确列出禁止使用的模式：

```markdown
## 禁止使用的模式

- ❌ 禁止使用 `eval()` 或 `Function` 构造函数
- ❌ 禁止在循环中创建新对象（性能问题）
- ❌ 禁止使用 `var`，统一使用 `let` 或 `const`
- ❌ 禁止直接操作 DOM，必须通过 React
- ❌ 禁止硬编码配置值，必须使用环境变量

3. 文件类型特定规则

针对不同文件类型定义不同规则：

## 测试文件规则 (*.test.ts, *.spec.ts)

- 测试描述使用 `describe` 分组
- 单个行为使用 `it` 或 `test` 定义
- 使用 `beforeEach` 进行测试隔离
- Mock 数据放在 `__mocks__` 目录

## 配置文件规则 (*.config.ts, *.config.js)

- 必须导出默认配置对象
- 环境变量使用 `process.env` 访问
- 提供合理的默认值
- 配置项必须有注释说明

4. 团队特定约定

将团队独有的约定写入规则：

## 团队约定

### 代码审查要求

- PR 必须关联 Jira 任务
- 提交信息遵循 Conventional Commits
- 重大变更需要更新 CHANGELOG.md

### 目录约定

- 特性代码放在 `features/` 目录
- 共享组件放在 `shared/` 目录
- 工具函数放在 `utils/` 目录

### 数据库约定

- 表名使用复数形式
- 主键统一命名为 `id`
- 时间戳字段：`created_at`, `updated_at`

常见问题与解决方案

问题 1：AI 不遵守规则

症状：AI 生成的代码仍然违反定义的规则。

解决方案：

  1. 规则描述更具体，提供正反示例
  2. 将重要规则放在文件顶部
  3. 使用强调词汇（“必须”、“禁止”、“始终”）
  4. 在对话中显式提醒规则

问题 2：规则冲突

症状：不同规则之间产生矛盾。

解决方案：

  1. 建立规则优先级：文件级 > 项目级 > 全局级
  2. 定期审查和清理规则
  3. 使用条件规则（“当…时，使用…”）

问题 3：规则文件过大

症状：规则文件变得冗长难维护。

解决方案：

  1. 按主题拆分到多个文件
  2. 使用引用链接到外部文档
  3. 只保留 AI 需要知道的核心规则
  4. 将详细文档放在 Wiki，规则中简要引用

团队共享与版本控制

将 Rules 纳入 Git

# 添加规则文件到版本控制
git add .cursorrules
git commit -m "docs: 添加项目 Cursor Rules 配置"
git push

新成员入职

在新成员入职文档中添加：

## 开发环境设置

1. 克隆项目后，Cursor 会自动读取 `.cursorrules` 文件
2. 确保 Cursor 设置中启用了 "Use .cursorrules file"
3. AI 助手会自动遵循项目规则生成代码

规则更新流程

  1. 在 PR 中修改 .cursorrules
  2. 团队审查规则变更
  3. 合并后通知团队成员
  4. 在 CHANGELOG 中记录重大规则变更

最佳实践总结

✅ 应该做的

  • 保持规则简洁明了
  • 提供具体示例
  • 定期审查和更新规则
  • 与团队编码规范文档保持一致
  • 将规则纳入版本控制

❌ 应该避免的

  • 规则过于冗长（超过 500 行）
  • 规则之间存在冲突
  • 使用模糊的描述
  • 忽略规则的维护更新
  • 将敏感信息写入规则文件

进阶：与 CI/CD 集成

可以将 Rules 中的规范与 CI 检查结合：

# .github/workflows/lint.yml
name: Code Quality

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run lint
      - run: npm run format:check

这样确保即使 AI 生成的代码也符合团队规范。

结语

Cursor Rules 是让 AI 编程助手真正融入团队工作流的关键工具。通过精心设计的规则配置，你可以：

  • 确保 AI 生成的代码符合团队标准
  • 减少代码审查中的风格问题
  • 加速新成员上手过程
  • 保持项目长期一致性

记住，Rules 不是一成不变的。随着项目发展和团队经验积累，定期回顾和更新规则，让它们始终保持实用性和准确性。

开始行动吧——为你的项目创建第一份 .cursorrules 文件，让 AI 成为真正懂团队规范的编程伙伴！

参考资源

AI AI 工具

发表评论

你的邮箱地址不会被公开，带 * 的为必填项。