Cursor AI 编码助手规则集配置指南：从代码规范到项目定制

1. 项目概述：一个为 Cursor 编辑器量身定制的规则集

如果你和我一样，日常重度依赖 Cursor 这款 AI 驱动的代码编辑器，那你一定遇到过这样的场景：面对一个复杂的重构任务，你满怀期待地输入指令，结果 AI 生成的代码风格和你项目里现有的完全对不上，或者它自作主张地引入了你明令禁止的依赖。又或者，在团队协作中，每个人的 Cursor 都“各显神通”，生成的代码格式五花八门，Review 起来简直是一场灾难。

“LessUp/cursor-rules”这个项目，就是为了根治这些问题而生的。简单来说，它是一个专门为 Cursor 编辑器设计的、可高度自定义的规则集配置文件。它不提供任何具体的代码功能，而是扮演一个“交通警察”或“项目管家”的角色，通过一套精心设计的规则，来约束和引导 Cursor 内置的 AI（无论是 Claude 还是 GPT 模型）在生成代码、回答问题时的行为。

这个项目适合所有使用 Cursor 的开发者，无论你是独立开发者希望保持个人项目的代码一致性，还是团队技术负责人亟需统一团队的 AI 辅助编码规范。通过配置cursor-rules，你可以明确告诉 Cursor 的 AI：“在我们这个项目里，请用这个代码风格、请遵循这些架构原则、请避免使用那些特定的模式或库”。这相当于为你的 AI 结对编程伙伴进行了一次深度的“上岗培训”，让它更懂你的项目和团队习惯，从而显著提升生成代码的可用性、一致性和安全性，减少后续的人工调整成本。

2. 核心设计思路：从“自由发挥”到“精准制导”

为什么我们需要专门为 Cursor 制定规则？这源于当前 AI 编码助手的核心工作模式。它们本质上是基于海量代码和文本训练出来的概率模型，在响应你的指令时，会从训练数据中找出最可能的“下一个词”或“下一段代码”。这种模式带来了强大的灵活性和创造性，但也伴随着不可预测性。AI 可能会：

1. 风格漂移：混用不同的命名规范（snake_case vs camelCase）、缩进风格（空格 vs Tab）。
2. 引入“技术债”：使用项目已废弃的旧 API，或推荐团队明令禁止的第三方库。
3. 忽略项目上下文：虽然 Cursor 能读取打开的文件，但对于项目级的约定（如目录结构、框架特定写法）缺乏系统性认知。
4. 安全与合规风险：生成包含硬编码密钥、使用存在许可证冲突的代码片段。

cursor-rules的设计哲学，就是将这种“自由发挥”转变为“精准制导”。它不是一个运行时插件，而是一个静态的配置文件（通常是项目根目录下的.cursorrules文件）。当 Cursor 在处理当前项目的请求时，会主动读取并应用这个文件中的规则，将其作为 AI 生成内容时的强约束条件。

其核心思路可以拆解为三个层次：

1. 约束层（Constraints）：明确划定“红线”。例如，禁止使用某些函数、强制使用某种异步模式、要求所有生成的组件必须是函数式而非类式。这是最直接、最硬性的规则。
2. 引导层（Guidance）：提供“最佳实践”模板。例如，当创建新的 React 组件时，应遵循特定的文件结构、导入顺序和 PropTypes 定义方式。这更像是给 AI 一个高质量的范例。
3. 上下文层（Context）：注入项目专属知识。例如，告知 AI 本项目使用的内部工具函数、特定的配置对象名称、领域内的业务术语解释。这相当于给 AI 补充了一份项目手册。

通过这三层的组合，cursor-rules使得 Cursor 从一个“通用的代码生成器”进化为一个“懂你项目的专属编码助手”。它的设计巧妙之处在于，它不改变 Cursor 本身，而是通过一种声明式的配置，高效地利用了 Cursor 提供的规则接口，实现了深度的定制化。

3. 规则文件解析与核心语法要点

cursor-rules的核心是一个配置文件。虽然项目可能提供了示例，但理解其语法和结构是灵活运用的关键。通常，这个文件使用 YAML 或 JSON 等易于阅读的结构化格式。下面，我将以一个综合的.cursorrules文件为例，拆解其核心部分。

