规则

规则为智能体提供系统级指令，将提示词、脚本等内容整合在一起，便于在团队内管理和共享工作流。

Cursor 支持四类规则：

项目规则

存储在 .cursor/rules 中，纳入版本控制，且仅适用于您的代码库。

用户规则

适用于整个 Cursor 环境，由智能体 (聊天) 使用。

团队规则

在仪表盘中管理的团队级规则。适用于团队版和企业版方案。

AGENTS.md

采用 Markdown 格式的智能体指令，是 .cursor/rules 的简易替代方案。

规则的工作方式

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

应用规则时，其内容会被添加到模型上下文的起始位置。这为 AI 在生成代码、理解编辑或协助处理工作流程时提供一致的指导。

项目规则

项目规则以 .mdc 文件的形式存放在 .cursor/rules 中，并纳入版本控制。它们可以通过路径模式限定适用范围、手动调用，或根据相关性自动包含。

使用项目规则可以：

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

规则文件结构

每条规则都是一个 .mdc 文件，文件名可以随意。项目规则必须使用 .mdc 扩展名。.cursor/rules 中的普通 .md 文件会被规则系统忽略，因为它没有用于指定 description、globs 和 alwaysApply 的 frontmatter。如果你更喜欢纯 markdown，请改用 AGENTS.md。

.cursor/rules/  react-patterns.mdc       # 识别为项目规则  api-guidelines.md        # 已忽略（扩展名错误）  frontend/                # 可在文件夹中组织规则    components.mdc

规则结构

每条规则都是一个带有 frontmatter 元数据和内容的 markdown 文件。通过类型下拉菜单控制规则的应用方式，该菜单会更改 description、globs、alwaysApply 属性。

规则类型	描述
`Always Apply`	应用于每个聊天会话
`Apply Intelligently`	当智能体根据描述判断其相关时应用
`Apply to Specific Files`	当文件匹配指定模式时应用
`Apply Manually`	在聊天中被 @ 提及时应用 (例如 `@my-rule`)

在底层，这三个 frontmatter 字段会共同决定何时包含某条规则：

`alwaysApply`	`description`	`globs`	行为
`true`	—	—	始终包含。会忽略 globs 和 description。
`false`	—	已提供	当匹配的文件位于上下文中时自动附加。
`false`	已提供	省略	智能体会读取 description，并在相关时引入该规则。
`false`	省略	省略	仅当你在聊天中用 `@` 提及该规则时才会包含。

Always applied

---alwaysApply: true---- 所有源文件必须包含公司版权声明头- 当您对实现细节不确定时，请在提出更改建议之前阅读相关源文件- 切勿修改 `dist/` 或 `build/` 目录中的生成文件

Auto-attached by file pattern

---globs: src/components/**/*.tsxalwaysApply: false---- Use named exports, not default exports- Co-locate styles in a module CSS file next to the component- Keep components under 200 lines. Extract subcomponents into the same  directory when a file grows beyond that- Prefer composition over prop drilling. Pass children or render props  instead of threading data through multiple layers

Agent-selected based on description

---description: RPC service conventions and patterns for the backendalwaysApply: false---- 在 `src/services/` 目录下为每个服务定义独立文件- 在将数据传递给内部函数之前，始终在服务边界处验证输入- 返回包含 `code` 和 `message` 字段的结构化错误对象，  切勿抛出原始字符串- 创建新服务时，添加 `@service-template.ts` 参考文件以使用标准样板代码

Manual — only via @-mention

---alwaysApply: false---- 每次数据库迁移必须同时包含 `up` 和 `down` 函数，以便完全回滚- 切勿原地修改列类型。请添加新列、回填数据，然后在单独的迁移中删除旧列- 参考模板了解预期的文件结构@migration-template.sql

Glob 模式示例

使用 globs 可将规则限定为仅适用于特定文件或目录。多个模式之间用逗号分隔。

模式	匹配内容
`*`	任意单个文件名片段
`**`	任意层级的目录 (递归)
`*.ts`	根目录中的所有 `.ts` 文件
`*/.ts`	任意目录中的所有 `.ts` 文件
`src/**`	`src/` 下任意位置的所有文件
`src/*/.tsx`	`src/` 下任意位置的所有 `.tsx` 文件
`docs/*/.md, docs/*/.mdx`	`docs/` 下的 `.md` 和 `.mdx` 文件 (以逗号分隔)
`tailwind.config.*`	具有任意扩展名的 `tailwind.config`

