Cursor Rules 体系指南：让 AI 写出你想要的代码

> 你用 Cursor 写代码的时候，有没有遇到过这种情况：AI 生成了一个 Class 组件，但你的项目全是用 Hooks；AI 引用了 lodash，但你们团队统一用的是 es-toolkit；AI 写的 API 路径是 /api/user，但项目的约定是 /api/v1/users。 > > 这不是 AI 的问题。是你没告诉它规则。 > > Cursor Rules 就是这套规则的语言——它告诉 AI「在这个项目里，你该怎么写代码」。本文从零开始，帮你建立一套完整的 Rules 体系。

目录：

Rules 语法详解
项目级 vs 全局 Rules 策略
Agent 模式下的 Rules 行为
实战模板（4 套完整可用的 Rules）
Rules 与其他配置的配合
团队共享 Rules 方案
常见坑点排查（10 个）
高级技巧

1. Rules 语法详解

1.1 两种写法：`.cursorrules` vs `.cursor/rules/`

Cursor 支持两种 Rules 文件格式：

格式	路径	特点
单文件	项目根 `.cursorrules`	简单直接，适合小型项目
多文件目录	`.cursor/rules/*.md`	模块化，支持 glob 匹配，推荐

推荐使用 .cursor/rules/ 目录——它支持多个规则文件，可以按文件类型匹配，更灵活。

1.2 规则文件结构

每个规则文件由 YAML Frontmatter + Markdown Body 组成：

name: react-component-standard
description: React 组件编写规范
globs:
  - "**/*.tsx"
  - "**/*.jsx"
alwaysApply: false

# React 组件规范

## 组件定义
- 所有新组件使用函数式组件 + Hooks
- 禁止使用 Class 组件
- 组件文件使用 PascalCase 命名

## 状态管理
- 本地状态使用 useState
- 跨组件状态使用 Context + useReducer
- 避免 prop drilling 超过 2 层

1.3 Frontmatter 字段参考

字段	类型	必填	说明
`name`	string	是	规则名称，用于标识和调试
`description`	string	否	规则描述，帮助团队成员理解规则用途
`globs`	string[]	否	文件匹配模式，规则只在匹配的文件上生效
`alwaysApply`	boolean	否	是否始终生效（默认 false）
`priority`	number	否	规则优先级（数字越大优先级越高）

1.4 globs 详解

globs 让规则精确匹配文件类型：

# 只对 TypeScript React 组件生效
globs:
  - "**/*.tsx"

# 匹配多个类型
globs:
  - "**/*.ts"
  - "**/*.tsx"
  - "**/api/**/*.ts"   # 仅 API 路由

# 排除特定目录
globs:
  - "**/*.tsx"
  - "!**/node_modules/**"
  - "!**/*.test.tsx"     # 测试文件不应用此规则

1.5 规则优先级

高优先级 ←─────────────────────────────→ 低优先级
  .cursor/rules/ 目录    &gt;   项目根 .cursorrules    &gt;   全局 Rules
  (globs 精确匹配)           (项目级通用)                (个人偏好)

当多个规则冲突时，globs 更精确的规则优先，alwaysApply: true 的规则覆盖 alwaysApply: false。

2. 项目级 vs 全局 Rules 策略

2.1 分层策略

全局 Rules (~/.cursor/rules/)
├── 个人编码偏好（缩进风格、引号类型）
├── 通用安全规范（不要硬编码密钥）
└── 语言通用约定（TypeScript 严格模式）

项目 Rules (.cursor/rules/)
├── 技术栈约定（React Hooks、Tailwind、Prisma）
├── 项目特定规范（API 路径前缀、组件目录结构）
├── 团队约定（Git 提交信息格式、Code Review 清单）
└── 禁止事项（禁用的库、禁用的模式）

2.2 什么该放 Rules，什么不该放

放 Rules	不放 Rules
技术栈选择（用 React Hooks 还是 Class）	算法实现细节（放代码注释）
代码风格约定（函数命名、文件命名）	业务逻辑说明（放 README）
禁止使用的库或模式	部署流程（放 CLAUDE.md）
API 路径规范	数据库 Schema（放 Prisma Schema）
组件目录结构约定	测试数据（放 fixtures）

