Cursor AI 编码助手行为规则集：定制化配置提升代码生成质量与一致性

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

如果你和我一样，深度依赖 Cursor 这款 AI 驱动的代码编辑器，那你一定经历过这样的时刻：面对一个复杂的重构任务，你满怀期待地输入指令，结果 AI 助手生成的代码风格和你项目里现有的完全对不上，或者它自作主张地引入了你明令禁止的库。每次都要在提示词里重复“请遵循 ESLint 规则”、“使用函数式组件”、“不要用any类型”，不仅繁琐，而且效果时好时坏。

“Anuar-boop/cursor-rules”这个项目，就是为了根治这个问题而生的。它不是一个普通的代码库，而是一套精心设计的、用于约束和引导 Cursor 编辑器内置 AI 助手（Cursor Agent）行为的规则配置文件。你可以把它理解为给 Cursor AI 安装了一个“人格”或“工作手册”。通过这套规则，你可以明确告诉 AI：我们这个项目用什么技术栈、代码风格是什么、有哪些最佳实践必须遵守、哪些雷区绝对不能踩。从此，AI 生成的代码不再是“开盲盒”，而是高度符合你团队规范和项目上下文的高质量产出。

这套规则集的核心价值在于将“人适应 AI”转变为“AI 适应人”。它特别适合团队负责人、架构师以及追求代码一致性和开发效率的独立开发者。无论你是想在新项目中快速统一技术栈，还是希望将既有项目的庞大规范沉淀下来并自动化执行，cursor-rules 都提供了一个可扩展、可版本化管理的解决方案。接下来，我将带你彻底拆解这个项目，从设计思路到每一个配置项的实战含义，让你不仅能用好它，更能根据自己团队的需求定制出专属的“AI 开发宪法”。

2. 规则集的核心设计哲学与架构解析

2.1 为什么需要专门的 AI 行为规则？

在深入代码之前，我们必须先理解问题的本质。Cursor 等 AI 编码工具的底层模型（如 GPT-4）是通用的，它拥有海量的编程知识，但并不天然了解你当前这个特定项目的独特要求。这种信息差会导致几个典型问题：

1. 上下文不一致：AI 可能用 Python 的snake_case命名法来写你的 JavaScript 项目（后者通常用camelCase）。
2. 技术栈混淆：你项目用的是 React + TypeScript，但 AI 可能会生成带有PropTypes（React 旧版类型检查）的代码，或者使用未被项目依赖的第三方库。
3. 规范无视：项目明明配置了严格的 ESLint 和 Prettier，AI 生成的代码却充满了格式错误和风格违规，导致提交前需要大量手动修正。
4. 安全与最佳实践缺失：对于敏感操作（如直接操作 DOM、不安全的eval使用），AI 可能不会主动给出风险提示或替代方案。

“cursor-rules”的设计哲学，就是通过一个结构化的配置文件，主动、系统地向 AI 注入这些项目特定的“上下文”和“约束”。这比在每次对话中零散地输入提示词要高效、可靠得多。它的目标不是限制 AI 的创造力，而是为它的创造力框定一个正确、安全的发挥舞台。

2.2 规则集的模块化架构

Anuar-boop 的 cursor-rules 项目通常采用一种模块化、层次清晰的架构。虽然具体文件结构可能演变，但其核心思想包含以下几个层面：

2.2.1 全局规则与上下文定义这是规则的基石，位于配置文件（如.cursor/rules/global.mdc或cursorrules.json）的顶层。它定义了 AI 在整个项目范围内必须知晓和遵守的元信息。例如：

• 项目技术栈：明确声明项目使用 “React 18, TypeScript 5.x, Tailwind CSS 3.x”。
• 核心编码规范：指定主要的代码风格，如 “遵循 Airbnb JavaScript Style Guide”。
• 绝对禁令：列出无论如何都不能使用的模式或库，如 “禁止使用var关键字”、“禁止直接引入lodash整个包”。
• 核心目标：阐明项目的首要原则，如 “性能优先”、“可访问性（a11y）必须达标”。

这个层面的规则为 AI 建立了最基本的认知框架。

2.2.2 技术栈/框架特定规则在全局规则之下，会针对不同的技术栈设立更细致的规则。例如：

• React 规则：可能要求“优先使用函数组件和 Hooks”、“默认导出 React 组件”、“Props 必须使用 TypeScript 接口定义”。
• TypeScript 规则：可能要求“禁止使用any类型”、“必须为函数返回值显式定义类型”。
• 测试规则：可能规定“使用 Jest 和 React Testing Library”、“每个组件必须包含基础渲染测试”。

这些规则确保了 AI 在特定领域内的输出符合该领域的最佳实践。

2.2.3 目录/功能模块特定规则这是最精细化的控制层。你可以为项目的不同部分设置不同的规则。例如：