创建规则

创建规则有两种方式：

在对话中使用 /create-rule：在智能体中输入 /create-rule 并描述你的需求。智能体会生成带有正确 frontmatter 的规则文件，并将其保存到 .cursor/rules。
从自定义中创建：在侧边栏中打开 自定义，前往规则，然后点击 添加规则。这会在 .cursor/rules 中创建一个新的规则文件。你可以在自定义中查看所有规则及其状态。

最佳实践

好的规则应当聚焦、可操作且范围清晰。

将规则控制在 500 行以内
将大型规则拆分成多个可组合的规则
提供具体示例或引用的文件
避免含糊其辞；像写清晰的内部文档那样来写规则
在聊天中重复提示时复用规则
引用文件而不是复制其内容——这可以让规则保持简短，并避免因代码变更而变得过时

规则中应避免的做法

整份复制风格指南：这类工作交给 linter 更合适。Agent 已经了解常见的风格约定。
试图穷举所有可能的命令：Agent 已经熟悉 npm、git、pytest 等常用工具。
为极少出现的边缘情况添加说明：让规则聚焦在你经常使用的模式上。
重复你代码库中已有的内容：引用规范示例，而不是复制代码。

先从简单的规则开始。只有当你发现 Agent 一再犯同样的错误时，再新增规则。在真正理解你的模式之前，不要过度优化。

把规则提交到 git，让整个团队都能受益。当你看到 Agent 出错时，就更新对应规则。你甚至可以在 GitHub 的 issue 或 PR 中 @cursor，让 Agent 帮你更新规则。

规则文件格式

每条规则都保存在一个包含 frontmatter 元数据和正文内容的 Markdown 文件中。frontmatter 元数据用于控制规则的应用方式，正文内容则是规则本身。

---description: "此规则提供前端组件和 API 验证的标准"alwaysApply: false---...rest of the rule content

如果 alwaysApply 为 true，则该规则会应用于每个会话。否则，将把该规则的描述发送给 Cursor Agent，由其决定是否需要应用该规则。

示例

此规则为前端组件提供规范：

在 components 目录工作时：

一律使用 Tailwind 编写样式
使用 Framer Motion 实现动画
遵循组件命名约定

此规则对 API 端点强制进行校验：

在 API 目录中：

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

此规则提供 Express 服务模板：

创建 Express 服务时使用此模板：

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

@express-service-template.ts

此规则定义 React 组件结构：

React 组件应遵循以下布局：

顶部为 Props 接口
组件使用命名导出
样式放在底部

@component-template.tsx

此规则自动化应用分析：

在被要求分析应用时：

使用 npm run dev 启动开发服务器
从控制台获取日志
提出性能优化建议

此规则帮助生成文档：

通过以下方式辅助起草文档：

提取代码注释
分析 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;

不同的提供方和框架都提供了示例。社区贡献的规则可以在各类众包集合和线上代码仓库中找到。

团队规则

Team 和 Enterprise 计划可以通过 Cursor 仪表盘在整个组织范围内创建和实施规则。管理员可以配置每条规则对团队成员是否为必选。

团队规则与其他规则类型协同工作，并优先生效，以确保组织标准在所有项目中得到贯彻。它们提供了一种强大的方式，在无需逐个单独设置或配置的情况下，确保整个团队在编码规范、实践和工作流方面保持一致。

管理团队规则

团队管理员可以直接在 Cursor 仪表板上创建和管理团队规则：

创建团队规则后，这些规则会自动对所有团队成员生效，并在仪表板中显示：

激活与强制执行

立即启用此规则：选中后，此规则在创建后会立即生效。未选中时，此规则将作为草稿保存，在你稍后启用前不会生效。
强制执行此规则：启用后，此规则对所有团队成员一律生效，且无法在自定义中被关闭。未强制执行时，团队成员可以在自定义的 Team Rules 下将此规则关闭。

默认情况下，未强制执行的 Team Rules 可以被用户关闭。使用 强制执行此规则 来阻止用户关闭该规则。

团队规则的格式及其应用方式

