1. 项目概述：一个为开发者定制的 Cursor 规则集

如果你是一名深度使用 Cursor 的开发者，大概率经历过这样的场景：面对一个复杂的重构任务，你满怀期待地给 Cursor 下达指令，结果它生成的代码要么风格混乱，要么引入了你团队明令禁止的语法，或者干脆忽略了项目里那些不成文的“潜规则”。每次生成后，你都得花大量时间去手动调整格式、修正命名、甚至重写逻辑。这种“生成-修正”的循环，极大地消耗了开发效率的增益。

noobgaminghard/cursor-rules 这个项目，就是为了终结这种循环而生的。它本质上是一个为 Cursor AI 代码编辑器定制的、高度可配置的规则集。你可以把它理解为 Cursor 的“行为准则”或“开发规范说明书”。通过将你个人或团队的编码习惯、项目约束、最佳实践“翻译”成 Cursor 能理解的规则，你可以让 AI 在生成代码、回答问题、执行操作时，从一开始就走在“正确”的道路上。无论是确保生成的代码符合你项目的 ESLint 配置，还是强制使用特定的函数命名约定，亦或是避免使用某些过时的 API，这个规则集都能帮你实现。

这个项目适合所有希望将 Cursor 从“一个聪明的代码补全工具”提升为“一个理解我项目上下文的智能开发伙伴”的开发者。无论你是独立开发者，还是团队的技术负责人，通过定制和共享规则集，都能显著提升与 AI 协作的流畅度和产出代码的质量。

2. 核心思路：如何让 AI 理解你的“规矩”

2.1 规则集的本质：上下文与约束的具象化

Cursor 的强大之处在于它能深入分析你打开的项目，理解代码上下文。然而，这种理解是“描述性”的，而非“规范性”的。它能看到你用了 const ，但不知道你是否禁止使用 var ；它能识别出你的函数名是 camelCase，但不知道你是否要求异步函数必须以 Async 结尾。 cursor-rules 项目的作用，就是将后者——那些“规范性”的要求——明确地告诉 Cursor。

其核心思路基于 Cursor 的 .cursorrules 文件机制。这个文件可以放置在项目根目录或用户全局配置目录，Cursor 在运行时会主动读取并应用其中的规则。 noobgaminghard/cursor-rules 提供了一个结构化的、内容丰富的模板和范例，帮助你快速构建自己的 .cursorrules 文件。它不是一个运行时库，而是一个配置范例的集合。

2.2 规则设计的三个维度：从语法到文化

一个有效的规则集应该从多个层面去约束和引导 AI：

  1. 语法与风格层 ：这是最基础的一层，对应传统的 Linter（如 ESLint, Prettier）规则。例如：

    • 代码格式 ：缩进是 2 空格还是 4 空格？尾随逗号是否强制？行宽限制是多少？
    • 语法偏好 ：使用 === 还是 == ？字符串用单引号还是反引号？是否禁用 console.log ？
    • 导入/导出规范 ：如何组织 import 语句？是否禁止 require ？

  2. 架构与模式层 ：这一层定义了代码的组织方式和设计模式。例如：

    • 文件结构 ：组件文件必须放在 src/components/ 下吗？工具函数应该集中管理还是就近存放？
    • 状态管理 ：规定使用特定的状态管理库（如 Zustand, Redux Toolkit）及其最佳实践。
    • API 交互 ：定义统一的请求层（如使用 axios 实例，或特定的 fetch 封装），并规定错误处理模式。
    • 组件设计 ：对于 React/Vue 项目，规定是使用函数组件还是类组件？是否强制使用 Hooks？

  3. 项目与文化层 ：这是最个性化、也最能体现规则集价值的一层。它包含了项目特有的“潜规则”和团队共识。例如：

    • 命名约定 ：除了基本的 camelCase/PascalCase，可能还有特殊规则，如“事件处理函数必须以 handle 开头”、“常量枚举值必须全大写并用下划线连接”。
    • 禁用与推荐 ：明确列出项目中已废弃的、有性能问题的或存在安全隐患的 API/库，并要求 AI 使用推荐的新方案。
    • 业务逻辑封装 ：规定某些特定的业务计算必须调用项目内的某个工具函数，而不是让 AI 重新实现一遍逻辑。
    • 注释与文档 ：要求 AI 在生成复杂函数时，必须包含符合特定格式的 JSDoc/TSDoc 注释。