• /src/hooks/目录：规则可能是“自定义 Hook 必须以use前缀开头”、“必须包含清晰的 JSDoc 注释说明其作用和返回值”。
• /src/utils/目录：规则可能是“工具函数必须是纯函数”、“必须包含单元测试”。
• /src/pages/目录：规则可能是“页面组件使用Page后缀”、“必须处理加载和错误状态”。

通过这种分层、分模块的架构，规则集既能提供全局一致的约束，又能满足不同代码区域的特殊要求，实现了灵活性与控制力的平衡。

3. 核心规则配置详解与实战编写指南

理解了架构，我们来亲手编写和解读几个核心规则配置。Cursor 的规则通常支持多种格式，如 Markdown (.mdc)、JSON 或 YAML。这里以功能强大、可读性高的 Markdown 格式为例。

3.1 定义项目的“宪法”：全局规则

创建一个文件.cursor/rules/project-constitution.mdc。这个文件的名字可以自定，但放在.cursor/rules/目录下是关键。

# 项目全局开发宪法 ## 核心上下文 - **项目名称**: 新一代电商管理后台 (NextGen E-Commerce Admin) - **核心栈**: Next.js 14 (App Router), TypeScript 5.5, Tailwind CSS 3.4, Shadcn/ui 组件库 - **状态管理**: Zustand - **数据获取**: TanStack Query (React Query) v5 - **代码风格**: 项目已配置 ESLint (Next.js 官方配置) 和 Prettier。所有生成的代码必须**直接通过**现有 lint 和 format 检查，无需修改。 ## 绝对原则与禁令 1. **禁止 any 类型**: 在任何情况下都不允许使用 `any` 类型。如果暂时无法确定类型，使用 `unknown` 并辅以类型守卫。 2. **禁止默认导出**: 除了 Next.js 页面 (`page.tsx`) 和布局 (`layout.tsx`)，所有 React 组件、工具函数、常量均应使用**命名导出**。 3. **禁止内联样式**: 除动态计算样式外，所有样式必须通过 Tailwind CSS 类名实现。禁止使用 `style={{}}`。 4. **禁止直接控制台输出**: 生产代码中禁止使用 `console.log`、`console.error` 等。如需调试，使用项目内置的 `logger` 工具。 5. **安全红线**: 禁止生成包含 `eval()`、`innerHTML`（除非使用 `dangerouslySetInnerHTML` 且有充分消毒）、硬编码密钥或敏感信息的代码。 ## 默认行为与模式 - **组件设计**: 优先采用函数组件 + React Hooks。组件应小而专注，符合单一职责原则。 - **错误处理**: 异步操作必须使用 `try-catch` 进行错误捕获，并向用户展示友好的错误信息。 - **可访问性**: 所有交互式元素必须具有适当的 ARIA 属性，图片必须有 `alt` 文本。

注意：全局规则是最高纲领，要简洁、有力。这里定义的“禁令”应该是那些一旦违反就需要重构的严重问题。过于琐碎的规则（如缩进是2空格还是4空格）应该交给 ESLint/Prettier 管理，而不是在这里重复。

3.2 针对框架的精细化规则：以 React 组件为例

创建.cursor/rules/react-components.mdc，这个文件只对 React 组件代码的生成进行约束。

# React 组件开发规范 ## 适用范围 此规则适用于 `src/components/`、`src/app/` 下所有 React 组件文件（`.tsx`）。 ## 组件结构 1. **导入顺序**： 1. React / Next.js 核心库 2. 第三方库 3. 项目内部组件 4. 项目内部工具函数/常量 5. 类型定义 6. 样式导入（如有） 每个分组间用一个空行分隔。 2. **组件定义**： - 使用 `const ComponentName = (props: ComponentProps) => { ... }` 箭头函数语法。 - 立即对 `props` 进行解构。 - 组件名必须使用 PascalCase。 3. **Props 类型定义**： - **必须**使用 `interface`（而非 `type`）定义 Props，以便于扩展。 - 为每个 prop 添加清晰的 JSDoc 注释，说明其用途、是否可选、默认值。 ```typescript interface ButtonProps { /** 按钮显示的文本 */ children: React.ReactNode; /** 按钮的点击事件处理函数 */ onClick?: () => void; /** 按钮的视觉变体，默认为 'primary' */ variant?: 'primary' | 'secondary' | 'ghost'; /** 是否禁用按钮 */ disabled?: boolean; } ``` ## 状态与副作用管理 1. **状态**：优先使用 `useState`。复杂状态逻辑应考虑提取到自定义 Hook 或 Zustand Store 中。 2. **副作用**：`useEffect` 必须包含清晰的依赖数组。如果依赖项是对象或数组，考虑使用 `useMemo` 或 `useCallback` 来稳定引用。 3. **性能**：对于可能昂贵的计算或函数，主动使用 `useMemo` 和 `useCallback` 进行优化，并在注释中说明原因。 ## 组件示例模式 当被要求创建一个新组件时，请按照以下完整示例结构生成： ```typescript import { cn } from '@/lib/utils'; // 假设的工具函数 interface ExampleComponentProps { // ... props 定义 } export const ExampleComponent = ({ // ... 解构 props }: ExampleComponentProps) => { // 1. 状态与 Hook 调用 // 2. 逻辑处理函数 // 3. 渲染返回 return ( <div className={cn('base-classes', conditionalClasses)}> {/* 组件内容 */} </div> ); };

