1. Cursor Rules与@符号：开发者的效率倍增器
第一次接触Cursor的Rules和@符号功能时，我正被一个跨文件类型检查的问题困扰。团队里有人用any类型，有人用unknown，还有人直接忽略类型标注。直到发现可以通过Rules强制统一类型规范，配合@符号快速定位问题代码，效率直接提升了三倍。这组黄金组合就像给项目装了GPS导航系统，让AI辅助编程从"大概正确"变成"精准制导"。
Rules本质上是项目的宪法体系，分为项目规则（Project Rules）和用户规则（User Rules）两个层级。前者存储在.cursor/rules目录下的.mdc文件中，对整个团队生效；后者保存在用户本地目录，适合个人工作习惯配置。当两者冲突时，项目规则优先——这个设计既保证了团队规范，又尊重了开发者个性。
而@符号则是上下文调取的快捷键。在Chat或命令面板输入@时，会弹出智能菜单，能快速引用文件、代码片段、Git记录等12种资源。我常开玩笑说，这就像在代码库里玩"集卡游戏"，任何需要的上下文都能即抽即用。
2. Rules配置实战：从规范到执行的闭环
2.1 MDC语法精要
Rules使用MDC（Markdown with Cursor）格式编写，分为元数据区和规则正文。元数据用YAML定义基础属性，我特别推荐这几个实用参数：
--- alwaysApply: true # 是否全局生效 description: "React组件规范" globs: "src/components/**/*.tsx" # 作用路径 priority: 500 # 冲突时优先级 version: "1.2" custom: # 自定义字段 codeOwner: "前端组" ---规则正文用Markdown编写时，有个少有人知的技巧：用三级标题划分检查维度，配合任务列表描述具体要求。比如我们团队的React规范：
### 3. Props规范 - [ ] 必须使用TypeScript类型定义props - [ ] 默认props必须通过解构默认值设置 - [ ] 复杂props类型需添加jsDoc说明 ### 4. 生命周期 - [ ] 避免使用componentWillMount - [ ] 副作用代码必须放在useEffect回调中2.2 规则的热加载机制
修改Rules文件后，Cursor会自动重新加载而无需重启。但我在实践中发现，当同时修改多个规则文件时，建议手动触发加载：在Chat输入"/reload rules"。曾经因为忽略这点，导致新规则延迟生效，白白浪费半小时排查。
优先级处理也有门道：当多个规则作用于同一文件时，priority值大的生效。建议团队将基础规范设为100-300，项目特殊规则设为500+。有个反模式要避免——不要设置过多高优先级规则，容易导致"规则战争"。
3. @符号的十二般武艺
3.1 文件级精准定位
@Files可能是使用最频繁的功能。除了直接输入@后选择文件，还有几个高效技巧：
- 拖拽文件到输入框自动生成引用
- 使用相对路径快速定位：@../utils/request.ts
- 组合模糊搜索：@comp* 会列出所有匹配组件文件
有次我需要分析一个复杂表单的校验逻辑，输入"解释校验规则 @src/forms/UserForm.tsx @src/utils/validators.ts"，AI直接给出了跨文件调用关系图，比手动翻代码快得多。
3.2 代码时空穿梭术
@Git与@Recent Changes的组合堪称"时间机器"。上周排查一个突然出现的样式BUG时，我用"@Git diff HEAD~3 分析样式冲突原因"快速定位到某次提交的CSS修改。而@Recent Changes更适合查看未提交的临时变更，相当于增强版的git status。
对于大型代码库，@Codebase是秘密武器。它会智能分析整个项目结构，优先索引高频修改文件。在接手遗留项目时，输入"@Codebase 解释核心模块架构"，能快速建立认知地图。
4. 黄金组合的化学反应
4.1 自动化文档生成
我们在.cursor/rules/doc-generator.mdc中配置了这样的规则：
--- description: "接口文档自动生成" globs: "src/api/**/*.ts" --- ### 文档要求 1. 提取接口路径和参数 2. 生成Markdown格式文档 3. 追加到API.md的对应模块然后只需输入"更新接口文档 @Cursor Rules doc-generator"，就能自动扫描所有API文件生成文档。相比手动维护，错误率下降了70%。
4.2 智能错误修复流水线
结合@Lint Errors和Rules的错误修复方案特别惊艳。我们在规则中预定义了常见错误的修复模板：
### ESLint错误处理 - error TS2322: 类型不匹配 → 建议添加类型断言 - error no-unused-vars: 未使用变量 → 建议删除或添加下划线前缀当出现"@Lint Errors fix error TS2322 in line 45"时，AI不仅指出问题，还会直接给出符合项目规范的修复代码。新成员 onboarding 时，这个功能减少了大量低级问题咨询。
5. 避坑指南与性能优化
5.1 索引策略调优
过大的代码库可能拖慢Cursor响应速度。通过.cursorignore文件忽略不需要索引的目录（如node_modules），能使性能提升40%以上。有个容易忽略的点：测试文件也应该被索引，因为AI需要它们理解代码行为。我们的最佳实践是：
# .cursorignore *-spec.js *-test.js !src/**/*.spec.ts # 保留TS测试文件5.2 规则冲突解决
当多个规则产生冲突时，Cursor会显示"Multiple rules apply"警告。我的处理流程是：
- 用"/show active rules"查看生效规则
- 检查各规则的priority和globs设置
- 通过"@Cursor Rules 规则名"单独测试每条规则
曾有个诡异情况：某TS规则在Vue文件中意外生效。最后发现是globs模式写成了"/*.{ts,tsx}"，而Vue单文件组件也被识别为tsx扩展名。改成"/*.ts?"就解决了。
6. 高级定制技巧
6.1 自定义文档集成
通过Settings > Features > Docs添加Swagger文档地址后，就能用@Docs引用API规范。我们还将内部设计规范网站接入，现在输入"检查按钮样式 @Docs 设计系统"就能调出最新UI规范。
更酷的是支持私有文档库。在.cursor/rules目录下创建docs文件夹，放入Markdown文件后，它们会自动加入@Docs索引。我们把代码评审checklist放在这里，代码提PR前用"@Docs 评审清单"就能快速自检。
6.2 动态变量注入
Rules支持在元数据中使用环境变量，适合多环境配置。比如：
--- apiBaseUrl: ${API_BASE_URL} --- # 请求规范 - 所有API调用必须使用{{apiBaseUrl}}作为基础路径配合Cursor的Env Files功能，能实现开发/生产环境的自动切换。这个技巧在我们微服务架构中特别有用，不同服务可以保持相同的规则文件。