noobgaminghard/cursor-rules 的范例覆盖了这三个维度，为你提供了一个高起点的设计蓝图。

注意 ：规则不是越多越严越好。过于严苛的规则可能会限制 AI 的创造力，或导致它因为无法满足所有约束而生成低质量的代码。规则设计的艺术在于，在“一致性”和“灵活性”之间找到平衡点。

3. 规则集解析与核心配置实战

3.1 .cursorrules 文件结构剖析

让我们深入看看一个典型的 .cursorrules 文件可能包含哪些部分。虽然具体语法可能随 Cursor 版本更新，但其核心结构通常如下：

{
  “version”: “1.0”,
  “rules”: {
    “codeStyle”: { ... },
    “architecture”: { ... },
    “projectConventions”: { ... },
    “instructions”: { ... }
  }
}
  • version : 指明规则集版本，用于兼容性判断。
  • rules : 所有具体规则的容器，通常按维度分类。
3.1.1 codeStyle 规则配置详解

这部分直接与代码格式化工具和 Linter 的配置对齐。最佳实践是让 .cursorrules 引用或镜像你项目中已有的配置文件（如 .eslintrc.js , .prettierrc ），而不是重新定义一遍。

“codeStyle”: {
  “engine”: “eslint”, // 或 “prettier”， 告诉 Cursor 主要遵循哪个工具的规则
  “configPath”: “./.eslintrc.js”, // 指向项目中的配置文件
  “overrides”: { // 可以在这里对基础配置进行覆盖或补充
    “indent”: [“error”, 2],
    “quotes”: [“error”, “single”, { “avoidEscape”: true }],
    “semi”: [“error”, “never”]
  },
  “files”: { // 可以为不同文件类型设置不同规则
    “*.ts”: {
      “rules”: {
        “@typescript-eslint/explicit-function-return-type”: “error”
      }
    },
    “*.vue”: {
      “extends”: [“plugin:vue/recommended”]
    }
  }
}

实操心得 ：我强烈建议将 configPath 指向你项目中真实的配置文件。这样能保证 Cursor 生成的代码风格与你的 IDE 实时提示、以及 CI/CD 流水线中的检查完全一致，避免“在 Cursor 里看着对，一提交就报错”的尴尬。

3.1.2 architecture 与 projectConventions 规则配置

这两部分是规则集的精髓，它们用自然语言和结构化数据来描述项目的“规矩”。

“architecture”: {
  “framework”: “nextjs”, // 声明项目主框架
  “stateManagement”: “zustand”, // 声明状态管理方案
  “routing”: “next/router”, // 声明路由方案
  “styling”: “tailwindcss”, // 声明样式方案
  “patterns”: [ // 声明鼓励使用的设计模式
    “custom-hooks-for-logic-reuse”,
    “container-presentational-component-separation”
  ]
},
“projectConventions”: {
  “naming”: {
    “reactComponent”: “PascalCase”,
    “customHook”: “camelCase starting with ‘use’”,
    “constant”: “UPPER_SNAKE_CASE”,
    “eventHandler”: “prefix with ‘handle’， e.g., handleClick”
  },
  “forbidden”: [ // 明确禁止的内容
    {
      “description”: “Do not use the legacy Context API directly for global state.”,
      “suggestion”: “Use the Zustand store defined in `src/stores/` instead.”
    },
    {
      “description”: “Avoid direct DOM manipulation with `document.getElementById` in React components.”,
      “suggestion”: “Use React refs and the `useEffect` hook.”
    }
  ],
  “requiredImports”: { // 规定特定场景下必须导入的模块
    “whenGeneratingUtilityFunctions”: [“import { formatDate } from ‘@/lib/utils’”],
    “whenWorkingWithAPI”: [“import { apiClient } from ‘@/services/api’”]
  },
  “fileOrganization”: {
    “components”: “Place in `src/components/`， grouped by feature if possible.”,
    “hooks”: “Place in `src/hooks/`.”,
    “utils”: “Place in `src/lib/`.”
  }
}

注意事项 ：在定义 forbidden 和 suggestion 时，描述要尽可能具体、可操作。模糊的禁令（如“不要写低效代码”）对 AI 是无效的。应该换成“当处理超过 100 个列表项的渲染时，必须使用虚拟滚动技术，例如 react-window 库”。

3.2 instructions ：你的专属 AI 提示词库

