Cursor Rules 规则系统

Rules 让 AI 持续"懂"你的项目规范——配好后 PR 评审意见能从 10+ 条降至 2–3 条。

.mdc 文件结构

规则文件存放在 .cursor/rules/ 目录下，每个 .mdc 文件包含 YAML frontmatter 和 Markdown 正文：

---
description: TypeScript 编码规范
globs: "**/*.ts,**/*.tsx"
alwaysApply: false
---

- 使用 `interface` 而非 `type` 定义对象类型
- 禁止使用 `any`，用 `unknown` 替代
- 异步函数必须有错误处理

字段	说明
`description`	规则描述，帮助 AI 判断是否应用此规则
`globs`	文件匹配模式，决定 AutoAttach 的触发范围
`alwaysApply`	是否始终注入上下文

早期的 .cursorrules 单文件仍兼容，但推荐迁移到 .cursor/rules/*.mdc，获得模块化和条件触发能力。

四种触发类型

类型	配置	适用场景
Always	`alwaysApply: true`	全局规范（技术栈、编码风格）
AutoAttach	`globs: "*/.test.ts"`	特定文件类型（测试、API 路由）
Agent Request	仅有 `description`，无 `globs`	AI 按描述自行判断是否需要
Manual	无 `description`，无 `globs`	通过 `@ruleName` 手动引用

配置示例

项目概览（Always）

---
description: 项目基本信息
alwaysApply: true
---

- 技术栈：Next.js 15 + TypeScript + Tailwind CSS + Prisma
- 包管理器：pnpm | Node 22+
- 数据库：PostgreSQL
- 目录：src/app/(路由) | src/components/(组件) | src/lib/(工具) | src/server/(服务端)

测试规范（AutoAttach）

---
description: 单元测试编写规范
globs: "**/*.test.ts,**/*.test.tsx,**/*.spec.ts"
alwaysApply: false
---

- 使用 Vitest，测试文件与源文件同目录
- 描述用中文，测试函数名用英文
- 每个测试只验证一个行为

Git 提交（Agent Request）

---
description: Git 提交规范
alwaysApply: false
---

提交格式：type(scope): description
type: feat | fix | refactor | docs | test | chore

最佳实践

用数字前缀控制优先级：

.cursor/rules/
├── 001-project-overview.mdc
├── 002-coding-style.mdc
├── 010-react-components.mdc
├── 020-testing.mdc
└── 099-git-commits.mdc

原则	说明
控制篇幅	单文件不超 500 行，过长则拆分
给出示例	附带正确/错误代码示例
具体明确	"使用 `interface`" 优于 "用合适的方式"
团队共享	`.cursor/rules/` 提交到 Git

注意

规则过多反而降低 AI 表现——上下文被规则占满，留给代码的空间就少了。只保留真正必要的规则。

Rules 规则系统