规则
规则为智能体提供系统级指令，将提示词、脚本等内容整合在一起，便于在团队内管理和共享工作流。
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 属性。
| 规则类型 | 描述 |
|---|---|
始终应用 | 应用于每个聊天会话 |
智能应用 | 智能体根据描述判断规则相关时应用 |
应用于特定文件 | 文件匹配指定模式时应用 |
手动应用 | 在聊天中通过 @ 提及规则时 (例如 @my-rule) |
这三个 frontmatter 字段共同决定规则何时被包含：
alwaysApply | description | globs | 行为 |
|---|---|---|---|
true | — | — | 始终包含。忽略 glob 和描述。 |
false | — | 已提供 | 上下文中存在匹配文件时自动附加。 |
false | 已提供 | 已省略 | 智能体会读取描述，并在相关时引入规则。 |
false | 已省略 | 已省略 | 仅当你在聊天中通过 @ 提及规则时才会包含。 |
---alwaysApply: true---- 所有源文件必须包含公司的版权声明头- 如不确定实现细节，请先阅读相关源文件， 再提出更改建议- 切勿修改 `dist/` 或 `build/` 目录中的生成文件---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---description: RPC service conventions and patterns for the backendalwaysApply: false---- Define each service in its own file under `src/services/`- Always validate inputs at the service boundary before passing data to internal functions- Return structured error objects with a `code` and `message` field, never throw raw strings- Add a `@service-template.ts` reference file when creating a new service for the standard boilerplate---alwaysApply: false---- Every database migration must have both `up` and `down` functions so it can be fully reversed- Never alter a column type in-place. Add a new column, backfill, then drop the old one in a separate migration- Reference the template for the expected file structure@migration-template.sqlGlob 模式示例
使用 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 行以内
- 将大型规则拆分为多个可组合的规则
- 提供具体示例或引用相关文件
- 避免模糊的指导。像编写清晰的内部文档一样编写规则
- 在 chat 中重复使用提示词时复用规则
- 引用文件而非复制其内容——这样既能让规则保持简短，也能避免其因代码更改而过时
规则中应避免的做法
- 复制整份风格指南：应改用 linter。智能体已了解常见的代码风格约定。
- 记录所有可能的命令：智能体了解 npm、git 和 pytest 等常用工具。
- 为很少适用的边界情况添加说明：规则应聚焦于您经常使用的模式。
- 重复代码库中已有的内容：请引用权威示例，而不是复制代码。
从简单开始。只有当您发现智能体反复犯同样的错误时，才添加规则。在了解自己的模式之前，不要过度优化。
将规则提交到 git，让整个团队都能从中受益。发现智能体出错时，请更新规则。您还可以在 GitHub issue 或 PR 中 @cursor，让智能体为您更新规则。
规则文件格式
每条规则都是一个包含 frontmatter 元数据和内容的 markdown 文件。frontmatter 元数据用于控制规则的应用方式，内容则是规则本身。
---description: "This rule provides standards for frontend components and API validation"alwaysApply: false---...rest of the rule content如果 alwaysApply 为 true，该规则将应用于所有聊天会话。否则，Cursor Agent 会根据规则描述决定是否应用该规则。
示例
此规则规定了前端组件的标准：
在组件目录中工作时：
- 始终使用 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 } => { vsContext.reactiveStorageService.setApplicationUserPersistentStorage( "myNewProperty", newVal, ); }}/>要在应用中使用，请导入 reactiveStorageService 并使用该属性：
const flagIsEnabled = vsContext.reactiveStorageService.applicationUserPersistentStorage .myNewProperty;可从服务提供商和框架获取示例。社区贡献的规则可在网上的众包集合和仓库中找到。
团队规则
团队版和企业版方案可通过 Cursor 仪表盘为整个组织创建并强制执行规则。管理员可以配置每条规则是否要求团队成员遵守。
团队规则与其他类型的规则配合使用，并具有更高优先级，以确保所有项目均遵循组织标准。无需个人进行设置或配置，即可确保整个团队采用一致的编码标准、实践和工作流。
管理团队规则
团队管理员可以直接在 Cursor 仪表盘中创建和管理规则：
创建团队规则后，这些规则会自动对所有团队成员生效，并显示在仪表盘中：
启用和强制执行
- 立即启用此规则：选中后，创建规则时会立即启用。未选中时，规则将保存为草稿，待日后启用后才会生效。
- 强制执行此规则：启用后，所有团队成员都必须遵守此规则，且无法在“自定义”中禁用。未强制执行时，团队成员可在“自定义”的 团队规则 中关闭此规则。
默认情况下，用户可禁用未强制执行的团队规则。使用 强制执行此规则 可防止这种情况。
团队规则的格式与应用方式
- 内容：团队规则是自由格式文本，不使用项目规则的文件夹结构。
- Glob 模式：团队规则支持通过 glob 模式限定适用文件。设置 glob 模式后 (例如
**/*.py) ，仅当上下文中包含匹配的文件时，规则才会生效。未设置 glob 模式的规则适用于所有对话。 - 适用范围：启用团队规则后 (除非规则被强制执行，否则用户可将其禁用) ，该规则会被纳入该团队所有仓库和项目中智能体 (聊天) 的模型上下文。
- 优先级：规则按以下顺序应用：团队规则 → 项目规则 → 用户规则。所有适用规则都会合并；指导内容冲突时，优先采用较靠前来源的规则。
一些团队会将强制执行的规则用作内部合规工作流的一部分。虽然支持这种做法，但 AI 指导不应是唯一的安全控制措施。
导入规则
您可以从外部来源导入规则，以复用现有配置，或导入其他工具中的规则。
远程规则 (通过 GitHub)
可直接从你有权访问的任意 GitHub 仓库 (公开或私有) 导入规则。
- 在侧边栏中打开 自定义
- 前往 规则，然后点击 添加规则
- 选择 远程规则 (GitHub)
- 粘贴包含规则的 GitHub 仓库 URL。Cursor 将扫描仓库中的所有
.mdc文件。 - Cursor 将拉取规则并同步到你的项目中
规则将存放在 .cursor/rules/imported/<repoName> 中，并保留相对路径。因此，dir/rule.mdc 将导入为 .cursor/rule/imported/<repoName>/dir/rule.mdc。
AGENTS.md
AGENTS.md 是用于定义智能体指令的简单 markdown 文件。对于简单的使用场景，可将其放在项目根目录中，作为 .cursor/rules 的替代方案。
与项目规则不同，AGENTS.md 是不含元数据或复杂配置的纯 markdown 文件。它非常适合需要简单易读的指令、又不希望引入结构化规则额外开销的项目。
Cursor 支持位于项目根目录及子目录中的 AGENTS.md。
# 项目说明## 代码风格- 所有新文件均使用 TypeScript- 在 React 中优先使用函数组件- 数据库列名使用 snake_case## 架构- 遵循仓库模式- 将业务逻辑放在服务层改进
现已支持在子目录中使用嵌套的 AGENTS.md。您可以将 AGENTS.md 文件放在项目的任意子目录中；处理该目录或其子目录中的文件时，这些指令会自动应用。
您可以根据当前处理的代码库区域，更精细地控制智能体指令：
project/ AGENTS.md # 全局指令 frontend/ AGENTS.md # 前端专用指令 components/ AGENTS.md # 组件专用指令 backend/ AGENTS.md # 后端专用指令嵌套 AGENTS.md 文件中的指令会与父目录中的指令合并，更具体的指令优先。
用户规则
用户规则是在 自定义 → 规则 中设置的全局偏好，适用于所有项目。智能体 (聊天) 会使用这些规则，非常适合用于设定首选沟通风格或编码约定：
请简洁回复，避免不必要的重复或套话。常见问题
请检查规则类型。对于 智能应用，请确保已填写描述。对于 应用于特定文件，请确保文件模式与被引用的文件相匹配。
可以。使用 @filename.ts 将文件加入规则的上下文。你也可以在聊天中通过 @提及规则，手动应用这些规则。
可以，你可以让智能体为你创建一条新规则。
不会。规则不会影响 Cursor Tab 或其他 AI 功能。
不适用。用户规则不会应用于 Inline Edit (Cmd/Ctrl+K)。它们仅 供智能体 (聊天) 使用。