这是 .cursorrules 中最强大的部分之一。你可以在这里预设一系列针对常见任务的、详细的提示词（instructions）。当你在 Cursor 中触发相关操作时，这些预设指令会自动生效，省去你反复输入相同提示的麻烦。

“instructions”: {
  “createComponent”: “Create a new React functional component. It must be written in TypeScript， use Tailwind CSS for styling， accept props typed with an interface， and include a placeholder JSDoc comment. Export it as the default export.”,
  “writeUnitTest”: “Write a unit test using Jest and React Testing Library. Follow the Arrange-Act-Assert pattern. Mock external dependencies appropriately. Include descriptive test names.”,
  “refactorFunction”: “When refactoring a function， first explain the logic in plain language. Then provide the refactored version， aiming to improve readability and maintainability without changing the external behavior. Consider extracting reusable logic into separate functions.”
}

核心技巧 ：你可以为 instructions 设置触发条件。例如，当你在项目中创建新的 .test.js 文件时，自动应用 writeUnitTest 的规则；当你在 @/components 目录下创建新文件时，自动应用 createComponent 的规则。这需要通过规则中的 context 或 glob 模式来精细控制，具体语法需参考 Cursor 官方文档。

4. 从零开始构建与集成你的规则集

4.1 初始化与基础配置

假设我们为一个名为 my-awesome-app 的 Next.js + TypeScript + Tailwind CSS 项目配置规则集。

  1. 创建规则文件 ：在项目根目录下，创建 .cursorrules 文件。

    touch .cursorrules

  2. 搭建基础骨架 ：参考 noobgaminghard/cursor-rules 提供的范例，填入项目的基本信息。

    {
  “version”: “1.0”,
  “description”: “Code generation rules for My Awesome App (Next.js 14， TS， Tailwind)”,
  “rules”: {
    “codeStyle”: {
      “engine”: “eslint”,
      “configPath”: “./.eslintrc.json”
    },
    “architecture”: {
      “framework”: “nextjs”,
      “language”: “typescript”,
      “styling”: “tailwindcss”
    },
    “projectConventions”: {},
    “instructions”: {}
  }
}

4.2 渐进式填充项目专属规则

不要试图一次性写完所有规则。采用渐进式方法，在开发过程中随时补充。

  • 第一周 ：聚焦代码风格。确保 codeStyle 正确指向 ESLint 和 Prettier 配置。观察 AI 生成的代码在格式上是否还需要手动调整，将调整需求转化为规则。
  • 第二周 ：补充命名约定。在 projectConventions.naming 中，定义好组件、钩子、常量、类型等的命名规则。
  • 第三周 ：定义架构模式。在 architecture.patterns 和 projectConventions.fileOrganization 中，明确项目的文件结构和推荐模式。例如，“页面组件放在 app/(routes)/ 下，共享组件放在 components/ui/ 和 components/business/ 下”。
  • 持续过程 ：每当你在代码审查或日常开发中发现一个重复出现的、希望 AI 避免的错误或可以遵循的最佳实践，就立刻将其添加到 forbidden 列表或 instructions 中。

4.3 团队共享与版本化管理

.cursorrules 文件应该被纳入项目的版本控制系统（如 Git）。

  1. 作为团队规范 ：将 .cursorrules 提交到仓库，意味着所有团队成员在使用 Cursor 时都会遵循同一套标准，极大提升了团队代码的一致性。
  2. 分支出特定规则 ：对于大型项目，可以考虑创建多个 .cursorrules 文件。例如：
    • .cursorrules (基础规则)
    • .cursorrules.backend (针对 server/ 目录的 Node.js 规则)
    • .cursorrules.storybook (针对 .stories.tsx 文件的 Storybook 规则) 通过在特定目录放置特定的规则文件，可以实现更精细的控制。
  3. 全局个人规则 ：你也可以在系统级的 Cursor 配置目录（如 ~/.cursor/ ）下放置一个全局的 .cursorrules 文件。这里的规则会作为所有项目的默认规则，但项目本地的规则具有更高优先级。这适合用来配置你个人的通用习惯，比如你偏爱的代码注释风格。

5. 高级技巧与疑难问题排查

5.1 规则冲突与优先级解析

当全局规则、项目规则、甚至文件特定规则存在冲突时，理解其优先级至关重要。通常的优先级是：

文件/目录级规则 > 项目根目录规则 > 用户全局规则 > Cursor 默认行为

