1. 项目概述为什么我们需要为AI编码助手制定“规则”如果你和我一样从VSCode切换到Cursor最初可能只是被它“能聊天、能写代码”的噱头所吸引。但用了一段时间后我发现一个核心问题AI助手虽然强大但它就像一个新来的、天赋异禀但毫无经验的实习生。你让它写个API接口它可能给你生成一个RESTful风格的但你的项目内部约定可能是GraphQL或者有一套自研的RPC框架。结果就是你花在审查和修改AI生成代码上的时间甚至比自己从头写还要多。这完全违背了提升效率的初衷。这正是digitalchild/cursor-best-practices这个项目试图解决的核心痛点。它不是一个简单的功能列表而是一套关于如何“驯化”Cursor让它真正理解并融入你个人或团队开发生态的系统工程。其核心思想是通过一套结构化的规则Rules和上下文Context文件将你的项目规范、技术栈偏好、代码风格乃至工作流程“灌输”给Cursor。最终目标是让Cursor生成的每一行代码都像是你自己写出来的一样——符合规范、风格统一、直接可用。简单来说这就像是为你的AI助手编写一本详尽的《项目开发手册》。没有它Cursor是在“盲猜”有了它Cursor是在“按图索骥”。接下来我将结合自己近半年的深度使用和团队推广经验为你拆解如何从零开始构建一套高效、可维护的Cursor规则体系。2. 规则体系深度解析从全局到局部的控制力Cursor的规则系统设计得非常精巧它通过多层级的规则应用实现了从粗到细的粒度控制。理解这个层次结构是有效利用它的第一步。很多人上来就埋头写.mdc文件却忽略了全局设置导致事倍功半。2.1 规则优先级当多条规则冲突时谁说了算这是最容易被忽视却至关重要的部分。Cursor内部有一个明确的规则评估顺序理解它才能避免规则互相“打架”。本地手动规则优先级最高。当你在聊天框或Composer中使用ruleName显式引用某条规则时这条规则会立即被激活并置于最高优先级。这用于临时覆盖其他规则处理特殊情况。自动附加规则当AI处理的任务涉及的文件路径匹配了某条规则中定义的globs模式如src/api/**/*.ts这条规则会被自动附加到上下文中。这是实现“按场景生效”的核心机制。代理请求规则AI助手自己判断是否需要某条规则。这要求规则必须有清晰的description字段AI会根据描述和当前任务的相关性来决定是否采用。这给了AI一定的自主权去调用它认为有帮助的通用规则。始终应用规则在规则文件中设置了alwaysApply: true或者在User Rules中定义的全局规则。这些规则作为底线在所有场景下生效。实操心得优先级意味着“覆盖”。你可以利用这一点进行分层设计。例如在User Rules里设置“所有响应请用中文”这是一个底线。但在某个项目的.mdc规则里你可以设置alwaysApply: true的规则“本项目API响应需遵循{code, data, message}格式”。当处理该项目的API文件时项目规则会与全局规则共同作用。而如果你临时用englishOnly引用一条“本次对话请用英文”的规则它会暂时覆盖全局的中文要求。2.2 用户规则奠定你的个人编码基调User Rules位于Cursor的设置界面中Cmd ,打开设置搜索Rules。这里配置的规则会应用于你账号下的所有项目是塑造AI与你交互风格的“人格基底”。它的内容就是纯文本指令不支持.mdc的YAML头或复杂格式。但这恰恰是它的优势简单、直接、全局生效。你应该在这里放什么交互风格比如“请用简洁、直接的语言回答避免客套话和冗余解释。”全局编码偏好比如“除非特别说明否则请使用TypeScript并严格类型检查。”、“请为所有生成的函数和复杂逻辑添加JSDoc注释。”安全与质量红线比如“生成的代码中绝对禁止出现硬编码的密码、密钥或敏感信息。”、“在提供涉及文件系统或网络操作的代码时必须包含基本的错误处理。”// 一个我的User Rules示例 - 请使用中文进行回复和代码注释。 - 在提供解决方案时请先简要说明思路再给出代码。 - 生成的代码应优先考虑可读性和可维护性其次才是性能优化。 - 对于可能产生副作用的操作如删除文件、写入数据库必须给出明确警告。注意事项User Rules不宜过长或过于具体。它应该是原则性的、跨项目通用的。如果把某个项目的具体技术栈如“使用Zustand而非Redux”放在这里就会在其他项目中造成干扰。记住这里是“个人工作习惯”不是“项目规范”。2.3 项目规则.mdc文件——团队协作的基石项目规则是这套实践的灵魂所在它存储在项目根目录的.cursor/rules/文件夹下每个规则是一个独立的.mdcMarkdown Cursor文件。这个目录应该被加入版本控制如Git从而确保团队每个成员使用的AI助手都遵循同一套标准。一个.mdc文件由两部分组成YAML Frontmatter元数据用于定义规则的属性如描述、作用范围、应用方式。规则内容Markdown具体的指令和规范用Markdown列表或段落书写。2.3.1 解剖一个完整的.mdc规则文件让我们看一个比官方示例更贴近真实场景的规则一个针对React组件开发的规则。--- description: React组件开发规范 - 适用于所有使用TypeScript和Tailwind CSS的组件 globs: - src/components/**/*.tsx - src/components/**/*.ts alwaysApply: false priority: high --- # React组件开发指南 当创建或修改React组件时请严格遵守以下规范 ## 组件定义 - 使用函数式组件配合React.FC类型或直接标注参数类型。 - 组件文件名使用PascalCase如UserProfileCard.tsx。 - 默认导出组件本身。 ## Props与类型 - 使用interface定义组件的Props。 - 为可选Props设置默认值或在interface中标记为可选?。 - 禁止使用any类型。 ## 样式与结构 - 本项目使用**Tailwind CSS**进行样式开发。请优先使用Tailwind工具类禁止在组件中编写*.module.css或styled-components。 - 容器元素默认使用div语义化标签仅在明确时使用如section, article。 - 复杂组件需使用apply提取重复的Tailwind类到CSS中保持JSX整洁。 ## 状态与副作用 - 简单状态使用useState。 - 复杂状态逻辑或需要跨组件共享时使用项目中的useStore自定义Hook基于Zustand。 - 副作用必须被useEffect正确管理并注意清理函数。 ## 示例参考 请参考现有组件 src/components/common/Button.tsx 和 src/components/layout/Header.tsx 的结构和风格。元数据字段解读description: 必填。清晰描述规则用途供AI理解和用户在规则列表中识别。globs: 关键字段。定义此规则自动附加的文件路径模式。支持数组可匹配多个模式。alwaysApply: 默认为false。若为true则此规则会在项目任何上下文中被加载慎用以免造成上下文污染。priority(可选): 提示AI此规则的重要性。规则内容撰写技巧结构化使用Markdown标题和列表让内容清晰可读对人、对AI都是如此。具体化避免“写出高质量的代码”这种模糊要求取而代之的是“函数长度不超过50行”、“圈复杂度低于10”。提供锚点使用文件名的语法直接链接到项目中的典范代码这是最强大的上下文提供方式。AI可以直接读取这些文件的内容作为参考。2.3.2 规则类型与策略根据alwaysApply和globs的设置以及是否被手动引用规则在实践中表现为几种类型策略类型配置方法适用场景场景化自动规则设置globsalwaysApply: false最常用。当AI处理src/api/下的文件时自动加载API规范规则处理src/components/时加载UI组件规则。精准、高效。项目级基础规则设置alwaysApply: true适用于整个项目的核心约束如“所有API错误必须使用统一的AppError类抛出”。通常只有1-2个。手动调用的知识库不设globs和alwaysApply仅靠description存放一些不常用但重要的知识如“部署流程”、“第三方服务集成密钥命名规范”。AI在需要时可自主请求或你手动用调用。临时覆盖指令在聊天中直接使用ruleName进行一次性特殊任务时临时启用某条特定规则优先级最高。踩坑实录初期我曾把所有规范塞进一个alwaysApply: true的project-guide.mdc里结果发现Cursor的上下文窗口很快被占满导致它在处理简单任务时也反应迟钝甚至遗忘核心指令。教训是规则一定要细粒度、场景化拆分。一个庞大的规则文件远不如十个精准的小规则有效。3. 核心实践构建你的项目上下文体系规则Rules告诉AI“怎么做”而上下文Context文件则告诉AI“这是什么”。两者结合才能让AI真正理解你的项目。instructions.md和roadmap.md是官方推荐的两个核心上下文文件。3.1instructions.md项目的“总说明书”这个文件是你给AI的“项目入职手册”。它不应该放在.cursor/rules/里而应该放在项目根目录或显眼的位置。它的目标是让一个完全不了解项目的人或AI快速掌握全貌。一份优秀的instructions.md应包含哪些部分项目简介用一两句话说明项目是做什么的解决什么问题。技术栈精确到版本号。例如“前端React 18.2 TypeScript 5.0 Vite 5.0状态管理Zustand 4.4UI库Ant Design 5.12CSS框架Tailwind CSS 3.3”。项目结构解释主要目录的职责。不要只列文件夹要说明为什么这样设计。src/ ├── api/ # 所有API请求层封装基于axios已配置拦截器和错误统一处理 ├── components/ # 通用业务组件按领域子目录划分 ├── hooks/ # 自定义React Hooks ├── stores/ # Zustand状态仓库 ├── utils/ # 纯函数工具库 └── pages/ # 页面级组件对应路由核心架构与模式解释关键设计决策。例如“数据流采用单向数据流组件通过调用stores/中的action来改变状态禁止组件间直接传递回调函数深嵌套。”开发与构建命令npm run dev启动什么npm run build有什么特殊参数编码规范速查虽然细节在规则文件里但这里可以放一些最核心、最易忘的比如“接口命名前缀用I还是不用”、“async函数必须用try-catch包裹吗”你可以用这样一个Prompt来让AI帮你生成初稿“你是一个资深技术文档工程师。请根据当前项目结构、package.json和主要源代码为我生成一份详细的instructions.md文件需包含项目概述、技术栈、目录结构说明、开发指南和编码规范摘要。”3.2roadmap.md指引长期开发方向这个文件用于规划未来。当AI在协助你开发一个新功能时如果它能看到这个功能在整体路线图中的位置以及后续可能关联的模块它就能给出更具前瞻性的代码建议减少未来的重构。内容示例# 项目开发路线图 ## 当前版本 (v1.2.0) - [ ] 用户个人中心页面重构 - [ ] 集成实时消息通知WebSocket服务 - [ ] 后台管理系统增加数据仪表盘 ## 下一阶段 (v1.3.0) - 性能优化实现组件级代码分割React.lazy - 引入PWA支持实现离线缓存 - 国际化(i18n)框架调研与基础搭建 ## 未来构想 - 移动端原生应用React Native可行性研究 - 微前端架构改造拆分主应用与子应用当AI在帮你写“用户个人中心”的代码时它看到后续有“国际化框架”的计划可能会提醒你“当前写的硬编码文本是否需要提前抽离到潜在的i18n键值结构中” 这种前瞻性建议非常有价值。3.3 忽略文件.cursorignore的妙用Cursor会索引项目文件以提供上下文但像node_modules、dist、*.log这类文件不仅无用还会浪费索引资源拖慢响应速度。.cursorignore文件的作用类似于.gitignore用于排除这些文件。# .cursorignore 示例 node_modules/ dist/ build/ *.log *.tmp coverage/ .DS_Store .env*.local重要提示.cursorignore只影响Cursor的后台索引和自动上下文加载。你依然可以在聊天中通过文件名手动引用被忽略的文件。这与.gitignore的行为不同。4. 高级技巧与Composer高效用法掌握了规则和上下文你已经能解决80%的问题。剩下的20%在于如何与Cursor高效交互尤其是利用好其核心功能——Composer。4.1 Composer模式Agent与Normal的选择Cursor的Composer有两种模式对应不同的使用场景Normal Mode默认你选中代码按下CmdK输入指令。AI会根据当前打开的文件和选中的代码块来理解上下文。这是最常用、最精准的模式适合局部代码的生成、解释、重构和调试。因为上下文非常聚焦AI的答案通常更准确。Agent ModeCmd.你提供一个高层次的任务描述如“为产品列表添加分页功能”AI会自主分析项目结构定位相关文件并可能执行一系列操作打开文件、编辑代码、甚至运行命令。它更强大但也更不可控。适合探索性任务或当你对代码库不熟悉时让AI帮你寻找切入点。实操心得对于明确的修改任务永远优先使用Normal Mode。先自己导航到相关文件选中要修改的代码区域再用Composer。这相当于给AI画了一个清晰的“作战地图”它能给出极其精准的建议。滥用Agent Mode容易导致AI“迷路”修改了不该改的文件。4.2 上下文命令精准投喂信息这是大幅提升AI理解准确度的关键。在聊天框或Composer指令中除了文字描述一定要多用命令来提供精确上下文。src/components/Form/UserForm.tsx直接引用一个文件。AI会读取其全部内容。src/api/引用整个目录。AI会了解这个目录下的文件结构但不会读取所有内容除非特别要求。“请参考这段代码的逻辑” code src/utils/validation.js:15-30引用一个文件的特定行号。这是最精准的锚点。docs README.md引用项目文档。web “React useEffect cleanup best practices”让AI临时搜索网络信息谨慎使用可能慢且信息不确定。一个高效的工作流接到任务“修改登录接口增加图形验证码校验。”先找到现有的登录接口文件src/api/auth.ts 打开它。找到处理登录的函数login 选中它。按下CmdK 输入“在这个login函数中在调用post请求之前增加对captcha参数的校验。校验逻辑请参考项目中已有的验证码工具src/utils/captcha.ts。校验失败时抛出ValidationError。”AI会基于你提供的精确代码位置和参考工具文件生成几乎可以直接接受的代码。4.3 规则与上下文的组合拳最强大的用法是将规则、上下文文件和命令结合起来。假设你有一条规则叫api-response-format.mdc定义了所有API控制器必须返回{ success, data, message }格式。 你正在编写一个新的用户控制器user.controller.ts。你可以这样操作打开或创建user.controller.ts。在Composer中输入“创建一个获取用户列表的GET端点。请遵循api-response-format规则并且分页参数请使用项目通用的PaginationParams接口定义在src/types/common.ts中。”Cursor会同时加载api-response-format规则和common.ts类型文件作为上下文生成的代码会天然符合你的项目规范无需二次调整。5. 常见问题与避坑指南在实际部署和团队推广这套实践的过程中我遇到了不少典型问题。这里汇总一下希望能帮你绕开这些坑。5.1 规则不生效或效果不佳问题写了.mdc规则但AI似乎完全无视。排查检查文件位置规则文件必须放在.cursor/rules/目录下且扩展名为.mdc。检查YAML语法---包裹的元数据部分必须是有效的YAML。最常见的错误是缩进用了Tab键必须用空格或冒号后没加空格。检查globs模式globs模式是相对于项目根目录的。src/**/*.ts会匹配所有TS文件而./src/**/*.ts可能无法正确匹配。使用在线Glob测试工具验证你的模式。规则冲突检查是否有alwaysApply: true的规则与你的场景化规则冲突。或者User Rules中的指令与项目规则矛盾。记住优先级顺序。上下文过载如果同时激活了太多规则尤其是内容很长的规则可能会挤占有限的上下文窗口导致AI“忘记”了某些指令。精简规则内容拆分大规则。5.2 AI生成的代码风格飘忽不定问题有时生成符合规范的代码有时又回到它的默认风格。解决强化规则的具体性不要写“使用清晰的命名”要写“变量名使用camelCase函数名使用动词开头如fetchUserData组件名使用PascalCase”。提供“榜样”代码在规则中多用引用项目内公认写得好的文件。AI非常擅长模仿。在指令中明确重申在给AI下指令时可以再次强调关键规范。例如“请创建一个React组件注意使用函数式组件和TypeScriptProps用interface定义样式全部使用Tailwind类名。”检查规则作用范围确保你正在编辑的文件路径匹配了对应规则的globs模式。5.3 团队协作时规则同步问题问题团队成员更新了规则其他人如何快速同步最佳实践版本控制确保.cursor/rules/目录和instructions.md等核心上下文文件都提交到Git。规则变更通知在团队内建立简单约定当有人更新重要规则如API规范、组件规范时在Pull Request描述中说明或在团队频道简单通知。编写SETUP.md在项目根目录创建一个简单的SETUP.md其中一步就是“拉取代码后请确认Cursor已正确加载项目规则”。可以引导团队成员在Cursor中检查规则列表。定期回顾在团队技术会议上可以花几分钟回顾一下常用规则的有效性根据大家的反馈进行优化。5.4 如何开始渐进式采用策略如果你面对一个已有的大型项目感到无从下手不要试图一次性编写所有规则。从痛点开始找出AI最常出错的领域。是API格式不统一还是组件结构混乱就从这里写第一条规则。创建instructions.md用AI辅助快速生成一份项目概述。这能立即提升AI对项目的整体理解。制定1-2条核心alwaysApply规则比如“所有错误必须用统一类抛出”、“所有API响应遵循固定格式”。这是底线。按模块扩展接下来一周当你需要开发或修改src/components/Button相关文件时为components目录编写一条规则。下一周处理api目录时再写一条。积少成多。鼓励团队贡献建立一个共享文档或频道让大家记录“如果AI能自动遵守XX规则就好了”的想法然后将其转化为正式的.mdc文件。经过几个月的实践这套方法已经将我团队的平均代码审查通过率提升了超过50%因为AI生成的第一版代码就已经非常接近最终要求。它更像是一个严格遵循团队规范的超级实习生而不是一个需要你反复纠正的新手。花时间投资在规则和上下文建设上初期看似有成本但从长期来看它在代码质量、团队协作和开发体验上带来的回报是巨大的。