SuperAPI AI 工具集

Creating Cursor Rules

编程与开发

查看项目

更新于 11-13 17:04

技能介绍

用途

这是一个面向 Cursor IDE 的技能,目标是帮助用户编写有效的 .cursor/rules 规则文件,让 AI 助手理解项目约定,从而减少反复纠正、产出更符合团队规范的代码。

适用场景包括:新项目需要搭建 .cursor/rules;改进已有项目规则;把已有的技能或指南转换为 Cursor 格式;团队需要统一记录编码标准。不适用于一次性指令、纯个人偏好(应放入全局设置)或 Claude Code 技能(该技能专用于 Cursor 规则)。

核心原则

  1. 具体且可执行:规则应给出明确指导,而非“写干净的代码”这类空话。例如明确“使用函数组件 + TypeScript”“用 interface 定义 prop 类型而非内联类型”“逻辑超过 10 行时抽取自定义 hook”。
  2. 聚焦决策而非基础规范:不重复 linter 负责的分号、缩进、尾逗号等内容,而记录架构决策,如全局状态选 Zustand、组件树用 React Context,仅在 API 边界用 Zod 做运行时校验,默认用服务端组件等。
  3. 按关注点组织:将规则分为技术栈、代码风格、模式、项目约定等清晰小节。

规则结构与元数据

Cursor 规则采用 MDC(.mdc)格式,支持 YAML frontmatter 加 Markdown 正文。description 为必填,AI 用它判断规则相关性,不得使用占位符或空字符串;globs 用于指定触发自动附加的文件模式(如 ["**/*.ts", "**/*.tsx"]),非 Auto Attached 类型可留空或省略;alwaysApply 为布尔值,true 时规则始终进入上下文。

在 Cursor 中通过类型下拉框控制规则的生效方式:

  • Always:始终包含在模型上下文中,适合核心项目约定、技术栈、通用模式。
  • Auto Attached:当引用匹配 globs 的文件时自动附加,适合按文件类型区分的规则(如 React 组件、API 路由、测试文件)。
  • Agent Requested:由 AI 根据 description 自行决定是否使用,适合上下文相关的模式、专门工作流、可选约定。
  • Manual:仅在用 @ruleName 显式提及时加入,适合少用模式、实验性约定、遗留文档。

建议谨慎使用 alwaysApply: true,仅用于技术栈与核心约定;Auto Attached 的 globs 应精准对应文件类型;Agent Requested 的 description 要包含关键词与具体用例,便于 AI 发现。

必要章节

每个规则文件建议包含:

  • 技术栈声明:列出框架、语言及版本、样式、状态管理、数据库、测试工具、部署平台与关键依赖,避免 AI 推荐错误工具。
  • 代码风格:组件写法、props 定义方式、hook 抽取阈值、导出风格(具名导出)、文件命名规范等。
  • 常见模式:必须配可运行的代码示例,如错误处理(try/catch + 提示 + 重新抛出)、API 路由结构(解析校验、鉴权、执行、返回 Response)、Zod 校验与错误响应等。
  • 项目结构、约定、常见任务(分步骤操作与代码片段)、反模式(含原因说明)、测试方式。

应避免的内容

不要写过于显而易见的建议(如“使用有意义的变量名”)、过于限制性的规定(如“禁止使用任何第三方库”)、与语言无关的空话(如“使用设计模式”)。

最佳实践

  • 单个规则文件控制在 500 行以内,按领域拆分为可组合文件,例如 tech-stack.mdc、typescript-patterns.mdc、api-conventions.mdc、component-patterns.mdc、testing-standards.mdc,并相互引用。
  • 提供具体示例或引用真实项目文件路径,而非模糊描述。
  • 像清晰的内部技术文档那样编写:精确、说明决策背后的原因、记录例外、链接相关文档。
  • 若在对话中反复给出相同指令,就把它沉淀进规则文件,并更新已有文件而非新建。
  • 保持易扫读:清晰标题、加粗关键词、代码示例、对比表格,超过 200 行可加目录。
  • 定期更新,删除过时模式,归档而非直接删除废弃规则。
  • 用 AI 实测:让其按约定新建 API 路由、补充错误处理、重构代码,检查是否遵循规则并据此修正。

限制

该技能本身聚焦 Cursor 规则的编写方法与格式,不涉及具体项目的业务逻辑;实际效果依赖规则内容质量与 AI 的遵循情况,需要通过测试验证。资料未提供该技能的具体安装命令、运行环境或收费信息。