判断标准：如果一条规则会影响 AI 生成代码的方式，放 Rules。如果只是解释已写好的代码，放注释或 README。

3. Agent 模式下的 Rules 行为

3.1 Chat 模式 vs Agent 模式

维度	Chat 模式	Agent 模式
Rules 加载	每次对话开始时加载	每次 Agent 执行步骤时加载
globs 匹配	对当前打开的文件生效	对 Agent 正在操作的文件生效
alwaysApply	始终注入 System Prompt	始终注入 Agent 上下文
工具调用	AI 手动触发	Agent 自动调用

3.2 Agent 模式专用指令

在 Agent 模式下，AI 会自动调用工具。Rules 中可以添加 Agent 专用指令：

name: agent-safety
description: Agent 模式安全约束
alwaysApply: true

# Agent 模式安全约束

## 工具调用规则
- 写文件前先确认文件存在
- 删除文件前先备份
- 修改超过 5 个文件时，先说明修改计划

## 自动执行（Auto-Run）
- 读文件操作可以自动执行
- 写文件操作需要确认（除非在 autoApprove 列表中）
- npm/pip install 操作需要确认

3.3 Auto-Run 与 Rules 配合

在 Cursor Settings → Features → Auto-Run 中开启自动执行后，Agent 会自动运行工具而无需确认。在 Rules 中明确哪些操作可以自动执行：

# Auto-Run 白名单
以下操作 Agent 可以自动执行，无需确认：
- Read 任何文件
- Bash(ls, cat, grep, find)
- Bash(npm test, npm run lint)

以下操作必须经用户确认：
- Bash(git push, git commit)
- Bash(npm install, pip install)
- 任何 rm / delete 操作

4. 实战模板（4 套完整可用的 Rules）

4.1 前端项目（React / Next.js / Tailwind）

name: frontend-react-nextjs
description: React + Next.js + Tailwind 前端项目规范
globs:
  - "**/*.tsx"
  - "**/*.ts"
alwaysApply: true

# 前端开发规范

## 组件
- 所有组件使用函数式组件 + Hooks
- 组件文件放在 `src/components/`，页面放在 `src/app/`
- 组件命名使用 PascalCase，文件名与组件名一致
- Props 类型定义在组件文件顶部：`interface XxxProps { ... }`

## 样式
- 样式优先使用 Tailwind CSS 类名
- 避免内联 style，除非是动态计算的值
- 响应式设计使用 Tailwind 断点（sm/md/lg/xl）
- 自定义颜色使用 Tailwind 配置文件中的 token

## 状态管理
- 本地状态：useState
- 跨组件共享：React Context + useReducer
- 服务端数据：React Query（@tanstack/react-query）
- 避免 prop drilling 超过 2 层

## API 调用
- 所有 API 调用统一通过 `src/lib/api.ts`
- API 路径使用 `/api/v1/` 前缀
- 请求和响应类型定义在 `src/types/api.ts`

## 文件命名
- 组件文件：PascalCase（`UserProfile.tsx`）
- 工具函数：camelCase（`formatDate.ts`）
- 类型定义：PascalCase（`User.ts`）
- 样式文件：kebab-case（`user-profile.module.css`）

## 禁止事项
- 禁止使用 Class 组件
- 禁止使用 jQuery 或直接操作 DOM
- 禁止引入新的 UI 库（统一用项目已有的）
- 禁止使用 `any` 类型
- 禁止使用 `var`

4.2 后端项目（Node.js / NestJS / Prisma）

name: backend-nestjs-prisma
description: NestJS + Prisma + PostgreSQL 后端项目规范
globs:
  - "**/*.ts"
  - "!**/*.spec.ts"
alwaysApply: true

# 后端开发规范

## 架构
- Controller：路由和参数校验（使用 class-validator 装饰器）
- Service：业务逻辑
- Repository：数据库操作（通过 Prisma）
- 每层只做自己该做的事，不跨层调用