3.1 基础结构与全局规则

文件通常以声明规则的作用范围和版本开始。

# .cursorrules version: 1 scope: project # 规则作用于整个项目

scope字段非常关键，它决定了规则的生效范围：

• project: 对整个项目生效（最常见）。
• directory: /src/components: 仅对指定目录生效。
• file: *.test.js: 仅对匹配特定模式的文件生效。

接下来是全局性的约束和引导：

constraints: - “禁止使用 `var` 关键字，一律使用 `const` 或 `let`。” - “禁止使用 `alert`, `confirm`, `prompt` 等原生弹窗函数。” - “生成的代码中不得包含任何模拟的 API 密钥、密码或真实用户信息。” - “避免使用 `any` 类型（针对 TypeScript 项目）。” guidance: - “本项目使用 React 18+ 和函数式组件。优先使用 Hooks。” - “样式方案采用 CSS Modules，文件命名应为 `Component.module.css`。” - “异步操作统一使用 `async/await`，并配合 `try-catch` 进行错误处理。” - “所有导出的函数、组件都需要添加 JSDoc/TSDoc 注释。”

注意：约束（constraints）的表述应使用肯定、明确、强制的语气，如“禁止”、“必须”、“不得”。引导（guidance）则可以使用“优先”、“推荐”、“遵循”等建议性语气，并为 AI 留下合理的判断空间。

3.2 针对文件类型的细化规则

这是提升规则效力的关键。你可以为不同后缀的文件定义特定规则。

rules: - scope: file:*.tsx constraints: - “Props 接口命名必须为 `{ComponentName}Props`。” - “组件文件默认导出必须是 React 组件。” guidance: - “使用 `import type` 来导入纯类型。” - “在组件顶部定义 `React.FC<Props>` 类型。” - scope: file:*.test.{js,ts,jsx,tsx} constraints: - “测试框架使用 Vitest，断言库使用 @testing-library/react 和 @testing-library/user-event。” - “禁止使用 `console.log` 进行调试，应使用测试断言。” guidance: - “测试描述（`describe`/`it`）应使用英文，清晰描述行为。” - “遵循 Arrange-Act-Assert 模式组织测试代码。” - scope: directory: /api constraints: - “所有 API 路由处理函数必须是异步的。” - “错误响应必须使用统一的 `ApiError` 类包装。” guidance: - “使用 `zod` 库进行输入参数验证。” - “在函数开头验证用户认证状态。”

3.3 上下文注入与知识库

你可以直接向 AI 的上下文“投喂”项目特定的代码片段、文档或设计决策，这对于理解内部工具和约定至关重要。

context: - “本项目使用一个自定义的 `fetchClient` 工具进行所有 HTTP 请求，它已内置了认证令牌处理和基础错误处理。不要使用原生的 `fetch` 或 `axios`。” - “工具函数 `formatCurrency(value: number): string` 用于格式化货币显示，它已经处理了千位分隔符和货币符号。” - “用户角色定义：`‘admin’` | `‘editor’` | `‘viewer’`。权限检查请使用 `hasPermission(user, permission)` 函数。”

你也可以直接引用项目内的文件内容作为上下文：

context: - “参考项目根目录下的 `ARCHITECTURE.md` 了解项目分层设计。” - “工具函数库的用法示例见 `/src/utils/README.md`。”

实操心得：context部分不宜过长或过于琐碎。应聚焦于高频使用且容易让 AI 误解或发明的核心概念和工具。把 AI 当成一个新加入团队的工程师，你会给他看哪些最重要的入职文档？这就是context应该包含的内容。

4. 从零开始构建你的.cursorrules文件

了解了核心语法后，我们来看如何为一个真实项目（假设是一个 Next.js + TypeScript + Tailwind CSS 的全栈应用）从头搭建一套有效的规则集。这个过程是迭代的，而非一蹴而就。

4.1 第一阶段：建立安全与风格基线

首先，在项目根目录创建.cursorrules文件。从最基础、最不容妥协的规则开始。

