规则为 Agent 和 Inline Edit 提供系统级指令。可以把它们看作项目的持久化上下文、偏好或工作流。 Cursor 支持四种类型的规则：

Project Rules

存放在 .cursor/rules 中，纳入版本控制，作用域限定于你的代码库。

User Rules

全局作用于你的 Cursor 环境。在设置中定义，并始终生效。

AGENTS.md

以 Markdown 格式编写的 Agent 指令，是 .cursor/rules 的简洁替代方案。

.cursorrules (Legacy)

仍受支持，但已弃用。请改用 Project Rules。

​
规则如何运作

大型语言模型在不同补全之间不会保留记忆。规则在提示层面提供持久且可复用的上下文。 启用后，规则内容会被放在模型上下文的开头。这能为 AI 在生成代码、理解编辑或协助工作流时提供一致的指引。
在聊天上下文中应用的规则
规则适用于 Chat 和 Inline Edit。启用的规则会显示在 Agent 侧边栏。

​
项目规则

项目规则位于 .cursor/rules。每条规则都是一个文件，并纳入版本控制。它们可以通过路径模式限定作用范围、手动调用，或按相关性自动包含。子目录可以包含各自的 .cursor/rules 目录，仅作用于该文件夹。 使用项目规则来：
  • 编码与你的代码库相关的领域知识
  • 自动化项目特定的工作流或模板
  • 统一风格或架构决策

​
规则结构

每个规则文件使用 MDC（.mdc）编写，这是一种同时支持元数据与内容的格式。通过类型下拉菜单控制规则的应用方式，该菜单会修改 description、globs、alwaysApply 属性。
规则类型描述
Always始终包含在模型上下文中
Auto Attached当引用匹配某个 glob 模式的文件时自动包含
Agent Requested对 AI 可用，由其自行决定是否包含。必须提供描述
Manual仅在使用 @ruleName 明确提及时才会包含
---
description: RPC 服务模板
globs:
alwaysApply: false
---

- 定义服务时请使用我们的内部 RPC 模式
- 服务名一律使用 snake_case。

@service-template.ts

​
嵌套规则

把规则放在项目各处的 .cursor/rules 目录中进行组织。当引用某个目录中的文件时，该目录下的嵌套规则会自动生效。 
project/
  .cursor/rules/        # 项目级规则
  backend/
    server/
      .cursor/rules/    # 后端专用规则
  frontend/
    .cursor/rules/      # 前端专用规则

​
创建规则

通过执行 New Cursor Rule 命令，或前往 Cursor Settings > Rules 创建规则。这样会在 .cursor/rules 中生成一个新的规则文件。你可以在设置里查看所有规则及其状态。
简洁规则 vs 冗长规则的对比

​
生成规则

在对话中直接使用 /Generate Cursor Rules 命令来生成规则。适合在你已经确定了代理的行为并想要复用这些设置时使用。

​
最佳实践

好的规则应当聚焦、可执行、范围清晰。
  • 将规则控制在 500 行以内
  • 把大型规则拆分成多个可组合的小规则
  • 提供具体示例或引用文件
  • 避免模糊的指导；像清晰的内部文档那样写规则
  • 在聊天里重复使用提示时复用这些规则

​
示例

该规则为前端组件提供规范：在 components 目录开发时：
  • 样式统一使用 Tailwind
  • 动效使用 Framer Motion
  • 遵循组件命名约定
该规则同时强制 API 端点的校验：在 API 目录：
  • 所有校验使用 zod
  • 使用 zod schema 定义返回类型
  • 导出由 schema 生成的类型
该规则提供 Express 服务模板：创建 Express 服务时使用该模板：
  • 遵循 RESTful 原则
  • 包含错误处理中间件
  • 配置完善的日志记录
@express-service-template.ts该规则定义 React 组件的结构：React 组件应遵循以下布局：
  • 顶部定义 Props 接口
  • 组件以具名导出
  • 样式置于底部
@component-template.tsx
该规则用于自动化应用分析：当被要求分析应用时：
  1. 使用 npm run dev 启动开发服务器
  2. 从控制台获取日志
  3. 提出性能优化建议
该规则也有助于生成文档：协助起草文档时请：
  • 提取代码注释
  • 分析 README.md
  • 生成 Markdown 文档
先在 @reactiveStorageTypes.ts 中创建一个可切换的属性。在 @reactiveStorageService.tsx 的 INIT_APPLICATION_USER_PERSISTENT_STORAGE 中添加默认值。对于 beta 功能，在 @settingsBetaTab.tsx 中添加开关；否则在 @settingsGeneralTab.tsx 中添加。通用复选框可作为 <SettingsSubSection> 添加。参考文件其余部分的示例。
<SettingsSubSection
				label="Your feature name"
				description="Your feature description"
				value={
					vsContext.reactiveStorageService.applicationUserPersistentStorage
						.myNewProperty ?? false
				}
				onChange={(newVal) => {
					vsContext.reactiveStorageService.setApplicationUserPersistentStorage(
						'myNewProperty',
						newVal
					);
				}}
			/>
在应用中使用时，导入 reactiveStorageService 并读取该属性：
const flagIsEnabled = vsContext.reactiveStorageService.applicationUserPersistentStorage.myNewProperty
来自各类服务商与框架的示例非常多。社区贡献的规则可在众包合集与在线仓库中找到。

​
AGENTS.md

AGENTS.md 是一个用于定义 Agent 指令的简单 Markdown 文件。把它放在项目根目录，作为 .cursor/rules 的替代方案，适合简单直观的用法。 与 Project Rules 不同，AGENTS.md 只是一个纯 Markdown 文件，没有元数据或复杂配置。对那些只需要简单、易读的指令、又不想承担结构化规则开销的项目来说，它再合适不过了。 
# 项目指南

## 代码风格
- 所有新文件使用 TypeScript
- 在 React 中优先使用函数组件
- 数据库列名使用 snake_case

## 架构
- 遵循仓储（Repository）模式
- 将业务逻辑放在服务层

​
用户规则

“用户规则”是在 Cursor Settings → Rules 中定义的全局偏好设置，适用于所有项目。规则以纯文本编写，特别适合用来设定偏好的交流风格或编码规范： 
请以简洁的风格回复。避免不必要的重复或冗余。

​
.cursorrules（旧版）

项目根目录中的 .cursorrules 文件仍受支持，但即将被弃用。我们建议迁移到 Project Rules，以获得更强的可控性、灵活性和可见性。

​
常见问题

检查规则类型。对于 Agent Requested，确保已填写描述。对于 Auto Attached，确保文件模式匹配被引用的文件。
可以。使用 @filename.ts 把文件包含进规则的上下文。
可以，使用 /Generate Cursor Rules 命令在聊天中生成项目规则。若启用了 Memories，会自动生成记忆。
不会。规则只适用于 Agent 和 Inline Edit。