## API 设计
- 路径前缀：`/api/v1/`
- RESTful 风格：GET（查）、POST（增）、PATCH（改）、DELETE（删）
- 返回格式统一：`{ code: number, message: string, data: T }`
- 分页参数：`page`（从 1 开始）和 `pageSize`（默认 20）

## 数据库
- 所有数据库操作通过 Prisma Client
- 禁止手写 SQL（除非 Prisma 无法实现）
- 数据库迁移使用 `npx prisma migrate dev`
- 关联查询使用 Prisma 的 include/select

## 安全
- 用户输入必须校验（class-validator）
- 密码使用 bcrypt 哈希
- JWT Token 有效期不超过 24 小时
- 敏感配置通过环境变量注入
- API 限流（@nestjs/throttler）

## 错误处理
- 业务异常使用 NestJS 内置 HttpException
- 未知异常通过全局 Exception Filter 处理
- 错误信息不暴露内部实现细节

## 禁止事项
- 禁止在 Controller 中直接操作数据库
- 禁止硬编码配置值
- 禁止使用 console.log（统一用 Logger）
- 禁止忽略 Prisma 迁移

4.3 全栈项目（Monorepo）

name: fullstack-monorepo
description: 前后端共享的类型和约定
alwaysApply: true

# 全栈项目规范

## 目录结构

packages/ ├── frontend/ # Next.js 前端 ├── backend/ # NestJS 后端 └── shared/ # 共享类型和工具


## 类型共享
- 前后端共享的类型定义在 `packages/shared/src/types/`
- API 请求/响应类型必须与后端 DTO 保持一致
- 修改 shared 类型后，前后端同时更新

## API 契约
- 前端通过 `packages/shared` 中的类型调用 API
- 后端 Controller 的 DTO 与 shared 类型保持同步
- API 变更遵循向后兼容原则

## 跨端协作
- 前端提交代码前确认对应后端接口已实现
- 后端 API 变更后同步更新前端 API client
- 重大变更通过 Issue 提前沟通

## 禁止事项
- 禁止前后端各自定义相同类型（放到 shared）
- 禁止前端直接访问数据库
- 禁止后端渲染 HTML（前后端完全分离）

4.4 Python 项目

name: python-project
description: Python 项目编码规范
globs:
  - "**/*.py"
alwaysApply: true

# Python 编码规范

## 类型注解
- 所有函数参数和返回值必须有类型注解
- 使用 `from __future__ import annotations`（Python 3.10+ 不用）
- 复杂类型使用 `TypeAlias` 或 `typing.TypeVar`

## 文档字符串
- 所有公开函数和类必须有 docstring
- 使用 Google 风格 docstring：
  ```python
  def fetch_user(user_id: int) -&gt; User | None:
      """获取用户信息。

      Args:
          user_id: 用户 ID。

      Returns:
          用户对象，如果不存在则返回 None。

      Raises:
          DatabaseError: 数据库连接失败。
      """

代码组织

每个模块的公开 API 在 __init__.py 中显式导出
工具函数放在 utils/ 目录
配置放在 config.py 或 settings.py

测试

使用 pytest
测试文件放在 tests/ 目录
测试函数命名：test_<功能>_<场景>

依赖管理

使用 pyproject.toml 管理依赖
开发依赖放在 [project.optional-dependencies] dev
锁定文件用 requirements.txt 或 uv.lock

禁止事项

禁止使用 import *
禁止在函数内部修改全局变量
禁止捕获所有异常（except Exception 要给出理由）
禁止 print 调试（用 logging）



## 5. Rules 与其他配置的配合

### 5.1 Rules vs 其他配置的分工

| 配置 | 用途 | 受众 |
|------|------|------|
| **Cursor Rules** | 告诉 AI 怎么生成代码 | AI（Cursor） |
| **`.cursorignore`** | 告诉 Cursor 哪些文件不要碰 | Cursor 索引 |
| **`CLAUDE.md`** | 告诉 Claude Code 项目概况 | Claude Code |
| **`.editorconfig`** | 编辑器统一基础格式 | 所有编辑器 |
| **ESLint / Prettier** | 自动化代码检查和格式化 | 构建工具 |
| **README** | 项目说明（给人看） | 开发者 |
| **代码注释** | 解释特定代码逻辑 | 读代码的人 |

**关键理解**：Rules 是给 AI 的——它不会像 ESLint 那样强制执行。Rules 告诉 AI **应该**怎么写；ESLint 保证代码**必须**这样写。两者互补，不是互替。

### 5.2 Rules vs `.cursorignore`

```ini
# .cursorignore
# 这些文件不被 Cursor 索引，AI 不会读取它们
node_modules/
.next/
dist/
*.min.js
*.lock
.codebuddy/

