1. 项目概述为什么我们需要为AI编码助手制定规则如果你和我一样从VS Code切换到Cursor最初那阵子可能会被它的“聪明”所震撼但很快也会被它的“自作主张”所困扰。它生成的代码风格可能和你团队的标准不符它可能在不该使用某个内部库的地方用了或者它写出的React组件结构总是和你期望的不一样。这就像给一个天赋异禀但缺乏经验的实习生布置任务如果不把项目背景、代码规范和你的个人偏好交代清楚他交上来的东西很可能需要你花大量时间重构。这正是digitalchild/cursor-best-practices这个项目试图解决的问题。它不是一个简单的功能列表而是一套关于如何“驯化”Cursor让它从一个通用的AI编码工具转变为你个人或团队专属的、高度定制化的开发伙伴的完整方法论。其核心在于规则Rules和上下文Context的体系化构建。通过这套体系你可以将项目的架构决策、编码规范、技术栈偏好乃至工作流习惯“灌输”给Cursor从而让它的每一次代码生成、每一次问题解答都更精准、更符合预期最终将开发效率的提升从“偶尔的惊喜”变成“稳定的常态”。2. 规则体系深度解析从全局到局部的精准控制Cursor的规则系统设计得非常精巧它允许你在不同粒度上进行控制从你个人的全局编码习惯到特定项目的技术规范再到单个文件类型的处理方式。理解这套层次结构是高效使用Cursor的第一步。2.1 规则优先级当多条规则冲突时谁说了算这是最容易被忽略但至关重要的一点。Cursor不是简单地把所有规则堆在一起而是有一套明确的优先级顺序。想象一下交通规则有全球通用的靠右行驶有城市特定的某条路单行还有临时性的施工绕行。AI会优先遵守最具体、最临时的指令。Cursor的规则优先级从高到低如下本地手动规则在聊天或Composer中你用ruleName显式引用的规则。这是最高指令相当于你当面给AI下的命令。自动附加规则当AI处理的文件路径匹配某个规则中定义的globs模式时该规则会被自动加入上下文。这是“场景化”智能的核心。代理请求规则如果一条规则包含了清晰的description描述AI在认为需要时可以主动选择将其纳入考虑范围。这给了AI一定的自主判断权。始终应用规则在规则文件中设置了alwaysApply: true的规则。这些是项目的“宪法”在任何情况下都会被加载。实操心得我通常将最基础、最不容违反的规范如基础代码风格、安全红线设为alwaysApply。将针对特定目录或文件类型的规则如src/api/**/*.ts下的API响应格式设为auto attached。而那些处理非常规场景的“锦囊妙计”规则则写好description留给AI在需要时自行取用。这样既保证了核心规范的强制性又避免了上下文过度臃肿。2.2 用户规则你的个人编码“口音”用户规则在Cursor设置 Rules中配置它作用于你的整个Cursor环境无论打开哪个项目。这相当于设定了你和AI对话的“基调和口音”。作用定义你希望AI回应的整体风格和你的个人通用偏好。格式纯文本不支持.mdc的元数据格式。典型用例风格控制请用简洁、直接的语言回复避免不必要的客套和重复解释。语言偏好所有代码注释请使用中文。通用原则在提供方案时请优先考虑可读性和可维护性而非最简短的代码。注意用户规则因为全局生效要避免写入过于具体的项目技术细节否则在其他不相关的项目中可能会造成干扰。2.3 项目规则.mdc文件团队的技术“宪法”这是规则系统的核心也是cursor-best-practices项目主要探讨的内容。项目规则以.mdc文件的形式存放在项目根目录的.cursor/rules/文件夹下并可以纳入版本控制如Git。这意味着所有克隆该项目的团队成员都能获得完全一致的AI辅助体验。一个.mdc文件包含两个部分Frontmatter元数据和Body规则正文。Frontmatter 示例与解析--- description: “API服务层规范” # 规则的简要描述用于AI识别和手动引用 globs: [“src/services/**/*.ts”, “src/api/**/*.ts”] # 文件路径匹配模式决定规则何时被自动附加 alwaysApply: false # 是否始终应用。通常设为false通过globs或手动触发更高效。 ---Body 正文编写技巧规则正文就是给AI的指令。写得好坏直接决定AI的理解程度。使用肯定、明确的语句避免“最好不要”而是说“必须使用”或“禁止使用”。结构化列举使用-列表或1.2.编号来分条陈述清晰明了。提供正反例这对于规范学习非常有效。- 定义API响应类型必须使用 ApiResponseT 泛型接口。 - 正确: async getUser(): PromiseApiResponseUser { ... } - 错误: async getUser(): PromiseUser { ... }引用具体文件使用符号引用项目内的文件作为示例或模板为AI提供最具体的上下文。- 新的工具函数应参考 src/utils/stringHelper.ts 中的格式和注释风格进行创建。快速创建规则在Cursor中按下CmdShiftP(Mac) /CtrlShiftP(Windows)输入“New Cursor Rule”可以快速在.cursor/rules/目录下生成一个规则模板文件非常方便。3. 构建高价值规则库从何写起写些什么面对一个新项目可能会感到无从下手。cursor-best-practices给出了一个极佳的思考框架我们可以将其理解为构建项目专属AI知识库的“目录”。以下是我结合实践梳理的核心模块和编写要点。3.1 项目与架构概览规则这类规则帮助AI理解项目的全貌相当于给AI一份“项目入职手册”。文件示例project-overview.mdc核心内容项目描述用一两句话说明这个项目是做什么的例如一个基于Next.js 14的SaaS后台管理系统采用微前端架构。核心架构图虽然不能直接贴图但可以用文字描述关键模块及其关系。例如“前端层与后端BFF层通过GraphQL通信BFF层聚合多个下游微服务。”关键设计决策解释为什么选择某些技术或架构。例如“状态管理使用Zustand而非Redux Toolkit因为本项目状态结构简单Zustand的简洁性更合适。”目录结构说明解释主要目录的职责。例如src/components/common/存放可复用UI组件src/hooks/存放自定义React Hooks。3.2 技术栈与开发规范规则这是规则库中最具体、最常用的一部分直接决定了生成代码的质量。文件示例coding-standards.mdc,react-guidelines.mdc,tailwind-config.mdc核心内容代码风格缩进、分号、引号、尾随逗号等。虽然部分可由Prettier管理但明确写出能让AI在生成时就符合预期。命名约定- 变量/函数小驼峰 camelCase - 组件大驼峰 PascalCase - 常量全大写 UPPER_SNAKE_CASE - 类型/接口大驼峰 PascalCase并以 Type 或 Interface 后缀区分可选。 - 文件名React组件使用 PascalCase工具类/钩子使用 camelCase。框架/库特定规则React函数组件优先何时使用useMemo/useCallbackProps的定义方式typevsinterface。Tailwind CSS颜色、间距使用设计系统中的特定值如bg-primary-500,p-4禁止任意颜色值。状态管理定义Store的模板如何分割Store逻辑。API交互必须使用封装的request工具函数错误处理的统一模式。安全与性能红线- 禁止直接将用户输入拼接至SQL查询或shell命令。 - 在渲染列表时必须为每个项提供稳定的 key 属性。 - 避免在组件渲染函数内创建新的对象/函数除非将其作为Hook的依赖项。3.3 工作流与工程化规则这类规则将团队的开发流程固化到AI辅助中。文件示例git-workflow.mdc,testing.mdc核心内容Git提交约定提交信息格式如Conventional Commits分支命名策略。测试单元测试使用Jest描述用describe和it快照测试的更新流程。可以提供一个基础测试套件模板。文档与注释要求公共API、复杂函数必须写JSDoc/TSDoc注释。组件Props需用注释说明。环境变量说明不同环境dev, staging, prod的配置文件和变量命名规则。实操心得不要试图把所有内容塞进一个巨大的.mdc文件。按照“单一职责”原则拆分。例如将eslint配置单独成一个linting.mdc将GraphQL查询规范单独成一个graphql-client.mdc。这样AI能更精准地加载相关规则你也更容易维护。一个.mdc文件的行数最好控制在200行以内超过500行就可能影响效率。4. 上下文文件为AI注入项目灵魂如果说规则Rules是“法律条文”规定了AI应该怎么做那么上下文文件Context Files就是“背景资料”告诉AI我们正在做一个什么样的项目。两者结合AI才能做出最明智的决策。4.1instructions.md项目的总说明书这是最重要的上下文文件通常放在项目根目录。它应该是一份活的文档随着项目演进而更新。内容结构建议项目愿景与目标用一两段话描述项目要解决的核心问题及其价值。功能特性列表列出已实现和计划中的主要功能模块。技术栈详单不仅列出名称最好注明版本和选择理由例如Node.js 18 LTS因需要稳定的ESM支持。项目结构详解比规则中更详细可以说明每个目录和关键文件的职责以及模块间如何交互。开发环境搭建步骤从克隆仓库、安装依赖、配置环境变量到启动服务的完整命令。AI可以据此为你生成相关的脚本或文档。构建与部署流程简要说明如何构建生产包以及部署到哪个环境。如何生成你可以直接让Cursor帮你起草一份。一个有效的提示词Prompt如下“你是一位资深技术文档工程师。请根据当前代码库的结构、package.json中的依赖以及主要源代码文件为我生成一份详细的instructions.md文件草案。内容需包括项目概述、核心技术栈及版本、目录结构说明、本地开发环境启动命令、以及重要的开发约定。请使用清晰的中文撰写。”4.2roadmap.md指引长期演进的地图这个文件用于规划未来帮助AI理解项目的发展方向使其在建议重构或添加新功能时能与长期目标对齐。内容示例## 产品路线图 - [ ] Q2 2024: 实现用户权限管理系统RBAC - [ ] Q3 2024: 集成实时消息通知功能 - [ ] Q4 2024: 开发移动端适配的PWA版本 ## 技术债与重构计划 - [ ] 将 lib/legacy 下的jQuery代码逐步重写为React组件。 - [ ] 在Q3前将状态管理从Context API迁移至Zustand。 - [ ] 为核心工具函数添加单元测试覆盖率提升至80%。注意事项instructions.md和roadmap.md都应被视为项目文档的一部分纳入版本控制。它们不仅服务于AI也是新团队成员极佳的上手资料。5. 核心功能Composer与上下文命令实战Cursor的Composer通过Cmd/Ctrl I唤起是其核心交互界面。掌握其两种模式和强大的上下文命令是发挥其威力的关键。5.1 两种模式的选择代理模式 vs 常规模式代理模式通过快捷键⌘.(Mac) /Ctrl.(Windows) 在聊天中激活或在Composer中点击“Agent”按钮。此模式下AI拥有更高的自主权可以自动分析相关文件、执行命令、直接编辑代码。适合场景实现一个定义清晰但步骤稍多的功能例如“在用户模型中添加手机号字段并更新相关的注册和编辑页面”。常规模式就是普通的Composer输入框。AI会根据你当前打开的文件和项目上下文提供建议和代码但需要你手动接受更改。适合场景编写一个函数、重构一段代码、解释一个复杂逻辑。我的经验对于复杂的、跨文件的任务我倾向于先使用代理模式让它给出一个实现方案和代码变更列表我审查后再决定应用。对于局部、精准的修改常规模式更可控。5.2 上下文命令精准投喂信息这是减少与AI“来回扯皮”的利器。通过在聊天或Composer中输入符号你可以精准地将特定信息纳入对话上下文。文件或路径最常用的命令。例如src/components/Button.tsx会将整个文件内容作为上下文。你也可以src/utils/**/*.ts来引用整个目录下的文件注意实际效果可能受限于上下文长度。代码片段在聊天中你可以选中编辑器里的一段代码然后输入Cursor会自动生成一个引用该代码块的链接。这在解释某段特定代码时非常有用。文档可以引用项目内的Markdown文档比如README.md或docs/api.md。网络搜索当你需要最新的、项目外部的信息时可以使用web命令让AI进行联网搜索需在设置中启用。例如“web最新的React Server Components最佳实践是什么”实战技巧在提出一个复杂问题前先用命令将相关的关键文件如接口定义、父组件、工具函数引入上下文。这能极大提升AI回答的准确性和相关性。例如在问“如何修复这个按钮的点击事件不触发的问题”之前先一下按钮组件文件和它所在的页面文件。6. 性能优化与项目管理.cursorignore与资源整理随着项目规模增长如何管理Cursor的上下文避免其被无关文件干扰或拖慢速度就变得很重要。6.1 使用.cursorignore文件类似于.gitignore你可以在项目根目录创建.cursorignore文件来排除不需要被Cursor索引和分析的文件或目录。为什么要用提升性能排除node_modules,build,.next,dist等大型生成目录能显著加快Cursor的初始索引和后续响应速度。净化上下文排除日志文件、临时文件、配置文件如.env.local包含敏感信息等防止无关或敏感信息污染AI的上下文导致其做出错误判断。专注核心代码排除遗留代码目录、实验性分支代码等让AI专注于当前活跃的代码库。示例# .cursorignore node_modules/ .next/ dist/ build/ *.log .env*.local legacy/ coverage/ .DS_Store提示Cursor默认会尊重.gitignore中的规则。.cursorignore是其补充用于排除那些在Git中需要跟踪但你不希望Cursor索引的文件。6.2 规则与上下文的维护策略一个健康的规则库需要维护否则会随着项目发展而变得过时或矛盾。定期审查每个季度或主要版本更新前花时间检查.cursor/rules/下的规则文件更新过时的技术栈描述合并重复的规则删除不再适用的规则。版本控制确保.cursor/rules/,instructions.md,.cursorignore等文件都提交到Git。这是团队协作的基础。渐进式采用对于已有的大型项目不要试图一次性编写所有规则。可以从一个最痛的痛点开始比如API调用规范写好一个规则应用并验证其效果再逐步扩展。7. 常见问题与排查技巧实录即使配置得当在实际使用中仍会遇到各种问题。以下是我和团队在实践中踩过的一些坑及解决方案。7.1 规则似乎没有生效这是最常见的问题。请按以下步骤排查检查规则文件位置和格式确保.mdc文件在.cursor/rules/目录下且Frontmatter格式正确三个短横线---不能少缩进是YAML格式。检查规则作用域确认你正在编辑的文件路径是否匹配规则中globs模式。你可以尝试在聊天中手动引用该规则文件看AI是否识别。检查规则优先级是否有更高优先级的规则比如手动引用的另一个规则覆盖了当前规则重启Cursor有时规则文件的更改需要重启Cursor IDE才能完全加载。查看“活动规则”在Cursor的聊天界面或Composer中留意AI回复时旁边是否显示了正在应用的规则图标或名称这是最直接的确认方式。7.2 AI生成的代码不符合预期如何调试提供更具体的上下文AI的“胡言乱语”往往源于信息不足。在提问前多用命令引入相关的接口定义、父组件、业务逻辑文件。检查instructions.md确保项目的总体说明是准确和最新的。一个过时的技术栈描述会导致AI推荐错误的方法。拆分复杂任务不要一次性要求“构建整个登录页面”。拆解为“1. 创建包含邮箱和密码输入框的表单组件2. 添加表单验证逻辑3. 集成登录API调用”。分步进行每一步都验证结果。在规则中提供反例如果AI总在某个地方犯同样错误就在对应的规则文件中明确指出“禁止xxx做法”并给出错误示例和正确示例。7.3 上下文长度限制与优化Cursor的上下文窗口有限虽然很大但非无限。当项目非常庞大时需要注意精简规则描述规则正文要言简意赅避免冗长的叙述。善用引用与其让AI自动加载大量可能无关的文件不如在需要时精准引用关键文件。模块化instructions.md如果instructions.md太长可以将其拆分为instructions-frontend.md,instructions-backend.md等然后在主instructions.md中做简要索引需要时再单独引用。7.4 团队协作中的规则管理规则冲突如果团队成员对某条规则有争议最好的方式是将其记录在规则文件的注释中或者创建一个rules-discussion.md文档进行讨论。规则应该是团队共识的体现。新人上手将配置好的.cursor目录和上下文文件作为项目标准模板的一部分。新成员克隆项目后Cursor会自动加载这些配置极大降低其上手成本并能立刻按照团队规范进行开发。我个人最深的一个体会是投资时间配置Cursor规则不是一个一劳永逸的“设置”而是一个持续的、与项目共同成长的“对话”过程。初期可能会花上几个小时来搭建框架但随之而来的是每天在代码生成、bug查找、方案咨询上节省的大量时间。它迫使你和团队更清晰地思考并记录下项目的架构决策和编码规范这本身对代码质量就是一种提升。当你看到AI生成的代码几乎无需修改就能直接使用时你会觉得这一切的投入都是值得的。