内容：团队规则是自由格式文本，不使用项目规则的文件夹结构。
Glob 模式：团队规则支持 glob 模式按文件范围生效。当设置了 glob 模式时 (例如 **/*.py) ，只有当匹配文件在上下文中时才会应用该规则。没有 glob 模式的规则会应用于每一次对话。
适用范围：当团队规则被启用 (且未被用户禁用，除非被设为强制执行) 时，它会被包含在该团队所有代码仓库和项目中的智能体 (Chat) 模型上下文中。
优先级：规则按以下顺序应用：团队规则 → 项目规则 → 用户规则。所有适用规则会被合并；当指导冲突时，较前的来源优先。

一些团队将强制规则作为内部合规流程的一部分。虽然这是受支持的用法，但 AI 指导不应成为你唯一的安全控制措施。

导入规则

可以从外部来源导入规则，以复用现有配置或引入其他工具的规则。

远程规则 (通过 GitHub)

从你有访问权限的任何 GitHub 仓库 (公共或私有) 直接导入规则。

在侧边栏中打开 自定义
前往 Rules，然后点击 Add Rule
选择 Remote Rule (Github)
粘贴包含这些规则的 GitHub 仓库 URL。Cursor 会扫描仓库中的所有 .mdc 文件。
Cursor 会拉取这些规则并将其同步到你的项目中

规则将放置在 .cursor/rules/imported/<repoName> 中。规则也会保留其相对路径，因此 dir/rule.mdc 将被导入为 .cursor/rule/imported/<repoName>/dir/rule.mdc。

AGENTS.md

AGENTS.md 是一个用于定义 Agent 指令的简单 markdown 文件。你可以将它放在项目根目录中，作为 .cursor/rules 的替代方案，适用于简单直接的用例。

与 Project Rules 不同，AGENTS.md 是一个不带元数据或复杂配置的纯 markdown 文件。它非常适合只需要简单、易读指令，而无需承受结构化规则开销的项目。

Cursor 在项目根目录和子目录中都支持 AGENTS.md。

# 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

改进

现在支持在子目录中使用嵌套的 AGENTS.md 文件。你可以在项目的任意子目录中放置 AGENTS.md 文件，在处理该目录或其子目录中的文件时，它们会自动生效。

这可以让你根据当前正在处理的代码库部分，更精细地控制 agent 指令：

project/  AGENTS.md              # 全局指令  frontend/    AGENTS.md            # 前端专用指令    components/      AGENTS.md          # 组件专用指令  backend/    AGENTS.md            # 后端专用指令

来自嵌套 AGENTS.md 文件的指令会与父目录中的指令合并，更具体的指令会优先生效。

用户规则

用户规则是在 自定义 → 规则 中定义的全局首选项，适用于所有项目。它们会被智能体 (Chat) 使用，非常适合用来设定偏好的沟通风格或编码规范：

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

常见问题

检查规则类型。对于 Apply Intelligently，确保已设置描述。对于 Apply to Specific Files，确保文件模式与被引用的文件匹配。

可以。使用 @filename.ts 将文件包含到规则的上下文中。你也可以在聊天中 @提及规则以手动应用它们。

可以，你可以让智能体为你创建一个新规则。

不会。规则不会影响 Cursor Tab 或其他 AI 功能。

不会。用户规则不会应用到 Inline Edit (Cmd/Ctrl+K) 。它们只会被智能体 (Chat) 使用。

规则

规则为智能体提供系统级指令，将提示词、脚本等内容整合在一起，便于在团队内管理和共享工作流。

Cursor 支持四类规则：

项目规则

存储在 .cursor/rules 中，纳入版本控制，且仅适用于您的代码库。

用户规则

适用于整个 Cursor 环境，由智能体 (聊天) 使用。

团队规则

在仪表盘中管理的团队级规则。适用于团队版和企业版方案。

AGENTS.md

采用 Markdown 格式的智能体指令，是 .cursor/rules 的简易替代方案。

规则的工作方式

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

应用规则时，其内容会被添加到模型上下文的起始位置。这为 AI 在生成代码、理解编辑或协助处理工作流程时提供一致的指导。

项目规则

项目规则以 .mdc 文件的形式存放在 .cursor/rules 中，并纳入版本控制。它们可以通过路径模式限定适用范围、手动调用，或根据相关性自动包含。

使用项目规则可以：

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

规则文件结构

.cursor/rules/  react-patterns.mdc       # 识别为项目规则  api-guidelines.md        # 已忽略（扩展名错误）  frontend/                # 可在文件夹中组织规则    components.mdc

规则结构

规则类型	描述
`Always Apply`	应用于每个聊天会话
`Apply Intelligently`	当智能体根据描述判断其相关时应用
`Apply to Specific Files`	当文件匹配指定模式时应用
`Apply Manually`	在聊天中被 @ 提及时应用 (例如 `@my-rule`)

在底层，这三个 frontmatter 字段会共同决定何时包含某条规则：

`alwaysApply`	`description`	`globs`	行为
`true`	—	—	始终包含。会忽略 globs 和 description。
`false`	—	已提供	当匹配的文件位于上下文中时自动附加。
`false`	已提供	省略	智能体会读取 description，并在相关时引入该规则。
`false`	省略	省略	仅当你在聊天中用 `@` 提及该规则时才会包含。

Always applied

---alwaysApply: true---- 所有源文件必须包含公司版权声明头- 当您对实现细节不确定时，请在提出更改建议之前阅读相关源文件- 切勿修改 `dist/` 或 `build/` 目录中的生成文件

Auto-attached by file pattern

---globs: src/components/**/*.tsxalwaysApply: false---- Use named exports, not default exports- Co-locate styles in a module CSS file next to the component- Keep components under 200 lines. Extract subcomponents into the same  directory when a file grows beyond that- Prefer composition over prop drilling. Pass children or render props  instead of threading data through multiple layers

Agent-selected based on description

---description: RPC service conventions and patterns for the backendalwaysApply: false---- 在 `src/services/` 目录下为每个服务定义独立文件- 在将数据传递给内部函数之前，始终在服务边界处验证输入- 返回包含 `code` 和 `message` 字段的结构化错误对象，  切勿抛出原始字符串- 创建新服务时，添加 `@service-template.ts` 参考文件以使用标准样板代码

Manual — only via @-mention

---alwaysApply: false---- 每次数据库迁移必须同时包含 `up` 和 `down` 函数，以便完全回滚- 切勿原地修改列类型。请添加新列、回填数据，然后在单独的迁移中删除旧列- 参考模板了解预期的文件结构@migration-template.sql

Glob 模式示例

使用 globs 可将规则限定为仅适用于特定文件或目录。多个模式之间用逗号分隔。

模式	匹配内容
`*`	任意单个文件名片段
`**`	任意层级的目录 (递归)
`*.ts`	根目录中的所有 `.ts` 文件
`*/.ts`	任意目录中的所有 `.ts` 文件
`src/**`	`src/` 下任意位置的所有文件
`src/*/.tsx`	`src/` 下任意位置的所有 `.tsx` 文件
`docs/*/.md, docs/*/.mdx`	`docs/` 下的 `.md` 和 `.mdx` 文件 (以逗号分隔)
`tailwind.config.*`	具有任意扩展名的 `tailwind.config`

创建规则

创建规则有两种方式：

在对话中使用 /create-rule：在智能体中输入 /create-rule 并描述你的需求。智能体会生成带有正确 frontmatter 的规则文件，并将其保存到 .cursor/rules。
从自定义中创建：在侧边栏中打开 自定义，前往规则，然后点击 添加规则。这会在 .cursor/rules 中创建一个新的规则文件。你可以在自定义中查看所有规则及其状态。

最佳实践

好的规则应当聚焦、可操作且范围清晰。

将规则控制在 500 行以内
将大型规则拆分成多个可组合的规则
提供具体示例或引用的文件
避免含糊其辞；像写清晰的内部文档那样来写规则
在聊天中重复提示时复用规则
引用文件而不是复制其内容——这可以让规则保持简短，并避免因代码变更而变得过时

规则中应避免的做法

整份复制风格指南：这类工作交给 linter 更合适。Agent 已经了解常见的风格约定。
试图穷举所有可能的命令：Agent 已经熟悉 npm、git、pytest 等常用工具。
为极少出现的边缘情况添加说明：让规则聚焦在你经常使用的模式上。
重复你代码库中已有的内容：引用规范示例，而不是复制代码。

先从简单的规则开始。只有当你发现 Agent 一再犯同样的错误时，再新增规则。在真正理解你的模式之前，不要过度优化。

把规则提交到 git，让整个团队都能受益。当你看到 Agent 出错时，就更新对应规则。你甚至可以在 GitHub 的 issue 或 PR 中 @cursor，让 Agent 帮你更新规则。

规则文件格式

每条规则都保存在一个包含 frontmatter 元数据和正文内容的 Markdown 文件中。frontmatter 元数据用于控制规则的应用方式，正文内容则是规则本身。

---description: "此规则提供前端组件和 API 验证的标准"alwaysApply: false---...rest of the rule content

如果 alwaysApply 为 true，则该规则会应用于每个会话。否则，将把该规则的描述发送给 Cursor Agent，由其决定是否需要应用该规则。

示例

此规则为前端组件提供规范：

在 components 目录工作时：

一律使用 Tailwind 编写样式
使用 Framer Motion 实现动画
遵循组件命名约定

此规则对 API 端点强制进行校验：

在 API 目录中：

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

此规则提供 Express 服务模板：

创建 Express 服务时使用此模板：

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

@express-service-template.ts

此规则定义 React 组件结构：

React 组件应遵循以下布局：

顶部为 Props 接口
组件使用命名导出
样式放在底部

@component-template.tsx

此规则自动化应用分析：

在被要求分析应用时：

使用 npm run dev 启动开发服务器
从控制台获取日志
提出性能优化建议

此规则帮助生成文档：

通过以下方式辅助起草文档：

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

首先在 @reactiveStorageTypes.ts 中创建一个需要切换的属性。

在 @reactiveStorageService.tsx 中的 INIT_APPLICATION_USER_PERSISTENT_STORAGE 里添加该属性的默认值。

<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;

不同的提供方和框架都提供了示例。社区贡献的规则可以在各类众包集合和线上代码仓库中找到。

团队规则

Team 和 Enterprise 计划可以通过 Cursor 仪表盘在整个组织范围内创建和实施规则。管理员可以配置每条规则对团队成员是否为必选。

管理团队规则

团队管理员可以直接在 Cursor 仪表板上创建和管理团队规则：

创建团队规则后，这些规则会自动对所有团队成员生效，并在仪表板中显示：

激活与强制执行

立即启用此规则：选中后，此规则在创建后会立即生效。未选中时，此规则将作为草稿保存，在你稍后启用前不会生效。
强制执行此规则：启用后，此规则对所有团队成员一律生效，且无法在自定义中被关闭。未强制执行时，团队成员可以在自定义的 Team Rules 下将此规则关闭。

默认情况下，未强制执行的 Team Rules 可以被用户关闭。使用 强制执行此规则 来阻止用户关闭该规则。

团队规则的格式及其应用方式

内容：团队规则是自由格式文本，不使用项目规则的文件夹结构。
Glob 模式：团队规则支持 glob 模式按文件范围生效。当设置了 glob 模式时 (例如 **/*.py) ，只有当匹配文件在上下文中时才会应用该规则。没有 glob 模式的规则会应用于每一次对话。
适用范围：当团队规则被启用 (且未被用户禁用，除非被设为强制执行) 时，它会被包含在该团队所有代码仓库和项目中的智能体 (Chat) 模型上下文中。
优先级：规则按以下顺序应用：团队规则 → 项目规则 → 用户规则。所有适用规则会被合并；当指导冲突时，较前的来源优先。

一些团队将强制规则作为内部合规流程的一部分。虽然这是受支持的用法，但 AI 指导不应成为你唯一的安全控制措施。

导入规则

可以从外部来源导入规则，以复用现有配置或引入其他工具的规则。

远程规则 (通过 GitHub)

从你有访问权限的任何 GitHub 仓库 (公共或私有) 直接导入规则。

在侧边栏中打开 自定义
前往 Rules，然后点击 Add Rule
选择 Remote Rule (Github)
粘贴包含这些规则的 GitHub 仓库 URL。Cursor 会扫描仓库中的所有 .mdc 文件。
Cursor 会拉取这些规则并将其同步到你的项目中

规则将放置在 .cursor/rules/imported/<repoName> 中。规则也会保留其相对路径，因此 dir/rule.mdc 将被导入为 .cursor/rule/imported/<repoName>/dir/rule.mdc。

AGENTS.md

AGENTS.md 是一个用于定义 Agent 指令的简单 markdown 文件。你可以将它放在项目根目录中，作为 .cursor/rules 的替代方案，适用于简单直接的用例。

与 Project Rules 不同，AGENTS.md 是一个不带元数据或复杂配置的纯 markdown 文件。它非常适合只需要简单、易读指令，而无需承受结构化规则开销的项目。

Cursor 在项目根目录和子目录中都支持 AGENTS.md。

# 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

改进

这可以让你根据当前正在处理的代码库部分，更精细地控制 agent 指令：

project/  AGENTS.md              # 全局指令  frontend/    AGENTS.md            # 前端专用指令    components/      AGENTS.md          # 组件专用指令  backend/    AGENTS.md            # 后端专用指令

来自嵌套 AGENTS.md 文件的指令会与父目录中的指令合并，更具体的指令会优先生效。

用户规则

用户规则是在 自定义 → 规则 中定义的全局首选项，适用于所有项目。它们会被智能体 (Chat) 使用，非常适合用来设定偏好的沟通风格或编码规范：

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

常见问题

检查规则类型。对于 Apply Intelligently，确保已设置描述。对于 Apply to Specific Files，确保文件模式与被引用的文件匹配。

可以。使用 @filename.ts 将文件包含到规则的上下文中。你也可以在聊天中 @提及规则以手动应用它们。

可以，你可以让智能体为你创建一个新规则。

不会。规则不会影响 Cursor Tab 或其他 AI 功能。

不会。用户规则不会应用到 Inline Edit (Cmd/Ctrl+K) 。它们只会被智能体 (Chat) 使用。

规则

规则为智能体提供系统级指令，将提示词、脚本等内容整合在一起，便于在团队内管理和共享工作流。

Cursor 支持四类规则：

项目规则

存储在 .cursor/rules 中，纳入版本控制，且仅适用于您的代码库。

用户规则

适用于整个 Cursor 环境，由智能体 (聊天) 使用。

团队规则

在仪表盘中管理的团队级规则。适用于团队版和企业版方案。

AGENTS.md

采用 Markdown 格式的智能体指令，是 .cursor/rules 的简易替代方案。

规则的工作方式

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

应用规则时，其内容会被添加到模型上下文的起始位置。这为 AI 在生成代码、理解编辑或协助处理工作流程时提供一致的指导。

项目规则

项目规则以 .mdc 文件的形式存放在 .cursor/rules 中，并纳入版本控制。它们可以通过路径模式限定适用范围、手动调用，或根据相关性自动包含。

使用项目规则可以：

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

规则文件结构

.cursor/rules/  react-patterns.mdc       # 识别为项目规则  api-guidelines.md        # 已忽略（扩展名错误）  frontend/                # 可在文件夹中组织规则    components.mdc

规则结构

规则类型	描述
`Always Apply`	应用于每个聊天会话
`Apply Intelligently`	当智能体根据描述判断其相关时应用
`Apply to Specific Files`	当文件匹配指定模式时应用
`Apply Manually`	在聊天中被 @ 提及时应用 (例如 `@my-rule`)

在底层，这三个 frontmatter 字段会共同决定何时包含某条规则：

`alwaysApply`	`description`	`globs`	行为
`true`	—	—	始终包含。会忽略 globs 和 description。
`false`	—	已提供	当匹配的文件位于上下文中时自动附加。
`false`	已提供	省略	智能体会读取 description，并在相关时引入该规则。
`false`	省略	省略	仅当你在聊天中用 `@` 提及该规则时才会包含。

Always applied

---alwaysApply: true---- 所有源文件必须包含公司版权声明头- 当您对实现细节不确定时，请在提出更改建议之前阅读相关源文件- 切勿修改 `dist/` 或 `build/` 目录中的生成文件

Auto-attached by file pattern

---globs: src/components/**/*.tsxalwaysApply: false---- Use named exports, not default exports- Co-locate styles in a module CSS file next to the component- Keep components under 200 lines. Extract subcomponents into the same  directory when a file grows beyond that- Prefer composition over prop drilling. Pass children or render props  instead of threading data through multiple layers

Agent-selected based on description

---description: RPC service conventions and patterns for the backendalwaysApply: false---- 在 `src/services/` 目录下为每个服务定义独立文件- 在将数据传递给内部函数之前，始终在服务边界处验证输入- 返回包含 `code` 和 `message` 字段的结构化错误对象，  切勿抛出原始字符串- 创建新服务时，添加 `@service-template.ts` 参考文件以使用标准样板代码

Manual — only via @-mention

---alwaysApply: false---- 每次数据库迁移必须同时包含 `up` 和 `down` 函数，以便完全回滚- 切勿原地修改列类型。请添加新列、回填数据，然后在单独的迁移中删除旧列- 参考模板了解预期的文件结构@migration-template.sql

Glob 模式示例

使用 globs 可将规则限定为仅适用于特定文件或目录。多个模式之间用逗号分隔。

模式	匹配内容
`*`	任意单个文件名片段
`**`	任意层级的目录 (递归)
`*.ts`	根目录中的所有 `.ts` 文件
`*/.ts`	任意目录中的所有 `.ts` 文件
`src/**`	`src/` 下任意位置的所有文件
`src/*/.tsx`	`src/` 下任意位置的所有 `.tsx` 文件
`docs/*/.md, docs/*/.mdx`	`docs/` 下的 `.md` 和 `.mdx` 文件 (以逗号分隔)
`tailwind.config.*`	具有任意扩展名的 `tailwind.config`

创建规则

创建规则有两种方式：

在对话中使用 /create-rule：在智能体中输入 /create-rule 并描述你的需求。智能体会生成带有正确 frontmatter 的规则文件，并将其保存到 .cursor/rules。
从自定义中创建：在侧边栏中打开 自定义，前往规则，然后点击 添加规则。这会在 .cursor/rules 中创建一个新的规则文件。你可以在自定义中查看所有规则及其状态。

最佳实践

好的规则应当聚焦、可操作且范围清晰。

将规则控制在 500 行以内
将大型规则拆分成多个可组合的规则
提供具体示例或引用的文件
避免含糊其辞；像写清晰的内部文档那样来写规则
在聊天中重复提示时复用规则
引用文件而不是复制其内容——这可以让规则保持简短，并避免因代码变更而变得过时

规则中应避免的做法

整份复制风格指南：这类工作交给 linter 更合适。Agent 已经了解常见的风格约定。
试图穷举所有可能的命令：Agent 已经熟悉 npm、git、pytest 等常用工具。
为极少出现的边缘情况添加说明：让规则聚焦在你经常使用的模式上。
重复你代码库中已有的内容：引用规范示例，而不是复制代码。

先从简单的规则开始。只有当你发现 Agent 一再犯同样的错误时，再新增规则。在真正理解你的模式之前，不要过度优化。

把规则提交到 git，让整个团队都能受益。当你看到 Agent 出错时，就更新对应规则。你甚至可以在 GitHub 的 issue 或 PR 中 @cursor，让 Agent 帮你更新规则。

规则文件格式

每条规则都保存在一个包含 frontmatter 元数据和正文内容的 Markdown 文件中。frontmatter 元数据用于控制规则的应用方式，正文内容则是规则本身。

---description: "此规则提供前端组件和 API 验证的标准"alwaysApply: false---...rest of the rule content

如果 alwaysApply 为 true，则该规则会应用于每个会话。否则，将把该规则的描述发送给 Cursor Agent，由其决定是否需要应用该规则。

示例

此规则为前端组件提供规范：

在 components 目录工作时：

一律使用 Tailwind 编写样式
使用 Framer Motion 实现动画
遵循组件命名约定

此规则对 API 端点强制进行校验：

在 API 目录中：

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

此规则提供 Express 服务模板：

创建 Express 服务时使用此模板：

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

@express-service-template.ts

此规则定义 React 组件结构：

React 组件应遵循以下布局：

顶部为 Props 接口
组件使用命名导出
样式放在底部

@component-template.tsx

此规则自动化应用分析：

在被要求分析应用时：

使用 npm run dev 启动开发服务器
从控制台获取日志
提出性能优化建议

此规则帮助生成文档：

通过以下方式辅助起草文档：

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

首先在 @reactiveStorageTypes.ts 中创建一个需要切换的属性。

在 @reactiveStorageService.tsx 中的 INIT_APPLICATION_USER_PERSISTENT_STORAGE 里添加该属性的默认值。

<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;

不同的提供方和框架都提供了示例。社区贡献的规则可以在各类众包集合和线上代码仓库中找到。

立即启用此规则：选中后，此规则在创建后会立即生效。未选中时，此规则将作为草稿保存，在你稍后启用前不会生效。
强制执行此规则：启用后，此规则对所有团队成员一律生效，且无法在自定义中被关闭。未强制执行时，团队成员可以在自定义的 Team Rules 下将此规则关闭。

默认情况下，未强制执行的 Team Rules 可以被用户关闭。使用 强制执行此规则 来阻止用户关闭该规则。

团队规则的格式及其应用方式

内容：团队规则是自由格式文本，不使用项目规则的文件夹结构。
Glob 模式：团队规则支持 glob 模式按文件范围生效。当设置了 glob 模式时 (例如 **/*.py) ，只有当匹配文件在上下文中时才会应用该规则。没有 glob 模式的规则会应用于每一次对话。
适用范围：当团队规则被启用 (且未被用户禁用，除非被设为强制执行) 时，它会被包含在该团队所有代码仓库和项目中的智能体 (Chat) 模型上下文中。
优先级：规则按以下顺序应用：团队规则 → 项目规则 → 用户规则。所有适用规则会被合并；当指导冲突时，较前的来源优先。

一些团队将强制规则作为内部合规流程的一部分。虽然这是受支持的用法，但 AI 指导不应成为你唯一的安全控制措施。

导入规则

可以从外部来源导入规则，以复用现有配置或引入其他工具的规则。

远程规则 (通过 GitHub)

从你有访问权限的任何 GitHub 仓库 (公共或私有) 直接导入规则。

在侧边栏中打开 自定义
前往 Rules，然后点击 Add Rule
选择 Remote Rule (Github)
粘贴包含这些规则的 GitHub 仓库 URL。Cursor 会扫描仓库中的所有 .mdc 文件。
Cursor 会拉取这些规则并将其同步到你的项目中

规则将放置在 .cursor/rules/imported/<repoName> 中。规则也会保留其相对路径，因此 dir/rule.mdc 将被导入为 .cursor/rule/imported/<repoName>/dir/rule.mdc。

AGENTS.md

AGENTS.md 是一个用于定义 Agent 指令的简单 markdown 文件。你可以将它放在项目根目录中，作为 .cursor/rules 的替代方案，适用于简单直接的用例。

与 Project Rules 不同，AGENTS.md 是一个不带元数据或复杂配置的纯 markdown 文件。它非常适合只需要简单、易读指令，而无需承受结构化规则开销的项目。

Cursor 在项目根目录和子目录中都支持 AGENTS.md。

# 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

改进

这可以让你根据当前正在处理的代码库部分，更精细地控制 agent 指令：

project/  AGENTS.md              # 全局指令  frontend/    AGENTS.md            # 前端专用指令    components/      AGENTS.md          # 组件专用指令  backend/    AGENTS.md            # 后端专用指令

来自嵌套 AGENTS.md 文件的指令会与父目录中的指令合并，更具体的指令会优先生效。

用户规则

用户规则是在 自定义 → 规则 中定义的全局首选项，适用于所有项目。它们会被智能体 (Chat) 使用，非常适合用来设定偏好的沟通风格或编码规范：

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

常见问题

检查规则类型。对于 Apply Intelligently，确保已设置描述。对于 Apply to Specific Files，确保文件模式与被引用的文件匹配。

可以。使用 @filename.ts 将文件包含到规则的上下文中。你也可以在聊天中 @提及规则以手动应用它们。

可以，你可以让智能体为你创建一个新规则。

不会。规则不会影响 Cursor Tab 或其他 AI 功能。

不会。用户规则不会应用到 Inline Edit (Cmd/Ctrl+K) 。它们只会被智能体 (Chat) 使用。

Command Palette

开始使用

Agent

自定义

Agent

源站

集成

SDK

命令行界面

团队与企业版

规则

前端组件和 API 校验规范

Express 服务和 React 组件模板

自动化开发工作流与文档生成

在 Cursor 中添加新设置

嵌套 AGENTS.md 支持

为什么我的规则没有被应用？

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

我可以从聊天中创建规则吗？

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

用户规则 会应用到 Inline Edit（Cmd/Ctrl+K）吗？

Command Palette

开始使用

Agent

自定义

Agent

源站

集成

SDK

命令行界面

团队与企业版

规则

前端组件和 API 校验规范

Express 服务和 React 组件模板

自动化开发工作流与文档生成

在 Cursor 中添加新设置

嵌套 AGENTS.md 支持

为什么我的规则没有被应用？

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

我可以从聊天中创建规则吗？

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

用户规则 会应用到 Inline Edit（Cmd/Ctrl+K）吗？

Command Palette

开始使用

Agent

自定义

Agent

源站

集成

SDK

命令行界面

团队与企业版

规则

前端组件和 API 校验规范

Express 服务和 React 组件模板

自动化开发工作流与文档生成

在 Cursor 中添加新设置

嵌套 AGENTS.md 支持

为什么我的规则没有被应用？

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

我可以从聊天中创建规则吗？

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

用户规则 会应用到 Inline Edit（Cmd/Ctrl+K）吗？