.cursorignore 阻止 AI 看到某些文件，Rules 告诉 AI 看到文件后怎么做。两者结合使用效果最好。

5.3 Rules vs `@` 引用

Rules：长期生效的约定，每次对话都加载
@file 引用：临时告诉 AI 参考某个特定文件

场景区分：

「这个项目用 React Hooks」→ 写进 Rules
「这个 PR 参考一下 src/examples/similar-feature.ts」→ 用 @file 引用

6. 团队共享 Rules 方案

6.1 Git 管理 Rules

# 推荐的 .cursor/ 目录结构
.cursor/
├── rules/
│   ├── frontend.md          # 前端规范（Git 追踪）
│   ├── backend.md           # 后端规范（Git 追踪）
│   ├── security.md          # 安全规范（Git 追踪）
│   └── local.md.example     # 本地配置模板（Git 追踪）
└── mcp.json                 # MCP 配置（Git 追踪）

# .gitignore
.cursor/rules/local.md        # 个人本地规则不提交

6.2 新人入职一键配置

#!/bin/bash
# setup-cursor-rules.sh
# 新成员入职时运行此脚本

REPO_URL="git@github.com:team/cursor-rules-templates.git"
TEMP_DIR=$(mktemp -d)

echo "📥 下载团队 Rules 模板..."
git clone "$REPO_URL" "$TEMP_DIR"

echo "📋 安装 Rules..."
cp "$TEMP_DIR/rules/"*.md .cursor/rules/

# 如果是前端开发者
if [ "$1" = "frontend" ]; then
    echo "🔧 应用前端专用配置..."
    cp "$TEMP_DIR/specializations/frontend.md" .cursor/rules/
fi

echo "✅ Cursor Rules 配置完成！"
rm -rf "$TEMP_DIR"

6.3 CI 中校验 Rules 合规性

# .github/workflows/cursor-rules-check.yml
name: Cursor Rules Compliance Check

on:
  pull_request:
    paths:
      - '.cursor/rules/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate Rules syntax
        run: |
          for f in .cursor/rules/*.md; do
            # 检查是否包含 frontmatter
            head -1 "$f" | grep -q '^---$' || echo "❌ $f: 缺少 frontmatter"
            # 检查是否包含 name 字段
            grep -q 'name:' "$f" || echo "❌ $f: 缺少 name 字段"
          done
      - name: Check for deprecated patterns
        run: |
          # 检查是否引用了已废弃的库或模式
          if grep -r 'class component' .cursor/rules/; then
            echo "❌ Rules 中引用了已废弃的 Class 组件"
            exit 1
          fi

7. 常见坑点排查（10 个）

7.1 Rules 写了但不生效

原因：globs 匹配问题。

排查：

# 检查你的文件是否被 glob 匹配
# 如果 globs 是 "**/*.tsx"，但你的文件是 .jsx，就不会匹配
ls src/**/*.tsx  # 确认文件存在

解决：放宽 globs 或检查文件路径是否正确。

7.2 AI 忽略部分 Rules

原因：Rules 太长（超过 500 行），AI 注意力被稀释。

解决：

每个 Rules 文件控制在 200 行以内
一个文件只覆盖一类规则
使用 globs 让 AI 只加载相关的 Rules

7.3 Rules 之间冲突

原因：多个 Rules 文件有矛盾的指令。