# .cursorrules - 初版 version: 1 scope: project # 安全与质量红线 constraints: - “绝对禁止在代码中硬编码任何敏感信息，如 API 端点、密钥、密码。必须使用环境变量。” - “禁止提交 `console.log` 调试语句。如需调试，使用调试器或临时的、有明显标记的日志（如 `console.log(‘[DEBUG]’, obj)`），并在提交前移除。” - “禁止使用 `eval()`、`Function` 构造函数等动态代码执行方法。” - “TypeScript 项目中禁止使用 `as` 进行类型断言，除非在处理第三方库返回的未知类型时。优先使用类型守卫。” # 基础代码风格 guidance: - “本项目使用 ESLint 和 Prettier 进行代码格式化。生成的代码应符合现有 `.eslintrc.json` 和 `.prettierrc` 配置。” - “使用双引号 `“`。缩进为 2 个空格。” - “导入语句分组顺序：1. 第三方库，2. 内部绝对路径引用，3. 相对路径引用，4. 类型导入。组间用空行分隔。”

将这个文件放入项目后，你可以立即在 Cursor 中尝试。当你让 Cursor 生成一个包含console.log的函数时，它会提醒你这条约束，甚至可能主动建议你移除它或改用调试器。

4.2 第二阶段：融入技术栈特定规则

根据项目使用的框架和库，添加更具体的引导。

# 在 rules 部分添加 rules: - scope: file:*.{tsx,jsx} # React 组件 guidance: - “组件命名使用 PascalCase。文件名与默认导出的组件名一致。” - “优先使用函数声明式组件而非箭头函数，除非是 `React.memo` 包裹的组件。” - “使用 Tailwind CSS 进行样式编写。避免编写行内 `style` 对象或单独的 `.css` 文件。” - “事件处理函数命名以 `handle` 开头，如 `handleClick`。” - “使用 `useState`, `useEffect` 等 Hooks 时，若依赖项数组为空，需明确写明 `[]`。” - scope: file:app/**/*.tsx # Next.js 13+ App Router constraints: - “页面组件必须是默认导出（default export）的异步函数组件。” - “除非必要，否则不要使用 `‘use client’` 指令。默认服务端组件。” guidance: - “数据获取使用 `async/await` 配合 `fetch`，或在服务端组件中使用 `React.cache`。” - “元数据定义使用 `generateMetadata` 函数。” - scope: file:*.ts # 通用 TypeScript 文件 guidance: - “接口（interface）命名使用 PascalCase，不以 `I` 开头。” - “类型别名（type）用于联合类型、交叉类型或复杂类型转换。” - “使用 `import type` 导入纯类型，以辅助 Tree Shaking。”

4.3 第三阶段：注入业务上下文与高级约束

这是让 AI 真正“懂你业务”的一步。

# 在 context 部分添加 context: - “本项目后端 API 基地址从 `process.env.NEXT_PUBLIC_API_URL` 读取。所有前端请求应使用封装在 `/lib/api-client.ts` 中的 `apiClient` 实例，它已处理了认证和错误。” - “用户会话信息通过 `useSession` Hook（来自 `next-auth/react`）获取。`session` 对象包含 `user` 字段，其中有 `id`, `email`, `role` 等信息。” - “表单验证统一使用 `react-hook-form` 配合 `zod` 模式。验证模式定义在 `/lib/validations` 目录下。” # 添加高级约束 constraints: # 在全局 constraints 中追加 - “禁止直接操作 DOM（如 `document.getElementById`）。必须使用 React Ref 或状态驱动。” - “禁止在组件内部创建非必要的内联函数，以避免不必要的重渲染。应使用 `useCallback` 或提取到组件外部。” - “对于可能为 `null` 或 `undefined` 的值，必须进行显式的空值检查，或使用可选链 `?.` 和空值合并运算符 `??`。”

4.4 第四阶段：优化与维护

规则集不是一成不变的。随着项目演进，你需要：

1. 观察与收集：在代码审查中，注意那些频繁被指出的、可以由 AI 避免的问题。
2. 测试规则：故意向 Cursor 提出可能触发不良模式的问题，看规则是否生效。
3. 团队同步：将.cursorrules文件纳入版本控制（如 Git）。任何修改都需要经过团队讨论，因为它影响了所有人的开发体验。
4. 保持简洁：定期回顾规则，移除过时的或很少被触发的条目，防止文件变得臃肿难懂。

