Cursor Rules 是给 Agent 设定持久上下文的机制：把规则文件放进 .cursor/rules/，Agent 每次回答时都会把规则内容注入到提示词开头，确保代码风格、架构约定、项目特有知识得到一致执行。支持 .mdc 格式（带元数据）和纯 Markdown 的 AGENTS.md 两种写法。本文介绍四种规则类型、.mdc 文件格式、如何创建规则，以及何时用 Rules 而不是普通提示词。

Cursor Rules：给 AI 设定持久行为规则

每次开新对话，Agent 都是白板状态——不记得你上次说"要用 TypeScript strict 模式"，也不知道"组件文件一律放 src/components/"。Cursor Rules 解决这个问题：把这些约定写成规则文件，Agent 每次都会自动遵守。

---

四种规则类型

类型	作用域	位置
Project Rules	当前项目，可提交到 Git	.cursor/rules/ 目录
User Rules	你的所有项目	Cursor Settings > Rules
Team Rules	整个团队	Cursor 云同步或 Git
AGENTS.md	项目或子目录，简单指令	项目根目录或任意子目录

---

项目规则：.mdc 格式

.cursor/rules/ 目录下的 .mdc 文件是最灵活的规则格式，支持 YAML 元数据控制应用时机：

---
description: "前端组件规范和 API 验证标准"
alwaysApply: false
---

所有 React 组件必须使用函数式写法。
Props 必须定义 TypeScript interface，不得用 any。

三种应用模式

模式	配置	适用场景
始终应用	alwaysApply: true	全局约定（代码风格、禁止事项）
智能匹配	alwaysApply: false	根据上下文自动决定是否注入
文件模式	globs: ["src/**/*.ts"]	只对特定文件类型生效

示例：只对 TypeScript 文件应用的规则

---
description: "TypeScript 严格模式要求"
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

使用 TypeScript strict 模式。
所有函数参数和返回值必须有类型注解。

---

如何创建规则

方式一：在对话里用命令

输入 /create-rule，Agent 会根据你的描述生成规则文件并保存到 .cursor/rules/。

方式二：在设置里添加

Cursor Settings > Rules > "+ Add Rule"，填写规则名称和内容。

方式三：手动创建文件

直接在 .cursor/rules/ 目录下创建 .md 或 .mdc 文件，文件名即规则名。可以用子目录组织：

.cursor/rules/
├── general.mdc       # 通用约定
├── frontend/
│   ├── react.mdc     # React 规范
│   └── css.mdc       # 样式规范
└── backend/
    └── api.mdc       # API 规范

---

AGENTS.md：简化版规则

如果不需要元数据控制，直接在项目根目录创建 AGENTS.md，用普通 Markdown 写指令：

# 项目约定

- 使用 pnpm 管理依赖，禁止 npm install
- 提交前运行 pnpm test
- 所有 API 返回值必须处理错误情况

AGENTS.md 对子目录也有效：在 src/api/AGENTS.md 里写的规则，只在 Agent 处理 src/api/ 下的文件时生效。

---

规则生效原理

当规则被应用时，规则文件内容会插入到模型上下文开头，相当于每次对话自动附上这段系统提示。Agent 据此生成代码、解释编辑意图、辅助工作流。

注意事项：

• 规则越多，消耗的 token 越多——只保留真正有用的规则
• alwaysApply: true 的规则每次都注入，控制好数量
• 规则是普通文件，可以和代码一起提交到 Git，团队共享

---

与 Claude Code 的对比

	Cursor Rules	Claude Code
规则文件	.cursor/rules/*.mdc	CLAUDE.md
应用粒度	文件模式匹配 / 智能触发	手动 /skip 或层级继承
版本控制	可提交到 Git	可提交到 Git
简化写法	AGENTS.md	根目录 CLAUDE.md

Cursor Rules 的 globs 匹配更细粒度；Claude Code 的 CLAUDE.md 层级继承（子目录自动继承父目录规则）更直观。两者思路相同：用文件定义 AI 的"行为规范"。

---

常见问题

Q: 规则没有生效，怎么排查？

检查三点：① 文件在 .cursor/rules/ 目录下；② .mdc 格式的 frontmatter 没有语法错误；③ alwaysApply 或 globs 设置是否符合当前场景。也可以在对话里直接问 Agent "你有哪些规则在生效"。

Q: User Rules 和 Project Rules 哪个优先级更高？

两者都会注入，不互相覆盖。如果有冲突，Project Rules 通常因为更具体而被 Agent 优先遵守。

Q: 能不能把 .cursorrules 文件迁移到新格式？

可以。在聊天里运行 /migrate-to-skills 或 /create-rule，Agent 会帮你把旧的 .cursorrules 内容迁移成新格式。