解决：

# 在 Rules 中明确优先级
name: project-override
description: 覆盖全局配置的项目级规则
priority: 10

7.4 Agent 模式下行为异常

原因：缺少 Agent 专用指令。

解决：为 Agent 模式单独写一个 Rules 文件：

name: agent-mode
description: Agent 模式下的行为约束
alwaysApply: true

# Agent 模式约束
- 写文件前先确认文件存在
- 修改超过 3 个文件时，先说明计划
- 操作完成后检查结果

7.5 Rules 更新后不生效

原因：Cursor 缓存了旧的 Rules。

解决：

Cmd+Shift+P → 「Developer: Reload Window」
如果还不行，关闭 Cursor 重新打开项目

7.6 团队 Rules 不一致

原因：团队成员各自修改本地的 Rules。

解决：

Rules 文件放入 Git 管理
CI 中校验 Rules 格式
定期 Review Rules 变更

7.7 Rules 太长导致加载慢

原因：Rules 总量超过 2000 行。

解决：

拆分 Rules 文件，用 globs 按需加载
只保留 AI 真正需要的指令
技术细节放到文档中，在 Rules 中只写「参考 docs/xxx.md」

7.8 过度约束导致 AI 创造力下降

原因：Rules 中全是「禁止」且没有给出替代方案。

解决：

# ❌ 差
- 禁止使用 any
- 禁止使用 var
- 禁止使用 class 组件

# ✅ 好
- 使用具体类型替代 any（如 unknown + 类型守卫）
- 使用 const/let 替代 var
- 使用函数式组件 + Hooks 替代 class 组件

7.9 中英文混用导致 AI 理解偏差

原因：Rules 中技术术语中英混杂。

解决：技术术语统一用英文，描述用中文。保持一致性。

# ✅ 好
- React 组件使用 function 定义
- 所有 API endpoint 返回 JSON 格式

# ❌ 差
- React 组件用 function 还是 arrow function 取决于场景
- 接口返回 JSON 还是 XML 看情况

7.10 忽略平台差异

原因：Rules 中写的路径和命令只在特定平台有效。

解决：

# 路径
- 使用正斜杠 `/`（Node.js 跨平台自动转换）
- 避免硬编码绝对路径

# 命令
- npm 脚本跨平台（不要直接写 bash 命令）
- 如需平台特定命令，注明适用的操作系统

8. 高级技巧

8.1 按分支动态切换 Rules

# 在 CI 中根据分支选择不同的 Rules
if [ "$GIT_BRANCH" = "production" ]; then
    cp .cursor/rules/production.md .cursor/rules/active/
elif [ "$GIT_BRANCH" = "staging" ]; then
    cp .cursor/rules/staging.md .cursor/rules/active/
fi

8.2 控制 AI 的「创造力」vs「规范性」

Rules 中可以设定「自由度」：

# 高自由度（允许 AI 自主发挥）
- 组件命名可以自选
- 变量名可以自选
- 实现方式可以自选

# 低自由度（严格要求）
- 组件必须放在 src/components//
- 变量名遵循 [具体命名规范]
- 使用 [具体库] 的 [具体 API]

8.3 Rules 性能优化

name: minimal-rules
description: 核心规则，保持简洁以减少 token 消耗

# 核心规则（精简版）
1. 技术栈：React 19 + TS + Tailwind
2. 组件：函数式 + Hooks
3. 样式：Tailwind 优先
4. API：src/lib/api.ts 统一调用
5. 禁止：Class 组件、any 类型、直接操作 DOM

精简版 Rules 只有 5 行核心指令，AI 加载快、理解准、执行稳。

> 写在最后：Cursor Rules 本质上是一种人机接口设计——你在为一个非人类的使用者（AI）写文档。写得越清晰、越精确、越简洁，AI 生成的代码就越符合你的预期。 > > 一个好的 Rules 体系不是一次性写完的，而是在和 AI 协作过程中不断迭代出来的——每当你发现 AI 生成了不符合预期的代码，就问自己：这条规则我写进 Rules 了吗？