踩坑提醒：不要试图用规则控制一切细节。AI 需要一定的创造性空间。规则的目标是防止错误和保证一致性，而不是扼杀所有可能性。如果某条规则导致 AI 频繁生成别扭或低效的代码，可能需要重新审视这条规则的合理性。

5. 高级技巧与场景化配置

掌握了基础配置后，我们可以探索一些更高级的用法，以应对复杂场景。

5.1 利用上下文实现“代码片段模板”

你可以将常用的代码模式作为上下文注入，让 AI 在类似场景中复用。例如，项目有一个标准的 API 响应处理模式：

context: - | // API 响应处理标准模式 async function fetchUserData(userId: string) { try { const response = await apiClient.get(`/users/${userId}`); // 假设 apiClient 会抛出非 2xx 响应的错误 return response.data; } catch (error) { // 使用项目统一的错误处理工具 logError(‘fetchUserData failed’, error); // 向上抛出经过处理的错误，供 UI 层显示 throw new UserFacingError(‘获取用户信息失败，请重试’); } }

当你想让 AI 生成另一个获取产品数据的函数时，它有很大概率会模仿这个try-catch结构、错误日志和包装方式。

5.2 为不同开发阶段配置不同规则

在项目初期（快速原型阶段）和后期（稳定维护阶段），对代码质量和 AI 辅助的期望可能不同。虽然cursor-rules文件本身是静态的，但你可以通过条件注释或维护多个版本来实现（需要手动切换）。

一种实践是，在快速迭代时，注释掉一些过于严格的质量约束（如“禁止内联函数”），专注于功能实现。在进入代码整理和优化阶段时，再启用这些规则，让 AI 帮助你重构。

5.3 与 Cursor 的.cursor/mdc文件配合使用

Cursor 还有一个更底层的模型指令定制功能，通过项目根目录下的.cursor/mdc文件实现。mdc(Model Directive Context) 文件中的指令会在每次AI 请求时被前置，影响力更强。

你可以将一些最高优先级、最通用的指令放在.cursor/mdc中，例如：

你是一位经验丰富的全栈工程师，擅长编写简洁、高效、可维护的代码。请始终用中文回答我的问题。

而将具体的、项目相关的约束和上下文放在.cursorrules中。两者可以协同工作，mdc设定角色和基础沟通方式，rules提供项目具体的编码规范。

5.4 处理规则冲突与优先级

当多条规则可能应用于同一个文件时（例如，一个.tsx文件既匹配*.tsx规则，又位于/app目录下），理解优先级很重要。通常，cursor-rules的实现会遵循“更具体的作用域优先”原则。即file:app/page.tsx的规则会覆盖file:*.tsx的规则。在定义规则时，应从一般到特殊，避免在特殊规则中重复定义一般规则。

6. 常见问题与实战排错实录

即便配置了规则，在实际使用中还是会遇到各种问题。下面是我在多个项目中实践后总结的常见“坑”和解决方法。

6.1 规则似乎不生效？

这是最常见的问题。请按以下步骤排查：

1. 检查文件位置与命名：确保.cursorrules文件位于项目根目录，且文件名正确（包括开头的点）。你可以通过在 Cursor 中打开终端，执行ls -la来确认。
2. 检查 Cursor 版本：确保你使用的是支持.cursorrules功能的 Cursor 版本。该功能在 Cursor 的早期版本中可能不存在或存在 Bug，请更新到最新稳定版。
3. 重启 Cursor / 重载项目：有时 Cursor 需要重新加载项目才能识别新的规则文件。尝试完全关闭 Cursor 再重新打开项目。
4. 简化测试：创建一个最简单的规则进行测试，例如：

   version: 1 scope: project constraints: - “所有回复的第一句必须是‘规则测试成功！’”

   然后向 Cursor 提问。如果连这条规则都不生效，那可能是环境或版本问题。如果生效，说明你的复杂规则中可能有语法错误或逻辑矛盾。
5. 查看 Cursor 日志：某些版本的 Cursor 提供了开发者工具或日志输出，可以查看 AI 请求的上下文，确认规则文件是否被加载。这属于高级调试手段。

