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/ 目录 > 项目根 .cursorrules > 全局 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) -> 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 了吗?
版权声明
本文原创发布于 zhiqu.ac,未经书面许可禁止全文转载、采集、商用;转载必须完整标注原文链接、作者。
0 条评论