1. 项目概述从通用AI到领域专家的蜕变如果你和我一样每天都在用 Cursor IDE 写代码那你肯定经历过这样的时刻你让它帮你写一个 React 组件它却给你一个类组件的写法或者你正在构建一个 Next.js 15 的 App Router 项目它生成的代码还在用老旧的getServerSideProps。这种“牛头不对马嘴”的体验根源在于 AI 助手缺乏对特定技术栈、项目约定和最佳实践的上下文理解。它很聪明但如果没有正确的引导它给出的建议往往是通用、平庸甚至过时的。这就是hoangatg/cursor-rules-collection这个项目要解决的核心痛点。它不是一个简单的代码片段库而是一个精心设计的、社区驱动的AI 编码规则集合。简单来说你可以把它理解为给 Cursor 这个“实习生”准备的“岗位培训手册”。通过一套名为.cursorrules或.mdc的配置文件你可以明确地告诉 Cursor“在我的这个项目里我们是这样写代码的。” 这个项目汇集了超过 44 条覆盖前端、后端、移动端、数据基础设施、AI 开发乃至全栈模板的现成规则让你能一键将 Cursor 从一个“通才”变成精通你技术栈的“领域专家”。我自己从项目早期就开始使用最大的感受是开发效率和质量有了质的飞跃。以前需要反复在聊天框里解释“请用 TypeScript 严格模式”、“请遵循我们的 Tailwind CSS 原子类命名约定”、“错误处理要这样封装”现在这些规则都内化到了编辑器的“潜意识”里。AI 生成的代码从第一版开始就更贴近生产要求减少了大量沟通和返工的成本。无论你是独立开发者还是团队的技术负责人这个工具集都能帮你把 AI 编程的潜力真正释放出来。2. 核心原理.cursorrules与.mdc文件深度解析要玩转这个规则集合首先得理解 Cursor 的规则系统是如何工作的。很多人把它当成一个“高级提示词”功能这其实低估了它的设计深度。2.1 规则的本质结构化上下文注入Cursor 的规则文件无论是.cursorrules还是.mdc本质上是一种结构化、可执行的项目规范文档。它通过特定的格式和语法将你对代码风格、架构模式、安全要求、性能准则等方面的约束系统地注入到 Cursor 的代码生成和补全模型中。这和我们平时在聊天框里输入的自然语言指令有根本区别持久化与自动化规则文件保存在项目根目录对所有项目文件生效无需每次打开新文件或新会话都重复输入。结构化与可组合规则有明确的字段如description,globs,alwaysApply和章节如Architecture,Code Style逻辑清晰且多个规则可以组合使用形成复杂的约束矩阵。作用域精准通过globs字段你可以精确控制某条规则只对特定的文件类型如**/*.tsx或目录生效避免了“一刀切”的干扰。注意规则不是魔法它不能改变 AI 模型本身的能力上限但它能极大地优化模型在你特定上下文下的输出质量。你可以把它看作是一个“过滤器”或“引导器”确保 AI 的创造力被引导到符合你期望的轨道上。2.2.cursorrulesvs.mdc格式演进与最佳实践项目提到了两种格式这里需要详细拆解一下它们的区别和选用策略。.cursorrules(传统单文件格式) 这是一个 YAML 格式的文件通常直接放在项目根目录。它的优点是简单所有规则都写在一个文件里管理起来一目了然。但缺点也很明显当项目涉及多个技术栈时这个文件会变得非常臃肿难以维护且无法针对不同文件类型做精细化的规则隔离。.mdc(Markdown Cursor推荐格式) 这是 Cursor 后期引入的更先进的格式。它采用 Markdown 语法可读性更强并且支持模块化。你可以将不同技术栈的规则拆分成独立的.mdc文件全部放在项目根目录下的.cursor/rules/文件夹中。Cursor 会自动加载该文件夹下的所有.mdc文件。这是cursor-rules-collection项目主要采用的格式也是我强烈推荐的方式。实操心得如何选择对于小型或单一技术栈的项目用一个.cursorrules文件可能更轻便。但对于绝大多数现代 Web 应用尤其是全栈应用使用.cursor/rules/目录配合多个.mdc文件是更可持续的方案。它允许你像搭积木一样组合规则例如为api/目录下的文件应用fastapi.mdc和security.mdc而为app/目录下的文件应用nextjs.mdc和tailwindcss.mdc。2.3 规则文件结构解剖让我们以一个简化的react.mdc为例看看一条生产级规则到底包含什么--- description: 应用于所有 React 组件文件使用函数组件和 Hooks globs: **/*.tsx, **/*.jsx alwaysApply: false --- # React 开发规则 (v19) ## 架构原则 - **优先使用函数组件**除非有特殊理由如 Error Boundary。 - **使用 Hooks 管理状态和副作用** (useState, useEffect, useCallback, useMemo)。 - **对于复杂状态逻辑优先考虑 useReducer 或外部状态库如 Zustand**而非滥用多个 useState。 - **默认使用 export default function ComponentName() {} 语法**保持导出一致性。 ## 代码风格 - **组件命名**使用 PascalCase如 UserProfileCard。 - **Props 定义**使用 TypeScript 接口或类型并置于组件函数之上。 - **内联样式**避免使用。样式应通过 CSS Modules、Styled-components 或 Tailwind CSS 类名处理。 - **事件处理**命名格式为 handleEventName如 handleSubmit, handleClick。 ## 性能最佳实践 - **记忆化**将传递给子组件的回调函数用 useCallback 包裹将复杂计算用 useMemo 缓存。 - **避免内联对象/函数**在 JSX 中避免直接创建新的对象或函数这会导致子组件不必要的重渲染。 - **懒加载**对非首屏关键的大型组件使用 React.lazy() 和 Suspense 进行代码分割。 ## 常见模式与模板 ### 基础组件模板 tsx import { useState } from react; interface ButtonProps { label: string; onClick: () void; variant?: primary | secondary; } export default function Button({ label, onClick, variant primary }: ButtonProps) { const [isLoading, setIsLoading] useState(false); const handleClick async () { setIsLoading(true); try { await onClick(); } finally { setIsLoading(false); } }; return ( button onClick{handleClick} disabled{isLoading} className{btn btn-${variant}} {isLoading ? Loading... : label} /button ); }可以看到一条好的规则不仅仅是“要做什么”更是清晰地定义了“不要做什么”并提供了可直接参考的**代码模板**。这极大地降低了 AI 的猜测成本让它能生成更精确、更符合预期的代码。 ## 3. 实战部署如何将规则集集成到你的工作流 了解了原理下一步就是动手把它用起来。cursor-rules-collection 提供了几种集成方式各有优劣。 ### 3.1 方法一克隆整个仓库适合探索和定制 这是最全面、最灵活的方式尤其适合想要深入了解所有规则内容或计划在此基础上进行深度定制的开发者。 bash # 1. 克隆仓库到本地 git clone https://github.com/hoangatg/cursor-rules-collection.git # 2. 进入仓库目录浏览规则 cd cursor-rules-collection ls -la rules/ # 3. 将你需要的规则复制到你的项目 # 例如为你的 Next.js 项目复制相关规则 cp -r cursor-rules-collection/rules/frontend/nextjs.mdc cursor-rules-collection/rules/frontend/typescript.mdc cursor-rules-collection/rules/frontend/tailwindcss.mdc /path/to/your-project/.cursor/rules/ # 4. 复制数据层规则如果需要 cp cursor-rules-collection/rules/data-infra/prisma.mdc /path/to/your-project/.cursor/rules/注意事项克隆后rules/目录下的结构非常清晰按类别组织。你可以像逛超市一样挑选你需要的“商品”。复制到你的项目时务必确保目标路径是.cursor/rules/。如果该目录不存在需要先创建它mkdir -p .cursor/rules。建议在复制后快速浏览一下.mdc文件的内容根据你项目的具体版本如 Next.js 14 还是 15和团队约定做一些微调。例如规则里可能默认开启了某些严格的 ESLint 规则而你的项目暂时没有配置。3.2 方法二按需复制单条规则最常用对于大多数开发者我们通常很清楚自己当前项目需要什么。这时直接去 GitHub 仓库页面找到对应的规则文件复制其原始内容是最快的。访问https://github.com/hoangatg/cursor-rules-collection。导航到rules/目录下的对应子目录比如rules/frontend/。点击react.mdc文件。点击页面上的“Raw”按钮获取纯净的文本内容。全选复制然后在你项目的.cursor/rules/目录下创建一个同名文件如react.mdc粘贴进去。实操心得我强烈建议在项目中为.cursor/rules/目录也初始化一个 Git 仓库。这样你的 AI 编码规则就和项目代码一样可以进行版本管理、团队共享和迭代更新。新成员克隆项目后立刻就能获得一套统一的 AI 辅助编码规范这对保持团队代码风格一致性有巨大帮助。3.3 规则组合策略搭建你的技术栈配方单个规则威力有限真正的威力在于组合。项目文档里给出了一些流行组合我想结合自己的经验展开讲讲现代 Next.js 全栈应用nextjs.mdc确保 App Router、Server Actions、流式渲染等现代模式正确使用。typescript.mdc强制执行严格类型检查避免any。tailwindcss.mdc规范工具类使用顺序和自定义设计令牌。prisma.mdc或drizzle.mdc规范数据库查询模式和事务处理。security.mdc加入基础的安全检查如输入验证、CORS 设置。performance.mdc关注 Core Web Vitals提醒进行图片优化、字体加载等。 这样组合后当你让 Cursor 在app/api/users/route.ts中创建一个 API 路由时它会自动生成类型安全的、使用了 Prisma 的、包含错误处理和基础安全头的代码。Python FastAPI 后端服务fastapi.mdc规范 Pydantic 模型、依赖注入、路径操作装饰器。security.mdc强调 OAuth2、JWT 令牌处理、密码哈希。docker.mdc生成高效、安全的 Dockerfile 和多阶段构建配置。testing-jest.mdc或testing-pytest.mdc如果项目有引导生成结构化的异步测试用例。 这能保证你的 API 端点从一开始就具备良好的结构、文档OpenAPI和安全性。踩坑提醒规则不是越多越好。如果为同一个文件类型加载了多条存在潜在冲突的规则比如一条要求函数用function声明另一条要求用const箭头函数可能会让 Cursor 感到困惑导致输出不稳定。通常一个技术栈选择其核心框架规则加上通用的质量规则安全、性能、测试即可。4. 高级技巧与自定义规则创作当你用熟了社区提供的规则后很自然地会想“能不能为我团队特有的技术栈或内部库也创建规则” 答案是肯定的这也是这个项目生态的核心价值——可扩展性。4.1 剖析一个优秀规则的构成要素要写出高质量的.mdc规则需要把握以下几个关键部分元数据头 (---之间)description用一句话清晰描述此规则的适用场景。例如“适用于所有使用公司内部 UI 组件库company/design-system的组件”。globs这是最重要的字段之一。使用通配符精确控制作用范围。例如**/*.tsx所有 TypeScript React 文件。src/components/**/*.tssrc/components下所有子目录的.ts文件。!**/*.test.*使用!来排除测试文件。alwaysApply慎用true。通常用于那些无论文件类型、无论上下文都必须遵守的最高级别规则比如“禁止提交明文密码”、“所有函数必须有 JSDoc/TSDoc 注释”。对于技术栈规则通常设为false。规则正文分章节组织像## Architecture,## Code Style,## Best Practices,## Common Patterns这样的结构非常清晰。你可以根据自己规则的特点调整章节名。使用肯定与否定清单多用“DO: ...”、“AVOID: ...”、“NEVER: ...”这样的句式让指令明确无误。提供代码模板这是最有效的部分不要只说“请正确使用我们的 SDK”而是直接给出一个标准的调用示例。AI 非常擅长模仿模式。4.2 实战为内部工具链创建自定义规则假设你的团队有一个内部的状态管理库team/storage用法比较特殊。你可以创建一个team-storage.mdc--- description: 为所有使用 team/storage v2 进行状态管理的文件提供规则 globs: **/*.ts, **/*.tsx alwaysApply: false --- # team/storage v2 使用规范 ## 核心原则 - **单一存储实例**每个功能模块应创建且仅创建一个 createStorage 实例。 - **响应式派生**使用 storage.derive() 创建计算状态避免在组件内进行冗余计算。 - **异步操作标准化**所有异步更新必须使用 storage.withTransaction() 包裹以保证状态更新的原子性和开发者工具的可追踪性。 ## 导入与初始化 - **DO**: 在模块顶层创建并导出存储实例。 - **AVOID**: 在组件内部或函数中动态创建存储实例。 typescript // ✅ 正确示例模块级存储 import { createStorage } from team/storage; export interface UserState { id: string; name: string; profile: null | UserProfile; } export const userStorage createStorageUserState(user, { id: , name: Guest, profile: null, }); // 派生状态示例 export const isLoggedIn userStorage.derive( (state) !!state.id state.name ! Guest );在 React 组件中使用DO: 使用useStoragehook 订阅状态并使用useCallback记忆化更新函数。NEVER: 直接在组件中修改存储的.current属性。// ✅ 正确示例组件内使用 import React, { useCallback } from react; import { userStorage, isLoggedIn } from ./user-storage; import { useStorage } from team/storage/react; export default function UserProfile() { const user useStorage(userStorage); const loggedIn useStorage(isLoggedIn); const updateName useCallback((newName: string) { // 使用 withTransaction 处理可能的异步操作 userStorage.withTransaction(async (draft) { draft.name newName; // 模拟异步保存 await api.saveUserName(newName); }); }, []); if (!loggedIn) return div请登录/div; return ( div h1{user.name}/h1 input onChange{(e) updateName(e.target.value)} / /div ); }创建好这个文件后把它放进项目的 .cursor/rules/ 目录。从此以后当任何开发者在项目中请求创建或修改与状态管理相关的代码时Cursor 就会自动遵循这套内部规范极大减少了代码审查时关于“为什么不按标准来”的讨论。 ### 4.3 调试与验证规则效果 规则生效了吗效果如何有几个小技巧可以验证 1. **检查规则加载**在 Cursor 中打开命令面板 (Cmd/Ctrl Shift P)输入“Cursor: Open Rules”可以查看当前项目已加载的所有规则及其作用域。这是排查规则是否被正确加载的第一步。 2. **针对性提问**打开一个目标文件比如一个 .tsx 文件在 Cursor Chat 中直接提问“请根据我们的规则创建一个新的用户表单组件。” 观察生成的代码是否符合你规则中的约定比如是否使用了正确的存储模式、函数命名等。 3. **使用 引用**在聊天中你可以用 符号引用特定规则文件。例如输入“team-storage.mdc 请帮我修复这个组件里的状态管理代码”。这可以强制 Cursor 在本次对话中优先应用该规则。 ## 5. 常见问题排查与效能最大化指南 即使规则配置正确在实际使用中也可能遇到一些“水土不服”的情况。下面是我和社区成员遇到过的一些典型问题及解决方案。 ### 5.1 规则冲突或不生效 **症状**Cursor 生成的代码似乎没有遵循某条规则里的约定。 **排查步骤** 1. **确认文件路径**首先检查 .mdc 文件是否放在了正确的 .cursor/rules/ 目录下且目录结构正确。 2. **检查 globs 模式**这是最常见的坑。确认你当前正在编辑的文件的路径是否匹配规则中 globs 字段定义的模式。例如规则 globs: **/*.tsx 对 .jsx 或 .ts 文件无效。你可以使用在线 glob 测试工具来验证。 3. **规则优先级与冲突**如果多条规则匹配同一个文件且指令有冲突例如一条要求函数用 export default另一条要求用 export constCursor 的行为可能不可预测。解决方案是**细化 globs**让每条规则的作用域尽可能不重叠或者合并冲突的规则。 4. **重启 Cursor**有时规则文件被修改后需要重启 Cursor IDE 才能完全重新加载。 ### 5.2 生成的代码过于死板或缺乏创意 **症状**AI 完全照搬规则里的模板生成的代码千篇一律没有根据具体上下文灵活调整。 **分析与解决** * **规则是底线不是天花板**规则应该定义“必须遵守的规范”和“推荐的最佳实践”但不应该扼杀所有灵活性。避免在规则中过度规定每一行代码的写法。多使用原则性描述如“优先使用组合而非继承”少用绝对化的具体语法规定。 * **在聊天中提供额外上下文**规则是背景知识你仍然需要在聊天中清晰描述当前的具体需求。例如不要说“加个按钮”而要说“在用户名的旁边添加一个编辑图标按钮点击后弹出模态框用于修改用户名。请遵循我们的设计系统使用 primary 变体。” * **迭代式生成**不要指望一次生成完美代码。可以先让 AI 生成一个基础版本然后基于此提出更具体的修改要求如“现在需要为这个表单添加验证用户名不能为空且必须是邮箱格式”。 ### 5.3 如何管理团队间的规则差异 **场景**团队 A 使用 React Redux团队 B 使用 Vue Pinia。如何在一个大仓库中管理不同的规则 **解决方案** 利用 globs 的路径匹配能力将规则按团队或项目模块进行隔离。your-monorepo/ ├── .cursor/ │ └── rules/ │ ├── team-a-react.mdc # globs: team-a/app//* │ ├── team-a-redux.mdc # globs: team-a/app//* │ ├── team-b-vue.mdc # globs: team-b//*.vue │ └── team-b-pinia.mdc # globs: team-b//.vue ├── team-a/ │ └── app/ │ └── (React files here, will match team-a-rules) └── team-b/ └── (Vue files here, will match team-b-* rules)这样当开发者在 team-a/app/ 下工作时Cursor 应用 React/Redux 规则在 team-b/ 下则应用 Vue/Pinia 规则互不干扰。 ### 5.4 效能最大化让 AI 成为你的结对编程专家 最后分享几个让 cursor-rules-collection 发挥最大价值的习惯 1. **从项目脚手架开始**在创建新项目时第一时间就把对应的规则集配置好。让 AI 从第一行代码开始就在正确的轨道上运行。 2. **规则即文档**把你团队的 .cursor/rules/ 目录视为一种活的、可执行的编码规范文档。新成员 onboarding 时除了看传统的文档让他们浏览一遍这些规则文件能更快理解代码应该怎么写。 3. **定期回顾与更新**技术栈在更新最佳实践在演进。每个季度或每个主要版本升级时花点时间回顾一下对应的规则文件更新版本号、废弃的 API 和新的推荐模式。可以订阅 cursor-rules-collection 仓库的 Release关注社区更新。 4. **与 Linter/Formatter 结合**规则.mdc和代码检查工具ESLint, Prettier是互补的。规则指导 AI“生成什么”而 Linter 确保“生成的对不对”。两者结合能实现从代码生成到代码质量的端到端保障。 说到底hoangatg/cursor-rules-collection 提供的是一套强大的“预设”。它把社区里经过验证的最佳实践打包好让你能快速武装你的 AI 助手。但真正让它产生价值的是你根据自身项目和团队情况所做的理解和定制。花点时间去配置它、调整它你会发现它回报给你的是远超投入的流畅编码体验和更高质量的代码产出。 Cursor AI 编码规则集：从通用助手到领域专家的蜕变指南
1. 项目概述从通用AI到领域专家的蜕变如果你和我一样每天都在用 Cursor IDE 写代码那你肯定经历过这样的时刻你让它帮你写一个 React 组件它却给你一个类组件的写法或者你正在构建一个 Next.js 15 的 App Router 项目它生成的代码还在用老旧的getServerSideProps。这种“牛头不对马嘴”的体验根源在于 AI 助手缺乏对特定技术栈、项目约定和最佳实践的上下文理解。它很聪明但如果没有正确的引导它给出的建议往往是通用、平庸甚至过时的。这就是hoangatg/cursor-rules-collection这个项目要解决的核心痛点。它不是一个简单的代码片段库而是一个精心设计的、社区驱动的AI 编码规则集合。简单来说你可以把它理解为给 Cursor 这个“实习生”准备的“岗位培训手册”。通过一套名为.cursorrules或.mdc的配置文件你可以明确地告诉 Cursor“在我的这个项目里我们是这样写代码的。” 这个项目汇集了超过 44 条覆盖前端、后端、移动端、数据基础设施、AI 开发乃至全栈模板的现成规则让你能一键将 Cursor 从一个“通才”变成精通你技术栈的“领域专家”。我自己从项目早期就开始使用最大的感受是开发效率和质量有了质的飞跃。以前需要反复在聊天框里解释“请用 TypeScript 严格模式”、“请遵循我们的 Tailwind CSS 原子类命名约定”、“错误处理要这样封装”现在这些规则都内化到了编辑器的“潜意识”里。AI 生成的代码从第一版开始就更贴近生产要求减少了大量沟通和返工的成本。无论你是独立开发者还是团队的技术负责人这个工具集都能帮你把 AI 编程的潜力真正释放出来。2. 核心原理.cursorrules与.mdc文件深度解析要玩转这个规则集合首先得理解 Cursor 的规则系统是如何工作的。很多人把它当成一个“高级提示词”功能这其实低估了它的设计深度。2.1 规则的本质结构化上下文注入Cursor 的规则文件无论是.cursorrules还是.mdc本质上是一种结构化、可执行的项目规范文档。它通过特定的格式和语法将你对代码风格、架构模式、安全要求、性能准则等方面的约束系统地注入到 Cursor 的代码生成和补全模型中。这和我们平时在聊天框里输入的自然语言指令有根本区别持久化与自动化规则文件保存在项目根目录对所有项目文件生效无需每次打开新文件或新会话都重复输入。结构化与可组合规则有明确的字段如description,globs,alwaysApply和章节如Architecture,Code Style逻辑清晰且多个规则可以组合使用形成复杂的约束矩阵。作用域精准通过globs字段你可以精确控制某条规则只对特定的文件类型如**/*.tsx或目录生效避免了“一刀切”的干扰。注意规则不是魔法它不能改变 AI 模型本身的能力上限但它能极大地优化模型在你特定上下文下的输出质量。你可以把它看作是一个“过滤器”或“引导器”确保 AI 的创造力被引导到符合你期望的轨道上。2.2.cursorrulesvs.mdc格式演进与最佳实践项目提到了两种格式这里需要详细拆解一下它们的区别和选用策略。.cursorrules(传统单文件格式) 这是一个 YAML 格式的文件通常直接放在项目根目录。它的优点是简单所有规则都写在一个文件里管理起来一目了然。但缺点也很明显当项目涉及多个技术栈时这个文件会变得非常臃肿难以维护且无法针对不同文件类型做精细化的规则隔离。.mdc(Markdown Cursor推荐格式) 这是 Cursor 后期引入的更先进的格式。它采用 Markdown 语法可读性更强并且支持模块化。你可以将不同技术栈的规则拆分成独立的.mdc文件全部放在项目根目录下的.cursor/rules/文件夹中。Cursor 会自动加载该文件夹下的所有.mdc文件。这是cursor-rules-collection项目主要采用的格式也是我强烈推荐的方式。实操心得如何选择对于小型或单一技术栈的项目用一个.cursorrules文件可能更轻便。但对于绝大多数现代 Web 应用尤其是全栈应用使用.cursor/rules/目录配合多个.mdc文件是更可持续的方案。它允许你像搭积木一样组合规则例如为api/目录下的文件应用fastapi.mdc和security.mdc而为app/目录下的文件应用nextjs.mdc和tailwindcss.mdc。2.3 规则文件结构解剖让我们以一个简化的react.mdc为例看看一条生产级规则到底包含什么--- description: 应用于所有 React 组件文件使用函数组件和 Hooks globs: **/*.tsx, **/*.jsx alwaysApply: false --- # React 开发规则 (v19) ## 架构原则 - **优先使用函数组件**除非有特殊理由如 Error Boundary。 - **使用 Hooks 管理状态和副作用** (useState, useEffect, useCallback, useMemo)。 - **对于复杂状态逻辑优先考虑 useReducer 或外部状态库如 Zustand**而非滥用多个 useState。 - **默认使用 export default function ComponentName() {} 语法**保持导出一致性。 ## 代码风格 - **组件命名**使用 PascalCase如 UserProfileCard。 - **Props 定义**使用 TypeScript 接口或类型并置于组件函数之上。 - **内联样式**避免使用。样式应通过 CSS Modules、Styled-components 或 Tailwind CSS 类名处理。 - **事件处理**命名格式为 handleEventName如 handleSubmit, handleClick。 ## 性能最佳实践 - **记忆化**将传递给子组件的回调函数用 useCallback 包裹将复杂计算用 useMemo 缓存。 - **避免内联对象/函数**在 JSX 中避免直接创建新的对象或函数这会导致子组件不必要的重渲染。 - **懒加载**对非首屏关键的大型组件使用 React.lazy() 和 Suspense 进行代码分割。 ## 常见模式与模板 ### 基础组件模板 tsx import { useState } from react; interface ButtonProps { label: string; onClick: () void; variant?: primary | secondary; } export default function Button({ label, onClick, variant primary }: ButtonProps) { const [isLoading, setIsLoading] useState(false); const handleClick async () { setIsLoading(true); try { await onClick(); } finally { setIsLoading(false); } }; return ( button onClick{handleClick} disabled{isLoading} className{btn btn-${variant}} {isLoading ? Loading... : label} /button ); }可以看到一条好的规则不仅仅是“要做什么”更是清晰地定义了“不要做什么”并提供了可直接参考的**代码模板**。这极大地降低了 AI 的猜测成本让它能生成更精确、更符合预期的代码。 ## 3. 实战部署如何将规则集集成到你的工作流 了解了原理下一步就是动手把它用起来。cursor-rules-collection 提供了几种集成方式各有优劣。 ### 3.1 方法一克隆整个仓库适合探索和定制 这是最全面、最灵活的方式尤其适合想要深入了解所有规则内容或计划在此基础上进行深度定制的开发者。 bash # 1. 克隆仓库到本地 git clone https://github.com/hoangatg/cursor-rules-collection.git # 2. 进入仓库目录浏览规则 cd cursor-rules-collection ls -la rules/ # 3. 将你需要的规则复制到你的项目 # 例如为你的 Next.js 项目复制相关规则 cp -r cursor-rules-collection/rules/frontend/nextjs.mdc cursor-rules-collection/rules/frontend/typescript.mdc cursor-rules-collection/rules/frontend/tailwindcss.mdc /path/to/your-project/.cursor/rules/ # 4. 复制数据层规则如果需要 cp cursor-rules-collection/rules/data-infra/prisma.mdc /path/to/your-project/.cursor/rules/注意事项克隆后rules/目录下的结构非常清晰按类别组织。你可以像逛超市一样挑选你需要的“商品”。复制到你的项目时务必确保目标路径是.cursor/rules/。如果该目录不存在需要先创建它mkdir -p .cursor/rules。建议在复制后快速浏览一下.mdc文件的内容根据你项目的具体版本如 Next.js 14 还是 15和团队约定做一些微调。例如规则里可能默认开启了某些严格的 ESLint 规则而你的项目暂时没有配置。3.2 方法二按需复制单条规则最常用对于大多数开发者我们通常很清楚自己当前项目需要什么。这时直接去 GitHub 仓库页面找到对应的规则文件复制其原始内容是最快的。访问https://github.com/hoangatg/cursor-rules-collection。导航到rules/目录下的对应子目录比如rules/frontend/。点击react.mdc文件。点击页面上的“Raw”按钮获取纯净的文本内容。全选复制然后在你项目的.cursor/rules/目录下创建一个同名文件如react.mdc粘贴进去。实操心得我强烈建议在项目中为.cursor/rules/目录也初始化一个 Git 仓库。这样你的 AI 编码规则就和项目代码一样可以进行版本管理、团队共享和迭代更新。新成员克隆项目后立刻就能获得一套统一的 AI 辅助编码规范这对保持团队代码风格一致性有巨大帮助。3.3 规则组合策略搭建你的技术栈配方单个规则威力有限真正的威力在于组合。项目文档里给出了一些流行组合我想结合自己的经验展开讲讲现代 Next.js 全栈应用nextjs.mdc确保 App Router、Server Actions、流式渲染等现代模式正确使用。typescript.mdc强制执行严格类型检查避免any。tailwindcss.mdc规范工具类使用顺序和自定义设计令牌。prisma.mdc或drizzle.mdc规范数据库查询模式和事务处理。security.mdc加入基础的安全检查如输入验证、CORS 设置。performance.mdc关注 Core Web Vitals提醒进行图片优化、字体加载等。 这样组合后当你让 Cursor 在app/api/users/route.ts中创建一个 API 路由时它会自动生成类型安全的、使用了 Prisma 的、包含错误处理和基础安全头的代码。Python FastAPI 后端服务fastapi.mdc规范 Pydantic 模型、依赖注入、路径操作装饰器。security.mdc强调 OAuth2、JWT 令牌处理、密码哈希。docker.mdc生成高效、安全的 Dockerfile 和多阶段构建配置。testing-jest.mdc或testing-pytest.mdc如果项目有引导生成结构化的异步测试用例。 这能保证你的 API 端点从一开始就具备良好的结构、文档OpenAPI和安全性。踩坑提醒规则不是越多越好。如果为同一个文件类型加载了多条存在潜在冲突的规则比如一条要求函数用function声明另一条要求用const箭头函数可能会让 Cursor 感到困惑导致输出不稳定。通常一个技术栈选择其核心框架规则加上通用的质量规则安全、性能、测试即可。4. 高级技巧与自定义规则创作当你用熟了社区提供的规则后很自然地会想“能不能为我团队特有的技术栈或内部库也创建规则” 答案是肯定的这也是这个项目生态的核心价值——可扩展性。4.1 剖析一个优秀规则的构成要素要写出高质量的.mdc规则需要把握以下几个关键部分元数据头 (---之间)description用一句话清晰描述此规则的适用场景。例如“适用于所有使用公司内部 UI 组件库company/design-system的组件”。globs这是最重要的字段之一。使用通配符精确控制作用范围。例如**/*.tsx所有 TypeScript React 文件。src/components/**/*.tssrc/components下所有子目录的.ts文件。!**/*.test.*使用!来排除测试文件。alwaysApply慎用true。通常用于那些无论文件类型、无论上下文都必须遵守的最高级别规则比如“禁止提交明文密码”、“所有函数必须有 JSDoc/TSDoc 注释”。对于技术栈规则通常设为false。规则正文分章节组织像## Architecture,## Code Style,## Best Practices,## Common Patterns这样的结构非常清晰。你可以根据自己规则的特点调整章节名。使用肯定与否定清单多用“DO: ...”、“AVOID: ...”、“NEVER: ...”这样的句式让指令明确无误。提供代码模板这是最有效的部分不要只说“请正确使用我们的 SDK”而是直接给出一个标准的调用示例。AI 非常擅长模仿模式。4.2 实战为内部工具链创建自定义规则假设你的团队有一个内部的状态管理库team/storage用法比较特殊。你可以创建一个team-storage.mdc--- description: 为所有使用 team/storage v2 进行状态管理的文件提供规则 globs: **/*.ts, **/*.tsx alwaysApply: false --- # team/storage v2 使用规范 ## 核心原则 - **单一存储实例**每个功能模块应创建且仅创建一个 createStorage 实例。 - **响应式派生**使用 storage.derive() 创建计算状态避免在组件内进行冗余计算。 - **异步操作标准化**所有异步更新必须使用 storage.withTransaction() 包裹以保证状态更新的原子性和开发者工具的可追踪性。 ## 导入与初始化 - **DO**: 在模块顶层创建并导出存储实例。 - **AVOID**: 在组件内部或函数中动态创建存储实例。 typescript // ✅ 正确示例模块级存储 import { createStorage } from team/storage; export interface UserState { id: string; name: string; profile: null | UserProfile; } export const userStorage createStorageUserState(user, { id: , name: Guest, profile: null, }); // 派生状态示例 export const isLoggedIn userStorage.derive( (state) !!state.id state.name ! Guest );在 React 组件中使用DO: 使用useStoragehook 订阅状态并使用useCallback记忆化更新函数。NEVER: 直接在组件中修改存储的.current属性。// ✅ 正确示例组件内使用 import React, { useCallback } from react; import { userStorage, isLoggedIn } from ./user-storage; import { useStorage } from team/storage/react; export default function UserProfile() { const user useStorage(userStorage); const loggedIn useStorage(isLoggedIn); const updateName useCallback((newName: string) { // 使用 withTransaction 处理可能的异步操作 userStorage.withTransaction(async (draft) { draft.name newName; // 模拟异步保存 await api.saveUserName(newName); }); }, []); if (!loggedIn) return div请登录/div; return ( div h1{user.name}/h1 input onChange{(e) updateName(e.target.value)} / /div ); }创建好这个文件后把它放进项目的 .cursor/rules/ 目录。从此以后当任何开发者在项目中请求创建或修改与状态管理相关的代码时Cursor 就会自动遵循这套内部规范极大减少了代码审查时关于“为什么不按标准来”的讨论。 ### 4.3 调试与验证规则效果 规则生效了吗效果如何有几个小技巧可以验证 1. **检查规则加载**在 Cursor 中打开命令面板 (Cmd/Ctrl Shift P)输入“Cursor: Open Rules”可以查看当前项目已加载的所有规则及其作用域。这是排查规则是否被正确加载的第一步。 2. **针对性提问**打开一个目标文件比如一个 .tsx 文件在 Cursor Chat 中直接提问“请根据我们的规则创建一个新的用户表单组件。” 观察生成的代码是否符合你规则中的约定比如是否使用了正确的存储模式、函数命名等。 3. **使用 引用**在聊天中你可以用 符号引用特定规则文件。例如输入“team-storage.mdc 请帮我修复这个组件里的状态管理代码”。这可以强制 Cursor 在本次对话中优先应用该规则。 ## 5. 常见问题排查与效能最大化指南 即使规则配置正确在实际使用中也可能遇到一些“水土不服”的情况。下面是我和社区成员遇到过的一些典型问题及解决方案。 ### 5.1 规则冲突或不生效 **症状**Cursor 生成的代码似乎没有遵循某条规则里的约定。 **排查步骤** 1. **确认文件路径**首先检查 .mdc 文件是否放在了正确的 .cursor/rules/ 目录下且目录结构正确。 2. **检查 globs 模式**这是最常见的坑。确认你当前正在编辑的文件的路径是否匹配规则中 globs 字段定义的模式。例如规则 globs: **/*.tsx 对 .jsx 或 .ts 文件无效。你可以使用在线 glob 测试工具来验证。 3. **规则优先级与冲突**如果多条规则匹配同一个文件且指令有冲突例如一条要求函数用 export default另一条要求用 export constCursor 的行为可能不可预测。解决方案是**细化 globs**让每条规则的作用域尽可能不重叠或者合并冲突的规则。 4. **重启 Cursor**有时规则文件被修改后需要重启 Cursor IDE 才能完全重新加载。 ### 5.2 生成的代码过于死板或缺乏创意 **症状**AI 完全照搬规则里的模板生成的代码千篇一律没有根据具体上下文灵活调整。 **分析与解决** * **规则是底线不是天花板**规则应该定义“必须遵守的规范”和“推荐的最佳实践”但不应该扼杀所有灵活性。避免在规则中过度规定每一行代码的写法。多使用原则性描述如“优先使用组合而非继承”少用绝对化的具体语法规定。 * **在聊天中提供额外上下文**规则是背景知识你仍然需要在聊天中清晰描述当前的具体需求。例如不要说“加个按钮”而要说“在用户名的旁边添加一个编辑图标按钮点击后弹出模态框用于修改用户名。请遵循我们的设计系统使用 primary 变体。” * **迭代式生成**不要指望一次生成完美代码。可以先让 AI 生成一个基础版本然后基于此提出更具体的修改要求如“现在需要为这个表单添加验证用户名不能为空且必须是邮箱格式”。 ### 5.3 如何管理团队间的规则差异 **场景**团队 A 使用 React Redux团队 B 使用 Vue Pinia。如何在一个大仓库中管理不同的规则 **解决方案** 利用 globs 的路径匹配能力将规则按团队或项目模块进行隔离。your-monorepo/ ├── .cursor/ │ └── rules/ │ ├── team-a-react.mdc # globs: team-a/app//* │ ├── team-a-redux.mdc # globs: team-a/app//* │ ├── team-b-vue.mdc # globs: team-b//*.vue │ └── team-b-pinia.mdc # globs: team-b//.vue ├── team-a/ │ └── app/ │ └── (React files here, will match team-a-rules) └── team-b/ └── (Vue files here, will match team-b-* rules)这样当开发者在 team-a/app/ 下工作时Cursor 应用 React/Redux 规则在 team-b/ 下则应用 Vue/Pinia 规则互不干扰。 ### 5.4 效能最大化让 AI 成为你的结对编程专家 最后分享几个让 cursor-rules-collection 发挥最大价值的习惯 1. **从项目脚手架开始**在创建新项目时第一时间就把对应的规则集配置好。让 AI 从第一行代码开始就在正确的轨道上运行。 2. **规则即文档**把你团队的 .cursor/rules/ 目录视为一种活的、可执行的编码规范文档。新成员 onboarding 时除了看传统的文档让他们浏览一遍这些规则文件能更快理解代码应该怎么写。 3. **定期回顾与更新**技术栈在更新最佳实践在演进。每个季度或每个主要版本升级时花点时间回顾一下对应的规则文件更新版本号、废弃的 API 和新的推荐模式。可以订阅 cursor-rules-collection 仓库的 Release关注社区更新。 4. **与 Linter/Formatter 结合**规则.mdc和代码检查工具ESLint, Prettier是互补的。规则指导 AI“生成什么”而 Linter 确保“生成的对不对”。两者结合能实现从代码生成到代码质量的端到端保障。 说到底hoangatg/cursor-rules-collection 提供的是一套强大的“预设”。它把社区里经过验证的最佳实践打包好让你能快速武装你的 AI 助手。但真正让它产生价值的是你根据自身项目和团队情况所做的理解和定制。花点时间去配置它、调整它你会发现它回报给你的是远超投入的流畅编码体验和更高质量的代码产出。