实操心得：为组件定义“示例模式”极其有效。这相当于给了 AI 一个具体的模板，它生成代码的格式和结构会高度一致，大大减少了后续的格式化调整工作。同时，强制要求 JSDoc 注释，虽然增加了生成的代码量，但从长远看，这些注释本身就是最好的文档，对团队协作和后期维护价值巨大。

3.3 利用上下文感知：目录级规则

在.cursor/rules下创建子目录，可以使其中的规则仅对特定目录生效。例如，创建.cursor/rules/src-hooks/index.mdc。

# 自定义 Hook 开发规范 ## 适用范围 此规则仅对 `src/hooks/` 目录下的文件生效。 ## 核心规范 1. **命名**：Hook 文件名必须为 `use*.ts`，Hook 函数名必须为 `use*`（如 `useLocalStorage`, `useDebounce`）。 2. **返回值**：必须返回一个数组或对象，以支持使用者进行重命名。优先使用元组 `[state, setState]` 或对象 `{ value, update }` 的形式。 3. **依赖注入**：如果 Hook 接收参数，应提供合理的默认值，并确保参数变化时 Hook 行为正确更新。 4. **错误边界**：Hook 内部应妥善处理错误，避免将未捕获的错误抛给组件。可以考虑返回一个 `error` 状态。 5. **类型完备**：必须完整导出 Hook 的参数类型和返回值类型。 ## 示例模板 ```typescript import { useState, useEffect } from 'react'; interface UseCustomHookOptions { /** 配置选项一 */ option1?: string; /** 配置选项二，默认值 100 */ option2?: number; } interface UseCustomHookReturn { /** 当前状态值 */ value: SomeType; /** 更新状态的方法 */ update: (newValue: SomeType) => void; /** 是否正在加载 */ isLoading: boolean; /** 可能发生的错误 */ error: Error | null; } /** * 一个描述 Hook 功能的详细说明。 * @param {UseCustomHookOptions} options - Hook 的配置选项 * @returns {UseCustomHookReturn} 返回状态和控制方法 */ export const useCustomHook = ( options: UseCustomHookOptions = {} ): UseCustomHookReturn => { const { option1 = 'default', option2 = 100 } = options; const [value, setValue] = useState<SomeType>(initialValue); const [isLoading, setIsLoading] = useState(false); const [error, setError] = useState<Error | null>(null); useEffect(() => { // Hook 的核心逻辑 }, [option1, option2]); // 依赖项必须明确 const update = (newValue: SomeType) => { // 更新逻辑 }; return { value, update, isLoading, error }; };

通过目录级规则，你可以实现“在什么位置，做什么事，就按什么规矩来”的精准控制，这是提升 AI 生成代码上下文相关性的关键。

4. 规则集的生效机制与高级调试技巧

4.1 Cursor 如何加载和应用规则？

Cursor 编辑器会在项目根目录下寻找.cursor文件夹，并自动加载rules子目录下的所有规则文件。其应用逻辑通常遵循以下优先级：

1. 目录特异性规则优先：如果当前打开的文件位于src/hooks/下，那么src-hooks/index.mdc中的规则将优先于全局规则被应用和强化。
2. 规则合并：AI 会综合所有适用的规则。目录规则不会覆盖全局规则，而是在其基础上增加更具体的约束。如果出现冲突（极为罕见，应避免），更具体（目录级）的规则可能权重更高。
3. 上下文注入：当你选中一段代码或光标位于某个文件时，Cursor Agent 会将当前文件路径、语言以及所有适用的规则内容，作为系统提示词（System Prompt）的一部分，发送给底层的大语言模型。这就是 AI 能“知晓”你项目规范的原因。

4.2 验证规则是否生效

一个简单的测试方法是，在受规则约束的目录下，向 Cursor Agent 提出一个明显会违反规则的要求。

测试案例：在src/components/目录下，向 Cursor 提问：“创建一个显示‘Hello World’的按钮组件，使用默认导出。”

期望的 AI 回复：

我将为您创建一个按钮组件。根据项目规则，我们使用命名导出而非默认导出，并遵循 TypeScript 和 Tailwind CSS 规范。