例如，你在项目根目录的 .cursorrules 中禁止使用 any 类型，但在 src/legacy/ 目录下放了一个 .cursorrules 文件，其中允许 any 。那么当 AI 在 src/legacy/utils.ts 文件中操作时，它会允许使用 any 。

排查技巧 ：如果发现 AI 没有遵守你认为已设置的规则，首先检查规则文件是否在正确的路径并被正确读取。其次，检查是否有更高优先级的规则覆盖了当前设置。可以在 Cursor 中尝试输入简单的指令并观察其输出，来验证规则是否生效。

5.2 利用上下文感知实现动态规则

最强大的规则是能感知上下文的规则。这需要结合 instructions 和 Cursor 对项目结构的理解。

场景示例 ：你希望 AI 在修改 src/services/auth.ts 文件时，自动使用项目中定义的错误处理装饰器。

你可以在 .cursorrules 的 instructions 中这样配置：

“instructions”: {
  “modifyAuthService”: {
    “context”: “When editing files matching `src/services/auth*.ts`”,
    “prompt”: “Always wrap API call logic with the `@withErrorHandling` decorator imported from ‘@/lib/decorators’. Log errors using the `logger` instance from ‘@/lib/logger’.”
  }
}

这样，当你的操作上下文位于认证服务文件时，这条指令会自动成为 AI 思考的背景知识，引导它生成符合规范的代码。

5.3 调试与验证规则有效性

  1. 使用测试指令 ：创建一个简单的测试文件或打开一个现有文件，对 Cursor 发出直接挑战你规则的指令。例如，如果你的规则禁止使用 var ，你可以要求它“用 var 声明一个变量”，看它是否会拒绝或自动纠正为 let/const 。
  2. 审查生成历史 ：Cursor 通常有对话或生成历史。回顾 AI 生成的代码，检查它是否遵循了你在规则中设置的命名约定、导入语句顺序、禁用模式等。
  3. 迭代优化 ：规则集不是一成不变的。它是一个活的文档。如果某条规则导致 AI 频繁生成低质量代码或变得“笨拙”，不要犹豫去调整它。可能这条规则限制得太死，或者描述得不够清晰。

5.4 常见问题速查表

问题现象 可能原因 解决方案
Cursor 完全忽略 .cursorrules 文件 1. 文件不在项目根目录或当前工作目录。
2. 文件格式错误（JSON 语法错误）。
3. Cursor 版本过旧不支持。		 1. 检查文件路径和名称（包括开头的点）。
2. 使用 JSON 验证工具检查语法。
3. 更新 Cursor 到最新版本。
部分规则生效，部分不生效 1. 规则语法有误或不被支持。
2. 规则之间存在冲突或优先级问题。
3. 规则描述过于模糊。		 1. 查阅 Cursor 官方文档，确认语法。
2. 简化规则，移除可能存在冲突的部分，逐一测试。
3. 将规则描述得更具体、可操作。
AI 生成的代码风格与规则不符 codeStyle.configPath 指向的配置文件（如 .eslintrc ）未被 Cursor 正确加载或解析。 1. 确保指向的配置文件存在且有效。
2. 尝试在 codeStyle.overrides 中直接写入几条核心规则进行测试。
instructions 没有在预期场景触发 1. context 条件设置不正确。
2. Instruction 的名称或调用方式不对。		 1. 检查 context 中的路径匹配模式是否正确。
2. 尝试使用更通用的指令，或检查 Cursor 是否支持该类型的上下文触发。

构建一个高效的 cursor-rules 集是一个持续磨合的过程。初期可能会花费一些时间，但一旦这套“共同语言”建立起来，你会发现与 Cursor 的协作效率会产生质的飞跃。它从一名需要频繁纠正的“实习生”，逐渐成长为一名深刻理解项目文化和规范、能够独立产出高质量代码的“资深开发伙伴”。这个投资回报率，在长期的项目开发中是非常可观的。

# 代码规范
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

DeepSeek-V4 RAG 分块策略优化：512 vs 1024 token 的实测边界与工程取舍

avatar DeepSeek技术社区
cover

企业知识库问答中的权限迷宫：如何用 DeepSeek 实现文档级 ACL 下沉与安全召回

avatar DeepSeek技术社区
cover

RAG 文档预处理：为什么 90% 的失败案例源于切分策略不当

avatar DeepSeek技术社区