规则
规则为你的项目提供持续生效的指令，帮助智能体每次都遵循你的编码风格、约定和工作流程，无需你在聊天中反复说明。
什么是规则？
规则是一组持久生效的指令，智能体会在您的项目中工作时遵循这些指令。您可以将规则的适用范围设为全局、项目级或特定文件。
如何创建项目规则？
项目规则存放在您的代码库中，并纳入版本控制。将其提交到 Git 后，整个团队都能受益。
- 打开命令面板：
- Mac：按 CmdCtrl + Shift + P
- Windows/Linux：按 Ctrl + Shift + P
- 输入“New Cursor Rule”并选择该选项
- 为规则命名 (例如
react-patterns) - 使用 Markdown 编写指令。例如：
- 所有新文件均使用 TypeScript- 在 React 中优先使用函数组件- 数据库列使用 snake_case - 从类型下拉菜单中选择规则的应用方式：
- 始终应用：每次对话都会包含该规则
- 智能应用：由智能体判断何时相关
- 应用于特定文件：仅应用于匹配模式的文件 (例如
*.tsx) - 手动应用：仅在聊天中通过 @提及该规则时使用
- 保存文件。文件会存储在项目的
.cursor/rules/目录中。
如何设置用户规则？
用户规则是适用于所有项目的全局偏好设置。它们会通过你的 Cursor 账户在不同设备间同步。
- 在侧边栏中打开 自定义
- 点击 规则
- 添加你的偏好设置。例如：“回复请简洁，避免不必要的重复。”
如何使用 AGENTS.md？
在项目根目录创建 AGENTS.md 文件，并用纯 markdown 编写指令。Cursor 会自动识别该文件。
# 项目说明- 所有新文件均使用 TypeScript- 数据访问遵循仓储（Repository）模式- 组件代码控制在 200 行以内如需更精细地控制规则的生效时机，请改用 .cursor/rules/ 中的项目规则。
编写规则有哪些最佳实践？
- 每条规则控制在 500 行以内。将较大的规则拆分为更小、更专注的文件。
- 在规则内容中使用
@filename引用具体示例或参考文件。 - 从简单开始。发现智能体多次犯同样的错误时，再添加规则。
- 将规则提交到 Git，让团队成员也能从中受益。
如何组织规则文件？
将所有规则放在扁平的 .cursor/rules/ 目录中。Cursor 会扫描此文件夹以发现规则；虽然也支持嵌套子文件夹，但扁平结构更简单，也更易于管理。请使用描述性文件名 (例如 react-patterns.mdc、api-validation.mdc) 。
对于大型项目，应将规则拆分为多个重点明确的文件，而非全部写在一个冗长的规则文件中。每个文件应只涵盖一个方面，例如样式规范、测试模式或 API 指南。
规则存储在哪里？
- 项目规则存储在项目文件夹中的
.cursor/rules/目录内，并通过 Git 纳入版本控制。
- Cursor 设置中的用户规则存储在你的 Cursor 账户中。它们适用于你的所有项目，并会在你登录另一台设备时同步。
~/.cursor/rules中的用户规则文件 (Windows：%USERPROFILE%\.cursor\rules) 保留在本机，不会同步。
- 团队规则存储在 Cursor 的服务器上，并通过团队仪表盘进行管理。它们会自动同步到所有团队成员。团队规则支持 glob 模式，因此你可以将规则限定到特定文件类型 (例如
**/*.py) 。
用户规则和团队规则不会包含在配置文件导出中。在新设备上登录会同步你的账户用户规则。
团队规则如何运作？
团队版和企业版方案可通过 Cursor 仪表盘创建规则，并在整个组织内强制执行。
- 强制规则对所有成员均为必需，无法在其设置中关闭。
- 可选规则默认启用，但成员可在自定义 > 规则中将其禁用。
- 团队规则支持 glob 模式 (例如
**/*.py) ，可将规则限定为特定文件类型。 - 规则冲突时，优先级为：团队规则 > 项目规则 > 用户规则。
团队规则采用自由文本形式，不使用项目规则的文件夹结构，并会自动同步给所有成员。
如何从 .cursorrules 迁移？
项目根目录中的 .cursorrules 文件为旧版，即将弃用。迁移步骤如下：
- 通过命令面板创建新规则：搜索“New Cursor Rule”
- 将
.cursorrules的内容复制到新规则文件中 - 将规则类型设为 始终应用 (与旧版行为一致)
- 从项目根目录中删除
.cursorrules文件
CLAUDE.md 在 Cursor 中如何生效？
Cursor 读取 CLAUDE.md 文件的方式与读取 AGENTS.md 相同。将 CLAUDE.md 文件放在项目根目录下，Cursor 会自动识别。
无论 alwaysApply frontmatter 设置为何，CLAUDE.md 文件都会始终应用于每次对话。这可确保与同样使用 Claude Code 的项目兼容。如果需要条件规则，请改用 .cursor/rules/ 中的项目规则。
不同文件夹中同名规则如何生效？
Cursor 会根据规则的完整文件路径 (而非仅根据名称) 识别规则。不同文件夹中具有相同文件名的两条规则，只要满足各自条件，都会生效。不会因文件名相同而产生冲突或相互覆盖。
如果规则似乎没有生效，该怎么办？
检查规则类型。对于 Apply Intelligently，请确保已添加描述，以便智能体了解规则何时相关。对于 Apply to Specific Files，请确认文件模式与您正在处理的文件相匹配。
规则仅适用于智能体 (Chat) ，不适用于 Tab completion、Inline Edit 或 Bugbot PR 评审。