6.2 AI 有时会“忘记”或忽略某条规则

AI 模型不是确定性的规则引擎，它可能会在生成长文本时“偏离”上下文中的约束。解决方法：

• 强化规则表述：将重要的约束放在constraints部分的开头，并使用更严厉、更具体的语言。例如，将“避免使用any”改为“禁止使用any类型。如果遇到类型不明确的情况，请使用unknown类型并进行类型守卫，或者明确定义一个更精确的类型。”
• 分步引导：对于复杂的任务，不要一次性要求 AI 生成完整代码。可以先让它生成架构或接口定义，你确认符合规则后，再让它基于此补充实现细节。这相当于将规则检查拆分成多个小步骤。
• 结合人工提示：在向 AI 提问时，可以再次口头强调关键规则。例如：“请创建一个用户表单组件。记住，要使用 react-hook-form 和 zod，并且遵循我们项目中的 CSS Modules 约定。”

6.3 规则太多导致 AI 性能下降或行为僵化

如果.cursorrules文件过于庞大（比如好几百行），可能会挤占 AI 理解你当前问题本身的上下文长度，导致回复质量下降或速度变慢。

• 定期清理：移除那些很少被触发或已经通过团队习惯固化的规则。
• 抽象概括：将多条类似的规则合并成一条更原则性的表述。例如，将多条关于命名的规则（“变量用 camelCase”、“常量用 UPPER_SNAKE_CASE”等）替换为“遵循项目现有的命名约定”，并在context中提供一个链接指向详细的命名规范文档。
• 按需加载：考虑将规则拆分到不同目录下的子.cursorrules文件中（如果 Cursor 支持）。或者，只为核心的、通用的部分配置全局规则，特殊规则通过对话时的即时指令来补充。

6.4 如何为大型单体仓库（Monorepo）配置规则？

对于使用 pnpm/npm workspaces 或 Turborepo 的 Monorepo，你可能希望不同的子项目（packages/apps）有不同的规则。

• 理想情况：在每个子项目的根目录下放置独立的.cursorrules文件。这需要 Cursor 支持基于当前打开文件的路径来递归查找并应用最近的规则文件。你需要测试你使用的 Cursor 版本是否支持这种行为。
• 备用方案：如果 Cursor 只识别项目根目录的规则，你可以在全局.cursorrules中利用scope字段进行精细划分。

  rules: - scope: directory: /apps/web/** guidance: “这是 Next.js 前端应用，规则如下...” - scope: directory: /packages/ui/** constraints: “这是共享组件库，禁止引入业务逻辑，规则如下...” - scope: directory: /packages/api-sdk/** guidance: “这是 TypeScript API 客户端，规则如下...”

  这种方式管理起来稍显复杂，但能实现一定程度的隔离。

6.5 规则与团队代码规范的同步问题

.cursorrules应该被视为团队代码规范（如 ESLint、Prettier、提交约定）的AI 可执行版本和前置检查器。

• 互补而非替代：规则应聚焦于那些静态分析工具（ESLint）难以捕捉，但对人类和 AI 都重要的逻辑和模式约束。例如，“禁止在组件内部创建新的闭包函数”这条规则，ESLint 的exhaustive-deps规则只能在useEffect等场景下部分检测，而cursor-rules可以在代码生成阶段就预防。
• 统一来源：最好将.cursorrules中的关键约束（特别是代码风格部分）与团队的 ESLint 配置、Prettier 配置保持同步。可以定期进行交叉检查，确保两者不冲突。
• 作为新人培训工具：对于新加入团队的开发者，让他先阅读.cursorrules文件，可以快速了解项目的技术栈偏好、架构禁忌和常用模式，这比阅读冗长的文档更高效。

配置cursor-rules是一个持续磨合的过程。它不是你与 AI 之间的“对抗”，而是建立一种高效的“合作语言”。开始时规则可以少而精，随着你和 AI 在项目中配合的深入，逐步增加那些能真正提升效率和质量的规则。最终目标不是让 AI 变成一个只会照章办事的代码打字机，而是让它成为一个深刻理解项目背景和团队品味的、可靠的结对编程伙伴。