Skip to main content

Command Palette

Search for a command to run...

自定义

规则

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

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 字段会共同决定何时包含某条规则：

alwaysApplydescriptionglobs行为
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/**/*.tsxsrc/ 下任意位置的所有 .tsx 文件
docs/**/*.md, docs/**/*.mdxdocs/ 下的 .md 和 .mdx 文件 (以逗号分隔)
tailwind.config.*具有任意扩展名的 tailwind.config

创建规则

创建规则有两种方式：

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

最佳实践

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

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

规则中应避免的做法

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

把规则提交到 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

此规则自动化应用分析：

在被要求分析应用时：

  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;

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

团队规则

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

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

管理团队规则

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

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

激活与强制执行

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

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

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

从代码仓库导入规则

规则无法单独导入。若要从 GitHub 代码仓库引入规则，请将它们打包为插件，并通过 marketplace 发布该插件：在 自定义 中使用 From GitHub Repository 导入该代码仓库 (代码仓库中需包含 .cursor-plugin/marketplace.json) ，或将其添加为团队 marketplace，然后安装该插件。规则会随插件一同引入，并与你的其他规则一起显示在 自定义 中。

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) 使用。

相关内容