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是通用的它拥有海量的编程知识但并不天然了解你当前这个特定项目的独特要求。这种信息差会导致几个典型问题上下文不一致AI 可能用 Python 的snake_case命名法来写你的 JavaScript 项目后者通常用camelCase。技术栈混淆你项目用的是 React TypeScript但 AI 可能会生成带有PropTypesReact 旧版类型检查的代码或者使用未被项目依赖的第三方库。规范无视项目明明配置了严格的 ESLint 和 PrettierAI 生成的代码却充满了格式错误和风格违规导致提交前需要大量手动修正。安全与最佳实践缺失对于敏感操作如直接操作 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*.tsHook 函数名必须为 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] useStateSomeType(initialValue); const [isLoading, setIsLoading] useState(false); const [error, setError] useStateError | null(null); useEffect(() { // Hook 的核心逻辑 }, [option1, option2]); // 依赖项必须明确 const update (newValue: SomeType) { // 更新逻辑 }; return { value, update, isLoading, error }; };通过目录级规则你可以实现“在什么位置做什么事就按什么规矩来”的精准控制这是提升 AI 生成代码上下文相关性的关键。4. 规则集的生效机制与高级调试技巧4.1 Cursor 如何加载和应用规则Cursor 编辑器会在项目根目录下寻找.cursor文件夹并自动加载rules子目录下的所有规则文件。其应用逻辑通常遵循以下优先级目录特异性规则优先如果当前打开的文件位于src/hooks/下那么src-hooks/index.mdc中的规则将优先于全局规则被应用和强化。规则合并AI 会综合所有适用的规则。目录规则不会覆盖全局规则而是在其基础上增加更具体的约束。如果出现冲突极为罕见应避免更具体目录级的规则可能权重更高。上下文注入当你选中一段代码或光标位于某个文件时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 ButtonHTMLAttributesHTMLButtonElement { 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 高级技巧条件规则与外部引用基于环境的条件规则你可以创建不同的规则集并通过简单的脚本或手动方式将.cursor/rules链接到不同的规则集目录。例如为“新项目启动”准备一套宽松的、鼓励探索的规则为“核心生产代码”准备一套严格的规则。引用外部文档在规则文件中你可以引用项目中的其他文档让 AI 去学习。# 请务必在编写 API 调用相关代码前参考项目中的 API 设计文档 # 文件路径./docs/api-conventions.md # 该文档规定了所有请求必须使用 useQuery 或 useMutation错误处理格式等。虽然 AI 不一定能实时读取被引用的文件但这是一种很好的提示有时 AI 在之前的上下文中已经了解过该文件内容。规则冲突与调试如果发现 AI 行为不符合预期可以打开 Cursor 的“Composer”界面通常通过快捷键Cmd/Ctrl K触发在输入指令前观察系统是否自动添加了相关的规则上下文。你也可以在指令中明确要求 AI 解释其决策依据例如“请按照我们的 React 组件规则创建一个模态框并说明你的实现如何满足了规则中的每一条要求。” 这既能检验规则效果也能帮助你优化规则表述。5. 常见问题排查与规则优化实录在实际部署和使用 cursor-rules 的过程中你肯定会遇到一些困惑和问题。下面是我踩过坑后总结出的常见问题与解决方案。5.1 规则不生效或部分不生效问题现象可能原因解决方案AI 完全无视规则生成风格迥异的代码。1. 规则文件未放在正确的.cursor/rules/目录下。2. 规则文件格式错误如 JSON 语法错误。3. Cursor 未正确加载项目上下文例如在未打开项目的情况下使用。1. 确认项目根目录存在.cursor/rules/文件夹且规则文件在其中。2. 检查文件格式对于.mdc文件确保是纯 Markdown对于.json文件使用 JSON 校验器检查。3. 在 Cursor 中打开项目根目录确保编辑器顶部显示的是项目名称。全局规则生效但目录级规则不生效。1. 目录级规则的文件路径或命名不符合 Cursor 的识别约定。2. 当前编辑的文件不在该目录级规则的适用路径内。1. 确认目录级规则文件路径例如src-components对应src/components/目录。参考官方文档确认命名模式。2. 检查文件保存位置。规则是基于文件物理路径的。AI 遵守了大部分规则但某一条特定规则如“禁止使用any”被忽略。1. 规则描述可能不够清晰或强硬。2. AI 在特定复杂场景下认为无法避免使用any。1. 强化规则表述。将“避免使用any”改为“禁止在任何情况下使用any类型。如果无法确定类型使用unknown并说明原因。”2. 在规则中提供替代方案和示例降低 AI 的“执行难度”。5.2 规则编写中的“坑”与最佳实践避免规则过于宽泛和模糊差“写出高质量的代码。”优“函数长度原则上不超过 50 行。超过时请主动建议将其拆分为更小的函数。”原因AI 对“高质量”的理解是模糊的而具体的行数限制是可执行的指令。用正面引导代替负面禁止当可能时差“不要写内联样式。”优“所有样式请通过 Tailwind CSS 工具类实现。例如使用className”px-4 py-2 bg-blue-500″而非style{{ padding: ‘1rem’, backgroundColor: ‘blue’ }}。”原因告诉 AI“应该怎么做”比单纯告诉它“不要怎么做”更有效因为它有了明确的行动路径。规则之间保持一致性避免矛盾坑全局规则说“使用函数组件”但某个目录规则又说“使用类组件”。这会让 AI 困惑。解决在编写规则前规划好规则的层次和范围。全局规则定基调具体规则做补充和微调绝不冲突。规则需要迭代和更新不要指望一套规则一劳永逸。随着项目技术栈更新、团队共识变化规则也需要调整。将.cursor/rules/目录纳入版本控制如 Git像管理代码一样管理你的规则。在团队中可以设立一个“规则维护”的角色定期根据大家的反馈进行更新。5.3 衡量规则集带来的收益如何判断这套规则是否真的提升了效率可以从以下几个维度观察代码审查成本AI 生成的代码提交后需要人工指出的规范性问题是否显著减少提示词复杂度你是否不再需要在新对话中反复粘贴一长串项目规范指令是否变得更简单、更专注于业务逻辑本身新人上手速度新成员使用配置好规则的 Cursor是否能更快地生成符合项目风格的代码心理负担你是否更放心地让 AI 去生成或修改大段代码而不必担心它会“搞破坏”我个人在引入 cursor-rules 后最直观的感受是与 AI 协作的“摩擦系数”大大降低。我不再是一个“代码审查员”而更像是一个“产品经理”只需要描述清楚“要什么”AI 就能以我熟悉的“语言和格式”交付成果。这种体验上的提升远比节省的几分钟格式化时间更有价值。最后记住 cursor-rules 的本质是一个沟通工具是你与 AI 助手之间的“合作协议”。花时间精心编写和维护这份协议你将在未来的每一个开发日里持续获得丰厚的回报。