Cursor AI 规则
免责声明：本文档是关于 Cursor AI 规则功能的第三方非官方中文文档，仅供学习参考。内容可能不完全反映最新的官方信息，请以 Cursor 官方文档 为准。所有商标和版权归 Cursor/Anysphere 公司所有。
本文档详细介绍如何在 Cursor 中设置与自定义 AI 规则，以便更好地控制和引导 AI 的行为与输出风格。
什么是 AI 规则？
AI 规则是一组指令和偏好设置，告诉 Cursor 的 AI 如何响应您的查询和请求。通过设置这些规则，您可以指导 AI 以特定的风格、格式或方法来回答问题或生成代码，使其输出更加符合您的期望和项目需求。
AI 规则实际上可以被视为对底层大语言模型(LLM)的指令或系统提示，它定义了 AI 的"个性"和行为方式。
为什么 AI 规则很重要？
- 项目上下文理解：为 AI 提供关于项目结构、技术栈和特定需求的关键信息
- 自适应行为：根据 AI 的表现调整其响应方式，让您能够随时间推移微调其行为
- 错误纠正：明确澄清误解并引导 AI 避免常见错误，提高其建议和代码生成的准确性
- 一致性保证：确保团队中所有成员获得风格一致的代码建议和回答
- 学习曲线降低：通过规则帮助新团队成员快速适应项目标准和最佳实践
Cursor 中的 AI 规则类型
Cursor 提供了三种主要的 AI 规则配置方式：
1. 全局规则设置
全局 AI 规则适用于您与 Cursor AI 的所有交互：
- 打开 Cursor 设置（⌘ + , 或 Ctrl + ,）
- 导航至 "AI" 或 "AI 设置" 部分下的 "General" > "Rules for AI"
- 在提供的文本区域中输入您的自定义规则
- 点击"保存"应用您的全局规则
- 确保启用"包含项目规则文件"选项以应用项目特定的规则
全局规则设置示例
1. 错误修复:
- 在提供修复建议前彻底分析问题
- 提供精确、有针对性的解决方案
- 解释错误的根本原因
2. 保持简洁:
- 优先考虑代码的可读性和可维护性
- 避免过度工程化解决方案
- 尽可能使用标准库和设计模式
3. 代码更改:
- 在进行更改前提出清晰的计划
- 一次性应用对单个文件的所有修改
- 不要修改不相关的文件
4. 语言偏好:
- 用中文回答我的问题
- 代码中的注释使用中文
- 变量名和函数名使用英文
请始终考虑每个项目的具体上下文和特定需求。2. 项目特定规则 (推荐方法)
Cursor 现在推荐使用 .cursor/rules 目录来存储项目特定的 AI 规则。这种新系统提供了更强大、更灵活的路径特定配置能力，对项目的不同部分提供精细控制。
设置步骤
- 在项目根目录创建
.cursor文件夹（如果尚不存在） - 在
.cursor文件夹内创建rules子目录 - 在
rules目录中创建规则文件（通常使用 MDC 格式 - Markdown Component）
项目规则核心功能
- 语义描述：每个规则可以包含何时应用该规则的描述
- 文件模式匹配：使用 glob 模式指定规则适用的文件/文件夹
- 自动附加：当引用匹配的文件时，规则会自动包含
- 引用文件：使用
@file在规则中引用其他文件，当规则应用时这些文件会作为上下文包含
创建新规则
您可以通过命令面板轻松创建新规则：
- 按下
Cmd + Shift + P(Mac) 或Ctrl + Shift + P(Windows/Linux) - 选择
New Cursor Rule
目录结构示例
项目根目录/
├── .cursor/
│ └── rules/
│ ├── general-coding-style.md
│ ├── react-components.md
│ ├── typescript-rules.md
│ └── api-endpoints.md
└── ...其他项目文件MDC 格式规则文件示例
文件：.cursor/rules/general-coding-style.md
# 通用编码风格
应用于：所有源代码文件
## 指南
- 使用2个空格进行缩进
- 每行代码不超过80个字符
- 使用分号结束语句
- 使用单引号而非双引号作为字符串
- 函数和方法应该包含JSDoc风格注释
## 代码组织
- 相关函数应当分组在一起
- 按逻辑相关性组织代码，而非严格的字母顺序
- 导入语句按以下顺序组织：标准库、第三方库、本地模块文件：.cursor/rules/react-components.md
# React 组件规则
应用于：**/*.tsx, **/*.jsx
## 组件结构
- 使用函数组件和Hooks，避免使用类组件
- 每个组件应当有一个清晰的责任
- 将大型组件拆分为多个小型组件
- 使用React.memo()优化渲染性能
- Props应该使用TypeScript接口定义
## 引用示例代码
@file src/components/Button.tsx
@file src/components/Card.tsx
## 测试要求
- 所有组件必须有单元测试
- 测试文件应与组件文件放在同一目录下基于路径的规则示例
您可以为特定文件模式创建规则：
文件：.cursor/rules/api-files.md
# API 端点规则
规则应用：src/api/**/*.ts
- 所有API请求函数必须有错误处理
- 使用try/catch包装所有异步调用
- 请求URL应使用环境变量而非硬编码
- 添加请求超时处理
- 实现请求重试逻辑规则链接和组合
您可以在规则文件中使用 @file 引用其他规则文件，实现规则的组合和继承：
# 前端项目主规则
@file .cursor/rules/typescript-base.md
@file .cursor/rules/react-components.md
@file .cursor/rules/styling-guidelines.md
## 项目特定补充规则
- 使用项目特定的组件库
- 遵循设计系统规范
- 实现特定的错误处理流程3. 会话级规则
在单个对话或会话中，您可以临时设定规则：
- 在 Ask 或 Agent 对话开始时，明确声明规则
- 例如："请在接下来的对话中，生成的所有代码都应当包含详细注释，并遵循 PEP 8 风格指南"
会话级规则示例
在本次会话中，请遵循以下规则：
1. 所有生成的 JavaScript 代码应使用 ES6+ 特性
2. 函数应该尽可能是纯函数
3. 使用 camelCase 命名变量和函数
4. 每个函数前都应有 JSDoc 风格的注释
5. 错误处理应使用 try/catch 而不是回调高级规则配置示例
框架特定规则示例
以下是一些针对特定框架或文件类型的规则示例：
SolidJS 规则 (.cursor/rules/solidjs.md)
# SolidJS 开发规则
应用于: **/*.tsx
## 组件风格
- 使用函数组件和 createSignal/createEffect 代替类组件
- 遵循 SolidJS 的响应式原则
- 避免不必要的组件嵌套
## 最佳实践
- 使用 createResource 处理异步数据
- 在顶层使用 createSignal/createStore，避免深层嵌套
- 利用 Solid 的细粒度渲染优化性能
## 参考示例
@file src/components/ExampleSolidComponent.tsx自动生成文件处理 (.cursor/rules/protobuf.md)
# Protobuf 文件处理规则
应用于: **/*.proto, **/generated/*.ts
## 注意事项
- 这些文件是自动生成的，不应直接修改
- 所有更改应该在原始 .proto 文件中进行
## 处理方式
- 生成的代码应视为只读
- 使用包装类扩展功能，而不是修改生成的代码
- 在导入这些文件时使用类型断言
## 参考文档
@file docs/protobuf-usage.md特定领域规则示例
UI 组件规则 (.cursor/rules/ui-components.md)
# UI 组件开发规则
应用于: src/components/ui/**/*.tsx
## 设计原则
- 遵循设计系统规范
- 组件应当是可组合的
- 使用 props 控制外观变化，而非内部状态
## 辅助工具
- 使用 Storybook 开发和测试组件
- 为每个组件编写测试用例
- 使用主题变量而非硬编码样式值
## 文档要求
- 每个组件需要有 JSDoc 注释
- 包含使用示例
- 记录所有 props 及其默认值
@file src/components/ui/Button.tsx
@file src/components/ui/styles/theme.ts架构规则 (.cursor/rules/architecture.md)
# 架构规则
应用于: src/**/*.ts
## 分层架构
- 遵循清晰的分层架构：UI -> 应用服务 -> 领域服务 -> 基础设施
- 遵循依赖倒置原则
- 领域层不应依赖外部库和框架
## 模块化
- 每个功能模块应该自包含
- 使用明确定义的接口进行模块间通信
- 避免循环依赖
## 代码组织
- 按照功能而非技术类型组织代码
- 相关功能应该位于同一目录
- 使用桶（barrel）文件导出公共API
@file src/core/architecture.diagram.md规则编写最佳实践
编写有效的 AI 规则时，请考虑以下最佳实践：
1. 保持一致性
确保您的规则之间不互相矛盾。相互冲突的指示会使 AI 无法确定应该遵循哪条规则，从而可能导致不一致的结果。
2. 涵盖多个方面
全面的规则应该涉及编码风格、文档、错误处理、性能考量等多个方面，以确保 AI 在各种情况下都能提供符合预期的输出。
3. 包含项目特定上下文
提及重要的项目细节，如主要编程语言、框架或独特的架构决策，帮助 AI 更好地理解项目环境。
4. 平衡灵活性和严格性
在坚持核心原则的同时，允许 AI 有一定空间提出创新解决方案。过于严格的规则可能会限制 AI 的创造力和有用性。
5. 使用示例
尽可能提供简短的代码片段来说明您偏好的做法，这比纯文本描述更有效。
6. 明确具体
使用清晰、具体的指令，避免模糊的表述：
✅ 好的规则：
- 生成的所有函数必须包含参数类型注释和返回类型
- 每个函数都应当有描述功能、参数和返回值的文档字符串
❌ 不太有效的规则：
- 写好代码
- 使代码更易读7. 设定优先级
当规则可能冲突时，明确指出优先级：
# AI 规则优先级
1. 安全性和错误处理优先于性能优化
2. 代码简洁性优先于详尽的文档（当空间有限时）
3. 遵循项目现有的命名惯例，即使与一般最佳实践不同从 .cursorrules 迁移到 .cursor/rules 目录
如果您仍在使用旧的 .cursorrules 文件，请按照以下步骤迁移到新系统：
迁移步骤
- 创建
.cursor/rules目录 - 分析您现有的
.cursorrules文件，按功能领域将其拆分 - 为每个功能领域创建单独的规则文件
- 添加适当的文件模式匹配
- 使用
@file引用示例文件和相关规则 - 在版本控制中弃用旧的
.cursorrules文件
迁移示例
旧的 .cursorrules 文件:
你是一位精通 TypeScript 和 React 的专家。
代码风格:
- 使用 ESLint 规范
- 使用 Prettier 格式化
- 类型定义使用接口
React组件:
- 使用函数组件
- 使用 React Hooks
- 提取复用逻辑到自定义 Hooks迁移后的结构:
.cursor/
└── rules/
├── typescript.md # TypeScript相关规则
├── react.md # React组件规则
└── general.md # 通用编码规则typescript.md:
# TypeScript 规则
应用于: **/*.ts, **/*.tsx
- 使用 ESLint 规范
- 使用 Prettier 格式化
- 类型定义优先使用接口而非类型别名
- 避免使用 any 类型，优先使用 unknown
@file tsconfig.json
@file .eslintrc.jsreact.md:
# React 组件规则
应用于: **/*.tsx, **/*.jsx
- 使用函数组件而非类组件
- 使用 React Hooks 管理状态和副作用
- 提取复用逻辑到自定义 Hooks
- 组件应遵循单一责任原则
@file src/components/ExampleComponent.tsx
@file src/hooks/useCustomHook.ts规则优先级与组合策略
当项目中有多个规则可能适用于同一文件时，Cursor 应用以下优先级策略：
- 路径特异性：更具体的路径匹配具有更高优先级
- 显式引用：通过
@file显式引用的规则优先于自动匹配的规则 - 规则声明顺序：在相同规则文件中，先声明的指令优先级更高
- 项目 vs 全局：项目规则总是优先于全局规则
规则的组织与维护
随着项目的发展，定期审查和更新您的 AI 规则很重要：
版本控制：将 AI 规则纳入版本控制，跟踪其变化
bash# 添加规则文件到版本控制 git add .cursor/rules/*.md git commit -m "更新AI规则：添加新的代码风格指南"团队共享：确保所有团队成员了解并使用统一的 AI 规则
markdown# 团队AI规则使用指南 1. 安装最新版Cursor 2. 确保启用了"包含项目规则文件"设置 3. 使用git pull确保获取最新的规则定义 4. 遇到问题请在团队Slack上讨论定期审查：随着项目的发展和新模式的出现，更新规则
markdown# 规则更新日志 2024-06-01: 添加TypeScript严格类型检查规则 2024-05-15: 更新测试规范，增加集成测试要求 2024-04-22: 添加新的安全规则和最佳实践从反馈中学习：根据 AI 生成的代码质量，调整和改进规则
markdown# 规则改进反馈表 | 日期 | 问题描述 | 规则调整建议 | 状态 | |------|---------|------------|------| | 2024-06-05 | AI未正确处理异步操作 | 添加更明确的异步处理指南 | 已实施 | | 2024-05-20 | 生成的单元测试覆盖不全 | 详细说明测试边缘情况要求 | 审核中 |
规则效果验证
创建规则后，可以通过以下方式验证其效果：
- 比较测试：使用相同的提示，对比有规则和无规则时的 AI 响应差异
- 团队评审：让团队成员审查规则并提供反馈
- 逐步迭代：从简单规则开始，观察效果后再添加更复杂的规则
常见问题与解决方案
Q: 我的规则似乎没有生效，可能是什么原因？
A: 检查以下几点：
- 确保规则文件位于正确位置（
.cursor/rules/目录中） - 验证文件格式和语法是否正确
- 检查文件模式匹配是否适合您的目标文件
- 检查Cursor设置中是否启用了"包含项目规则文件"选项
- 尝试重启Cursor编辑器
Q: 全局规则和项目规则冲突时，哪个优先？
A: 项目特定规则（.cursor/rules/ 目录中的文件）优先于全局规则。如果两者有冲突，AI 会优先遵循项目规则。
Q: 如何为不同编程语言设置不同规则？
A: 在 .cursor/rules/ 目录中为每种语言创建单独的规则文件，并使用文件模式匹配指定适用范围：
# Python 编码规则
应用于: **/*.py
- 遵循 PEP 8 规范
- 使用 4 空格缩进
- 使用 docstrings 文档化函数# JavaScript 编码规则
应用于: **/*.js, **/*.jsx
- 遵循 Airbnb 风格指南
- 使用 2 空格缩进
- 优先使用 ES6+ 特性Q: .cursorrules 文件是否仍然有效？
A: 虽然 .cursorrules 文件目前仍然有效，但它被视为旧系统，可能在未来被完全弃用。我们强烈建议迁移到新的 .cursor/rules/ 目录系统，以获得更好的灵活性和可维护性。
通过精心设计和应用 AI 规则，您可以将 Cursor 的 AI 功能塑造成您团队的高效协作伙伴。这些规则不仅提高了 AI 生成的代码质量和一致性，还确保了其输出符合项目的特定需求和标准。