import { ButtonHTMLAttributes, ReactNode } from 'react'; import { cn } from '@/lib/utils'; interface HelloWorldButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> { children?: ReactNode; } export const HelloWorldButton = ({ children, className, ...props }: HelloWorldButtonProps) => { return ( <button className={cn( 'px-4 py-2 bg-blue-500 text-white rounded-md hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-300', className )} {...props} > {children || 'Hello World'} </button> ); };

如果 AI 的回复遵循了你的规则（如使用了命名导出export const、使用了interface、集成了cn函数、使用了 Tailwind 类名），说明规则已成功加载。如果它仍然使用了默认导出，则需要检查规则文件路径、格式或重启 Cursor。

4.3 高级技巧：条件规则与外部引用

1. 基于环境的条件规则：你可以创建不同的规则集，并通过简单的脚本或手动方式，将.cursor/rules链接到不同的规则集目录。例如，为“新项目启动”准备一套宽松的、鼓励探索的规则，为“核心生产代码”准备一套严格的规则。

2. 引用外部文档：在规则文件中，你可以引用项目中的其他文档，让 AI 去学习。

   # 请务必在编写 API 调用相关代码前，参考项目中的 API 设计文档： # 文件路径：`./docs/api-conventions.md` # 该文档规定了所有请求必须使用 `useQuery` 或 `useMutation`，错误处理格式等。

   虽然 AI 不一定能实时读取被引用的文件，但这是一种很好的提示，有时 AI 在之前的上下文中已经了解过该文件内容。

3. 规则冲突与调试：如果发现 AI 行为不符合预期，可以打开 Cursor 的“Composer”界面（通常通过快捷键Cmd/Ctrl + K触发），在输入指令前，观察系统是否自动添加了相关的规则上下文。你也可以在指令中明确要求 AI 解释其决策依据，例如：“请按照我们的 React 组件规则创建一个模态框，并说明你的实现如何满足了规则中的每一条要求。” 这既能检验规则效果，也能帮助你优化规则表述。

5. 常见问题排查与规则优化实录

在实际部署和使用 cursor-rules 的过程中，你肯定会遇到一些困惑和问题。下面是我踩过坑后总结出的常见问题与解决方案。

5.1 规则不生效或部分不生效

5.2 规则编写中的“坑”与最佳实践

1. 避免规则过于宽泛和模糊：

   • 差：“写出高质量的代码。”
   • 优：“函数长度原则上不超过 50 行。超过时，请主动建议将其拆分为更小的函数。”
   • 原因：AI 对“高质量”的理解是模糊的，而具体的行数限制是可执行的指令。

2. 用正面引导代替负面禁止（当可能时）：

   • 差：“不要写内联样式。”
   • 优：“所有样式请通过 Tailwind CSS 工具类实现。例如，使用className=”px-4 py-2 bg-blue-500″而非style={{ padding: ‘1rem’, backgroundColor: ‘blue’ }}。”
   • 原因：告诉 AI“应该怎么做”，比单纯告诉它“不要怎么做”更有效，因为它有了明确的行动路径。

3. 规则之间保持一致性，避免矛盾：

   • 坑：全局规则说“使用函数组件”，但某个目录规则又说“使用类组件”。这会让 AI 困惑。
   • 解决：在编写规则前，规划好规则的层次和范围。全局规则定基调，具体规则做补充和微调，绝不冲突。

4. 规则需要迭代和更新：

   • 不要指望一套规则一劳永逸。随着项目技术栈更新、团队共识变化，规则也需要调整。将.cursor/rules/目录纳入版本控制（如 Git），像管理代码一样管理你的规则。在团队中，可以设立一个“规则维护”的角色，定期根据大家的反馈进行更新。

5.3 衡量规则集带来的收益

如何判断这套规则是否真的提升了效率？可以从以下几个维度观察：

1. 代码审查成本：AI 生成的代码提交后，需要人工指出的规范性问题是否显著减少？
2. 提示词复杂度：你是否不再需要在新对话中反复粘贴一长串项目规范？指令是否变得更简单、更专注于业务逻辑本身？
3. 新人上手速度：新成员使用配置好规则的 Cursor，是否能更快地生成符合项目风格的代码？
4. 心理负担：你是否更放心地让 AI 去生成或修改大段代码，而不必担心它会“搞破坏”？

我个人在引入 cursor-rules 后，最直观的感受是，与 AI 协作的“摩擦系数”大大降低。我不再是一个“代码审查员”，而更像是一个“产品经理”，只需要描述清楚“要什么”，AI 就能以我熟悉的“语言和格式”交付成果。这种体验上的提升，远比节省的几分钟格式化时间更有价值。

最后，记住 cursor-rules 的本质是一个沟通工具，是你与 AI 助手之间的“合作协议”。花时间精心编写和维护这份协议，你将在未来的每一个开发日里，持续获得丰厚的回报。