规则

使用可复用且具作用域的指令来控制 Agent 模型的行为。

规则为 Agent 和 Inline Edit 提供系统级指令。可以把它们理解为项目的持久化上下文、偏好设置或工作流。

Cursor 支持四种类型的规则：

项目规则

存放于 .cursor/rules，受版本控制，并限定在你的代码库范围内。

用户规则

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

AGENTS.md

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

.cursorrules（旧版）

仍受支持，但已弃用。请改用项目规则。

规则的工作方式

大型语言模型在不同的补全之间不会保留记忆。规则在提示层面提供持久、可复用的上下文。

应用后，规则内容会被添加到模型上下文的开头。这能为 AI 提供一致的指导，用于生成代码、理解编辑，或协助处理工作流。

规则适用于 Chat 和 Inline Edit。已启用的规则会显示在 Agent 侧边栏。

项目规则

项目规则位于 .cursor/rules。每条规则都是一个文件，并纳入版本控制。它们可以通过路径模式限定作用范围、手动触发，或按相关性自动包含。各子目录也可以包含自己的 .cursor/rules 目录，仅作用于该文件夹。

使用项目规则可以：

• 编码与你代码库相关的领域知识
• 自动化项目特定的工作流程或模板
• 统一风格或架构决策

规则结构

每个规则文件使用 MDC (.mdc) 编写，这是一种同时支持元数据与正文内容的格式。通过类型下拉菜单控制规则的应用方式，该菜单会修改 description、globs、alwaysApply 属性。

规则类型	描述
Always	始终包含在模型上下文中
Auto Attached	当引用与某个 glob 模式匹配的文件时自动包含
Agent Requested	可供 AI 使用，由 AI 决定是否包含。必须提供描述
Manual	仅在使用 @ruleName 明确提及时才包含

---
description: RPC Service boilerplate
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 中生成一个新的规则文件。在设置里你可以查看所有规则及其状态。

生成规则

在对话中直接使用 /Generate Cursor Rules 命令生成规则。适用于你已经确定了代理的行为并希望复用这些设置的情况。

最佳实践

好的规则应当聚焦、可执行、范围清晰。

• 将规则控制在 500 行以内
• 把大型规则拆分成多个可组合的规则
• 提供具体示例或被引用的文件
• 避免模糊指导，让规则像清晰的内部文档一样
• 在聊天中重复使用相同提示时复用这些规则

示例

前端组件与 API 校验规范

这条规则为前端组件制定了规范：

在 components 目录工作时：

• 样式一律使用 Tailwind
• 动画使用 Framer Motion
• 遵循组件命名约定

这条规则同时对 API 端点进行校验约束：

在 API 目录中：

• 所有校验使用 zod
• 用 zod schema 定义返回类型
• 导出由 schema 生成的类型

Express 服务与 React 组件模板

这条规则提供 Express 服务模板：

创建 Express 服务时请使用该模板：

• 遵循 RESTful 原则
• 包含错误处理中间件
• 配置合理的日志记录

@express-service-template.ts

这条规则定义 React 组件结构：

React 组件应遵循以下结构：

• 顶部定义 Props 接口
• 组件以具名导出
• 样式放在底部

@component-template.tsx

开发流程自动化与文档生成

这条规则用于自动化应用分析：

当被要求分析应用时：

1. 通过 npm run dev 运行开发服务器
2. 从控制台获取日志
3. 提出性能改进建议

这条规则也用于生成文档：

帮助起草文档的方式：

• 提取代码注释
• 分析 README.md
• 生成 Markdown 文档

在 Cursor 中添加新设置

先在 @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 文件。对于只需要简单、易读指令、又不想引入结构化规则开销的项目，它再合适不过。

# Project Instructions

## Code Style
- Use TypeScript for all new files
- Prefer functional components in React
- Use snake_case for database columns

## Architecture
- Follow the repository pattern
- Keep business logic in service layers

用户规则

用户规则是在 Cursor Settings → Rules 中定义的全局偏好设置，适用于所有项目。它们是纯文本，特别适合设置偏好的沟通风格或编码规范：

Please reply in a concise style. Avoid unnecessary repetition or filler language.

.cursorrules（旧版）

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

常见问题

为什么我的规则没有生效？

检查规则类型。对于 Agent Requested，确保已填写描述。对于 Auto Attached，确保文件模式能匹配被引用的文件。

规则可以引用其他规则或文件吗？

可以。使用 @filename.ts 将文件纳入规则的上下文。

我可以在聊天里创建规则吗？

可以，使用 /Generate Cursor Rules 命令从聊天生成项目规则。如果启用了 Memories，会自动生成记忆。

规则会影响 Cursor Tab 或其他 AI 功能吗？

不会。规则只作用于 Agent 和 Inline Edit。