Cursor IDE Rules / Skills / Subagents 前端项目配置全指南

我会以前端工程化最佳实践为标准，给你一套可直接复制、开箱即用的完整配置方案，覆盖规则、技能、子代理三大模块，适配 React/Vue/TS 等主流前端栈。

---

一、核心概念先搞懂

表格

模块	作用	适用场景
Rules	给 AI 设定强制约束，相当于项目的「编码宪法」，AI 必须遵守	代码规范、架构约束、安全红线、最佳实践
Skills	给 AI 赋予专项能力，相当于「工具插件」，AI 会在合适场景自动调用	自动化流程、专项任务、工具链集成
Subagents	给主 AI 分配专职子助手，并行处理复杂任务	大型重构、多模块开发、端到端测试

---

二、Rules 配置：前端项目「编码宪法」

1. 核心规则分类（直接复制可用）

（1）通用前端编码规范 Rule

# 前端项目通用编码规范 Rule
## 1. 代码风格与格式
- 严格遵循项目 ESLint + Prettier 配置，所有代码必须通过 lint 校验
- 变量/函数使用小驼峰（camelCase），组件/类型/接口使用大驼峰（PascalCase），常量使用全大写下划线（UPPER_SNAKE_CASE）
- 函数必须添加 JSDoc 注释，复杂逻辑必须添加行内注释
- 禁止使用 var，统一使用 const/let，优先使用 const
- 导入语句按「第三方包 → 内部模块 → 样式文件」排序，同一类按字母顺序排列

## 2. TypeScript 规范
- 禁止使用 any 类型，必须使用明确的类型定义，必要时使用 unknown 并做类型守卫
- 所有组件 Props 必须定义 interface/type，导出组件必须标注 Props 类型
- 优先使用类型守卫、类型断言而非强制类型转换
- 枚举优先使用 const enum，避免冗余代码

## 3. React 最佳实践
- 组件必须使用函数组件 + Hooks，禁止使用类组件
- 状态逻辑复杂时必须抽离自定义 Hooks，禁止在组件内写大段逻辑
-  useEffect 必须添加完整依赖项，禁止空依赖滥用
- 禁止在 useEffect 内直接修改 state 造成无限循环
- 组件拆分遵循单一职责原则，单个组件代码不超过 300 行
- 优先使用 React.memo、useMemo、useCallback 做性能优化，避免不必要的重渲染

## 4. Vue 最佳实践（如项目使用 Vue）
- 组件必须使用 <script setup> 语法糖，禁止使用 Options API
- 响应式数据优先使用 ref/reactive，computed 必须标注返回类型
- 生命周期钩子优先使用 onMounted/onUnmounted 等组合式 API
- 复杂逻辑抽离 composables，禁止在组件内写大段业务逻辑

## 5. 安全与性能
- 禁止直接操作 DOM，优先使用框架提供的 API
- 禁止在代码中硬编码敏感信息（API Key、密钥等），必须使用环境变量
- 所有用户输入必须做 XSS 防护，使用框架自带的安全渲染机制
- 图片必须添加懒加载，大文件必须做分片加载
- 禁止使用 console.log 生产环境代码，必须移除或用环境变量控制

## 6. 工程化规范
- 新增依赖必须同步更新 package.json 与 pnpm-lock.yaml（或对应包管理器锁文件）
- 所有异步操作必须添加错误捕获（try/catch 或 .catch()）
- 接口请求必须统一封装，禁止在组件内直接写 fetch/axios
- 路由跳转必须使用框架提供的路由 API，禁止直接修改 window.location

（2）架构约束 Rule（微前端 / 多端项目专用）

# 前端项目架构约束 Rule
## 1. 微前端（qiankun/无界）约束
- 子应用必须严格遵循主应用的生命周期规范，正确导出 bootstrap/mount/unmount 钩子
- 子应用禁止修改全局 window 对象，所有样式必须添加 scoped 或命名空间，避免样式污染
- 子应用路由必须使用 base 路由，禁止与主应用路由冲突
- 子应用静态资源必须使用相对路径，禁止绝对路径

## 2. Taro/多端小程序约束
- 所有代码必须兼容微信小程序与 H5 双端，禁止使用端专属 API 不做兼容
- 页面生命周期必须遵循 Taro 规范，禁止使用浏览器专属生命周期
- TabBar 配置必须严格遵循项目规范，禁止私自修改
- 小程序端必须适配不同屏幕尺寸，禁止固定像素布局

## 3. 状态管理约束
- 全局状态必须使用 Redux/ Zustand/ Pinia 等统一状态管理工具，禁止组件内透传多层 props
- 组件内状态优先使用局部 state，只有跨组件共享状态才使用全局状态
- 状态更新必须遵循 immutable 原则，禁止直接修改 state

2. 配置步骤

1. 进入当前页面，点击 Rules 区域的 New User Rule（或右上角 + New）
2. 粘贴上述规则内容，填写 Rule 名称（如 前端通用编码规范）
3. 选择生效范围：
   • Always：全局生效（推荐）
   • By File Path：按文件路径生效（如仅对 src/components 生效）
   • Manually：手动触发
4. 点击保存，规则立即生效

---

三、Skills 配置：给 AI 加「前端专属技能」

1. 高频实用 Skills（直接复制可用）

（1）前端代码审查 Skill

# 前端代码审查 Skill
## 技能描述
自动对提交的前端代码进行全方位审查，覆盖规范、性能、安全、架构四大维度，输出可落地的优化建议
## 触发条件
- 当用户输入「代码审查」「review 代码」「检查代码」时自动触发
- 当用户提交 PR/MR 代码时自动触发
## 执行流程
1.  检查代码是否符合项目 ESLint/Prettier 规范
2.  检查 TypeScript 类型定义是否完整、合理
3.  检查 React/Vue 组件是否遵循最佳实践
4.  检查性能问题（如不必要的重渲染、大列表未做虚拟滚动等）
5.  检查安全问题（如 XSS 风险、硬编码敏感信息等）
6.  检查架构合规性（如微前端约束、状态管理规范等）
7.  输出结构化审查报告，包含问题位置、问题原因、修复方案
## 输出格式
### 代码审查报告
#### ✅ 合规项
- （列出符合规范的内容）
#### ⚠️ 待优化项
- （问题位置 + 问题描述 + 优化建议）
#### ❌ 严重问题
- （必须修复的问题 + 修复方案）

（2）前端自动化测试 Skill

# 前端自动化测试 Skill
## 技能描述
根据业务代码自动生成单元测试、组件测试、E2E 测试用例，覆盖核心逻辑与边界场景
## 触发条件
- 当用户输入「生成测试用例」「写测试」「单元测试」时自动触发
- 当用户新增/修改业务组件/工具函数时自动触发
## 执行流程
1.  分析代码的核心逻辑、输入输出、边界场景
2.  生成对应测试用例（单元测试用 Vitest/Jest，组件测试用 Testing Library，E2E 用 Cypress/Playwright）
3.  确保测试用例覆盖 100% 核心逻辑，包含正常场景、异常场景、边界场景
4.  输出可直接运行的测试代码，标注测试覆盖范围
## 输出格式
### 测试用例生成结果
#### 测试文件路径
- `src/xxx/__tests__/xxx.test.tsx`
#### 测试代码
（完整可运行的测试代码）
#### 测试覆盖说明
- 覆盖的核心逻辑
- 覆盖的边界场景
- 未覆盖的场景（如有）

（3）前端性能优化 Skill

# 前端性能优化 Skill
## 技能描述
对项目进行性能分析，输出针对性优化方案，覆盖 FCP/LCP/CLS 等核心 Web Vitals 指标
## 触发条件
- 当用户输入「性能优化」「优化页面」「提升加载速度」时自动触发
## 执行流程
1.  分析项目的构建配置（Webpack/Vite/Rollup），识别打包体积问题
2.  分析页面渲染逻辑，识别重渲染、阻塞渲染问题
3.  分析资源加载逻辑，识别大文件、未做缓存问题
4.  输出分优先级优化方案，包含操作步骤、预期效果
## 输出格式
### 性能优化方案
#### 🔴 高优先级（立即执行）
- 优化项 + 操作步骤 + 预期效果
#### 🟡 中优先级（迭代执行）
- 优化项 + 操作步骤 + 预期效果
#### 🟢 低优先级（长期优化）
- 优化项 + 操作步骤 + 预期效果

2. 配置步骤

1. 进入当前页面，点击 Skills 区域的 New Skill（或右上角 + New）
2. 粘贴上述技能内容，填写 Skill 名称（如 前端代码审查）
3. 配置触发方式：
   • 自动触发：设置触发关键词（如 代码审查）
   • 手动触发：在聊天框输入 /技能名 触发
4. 点击保存，技能立即生效

---

四、Subagents 配置：给主 AI 配「专职助手」

1. 前端项目高频 Subagents（直接复制可用）

（1）组件开发子代理

# 组件开发子代理
## 角色定位
专职负责前端组件的设计、开发、测试、文档全流程，输出高质量可复用组件
## 核心职责
1.  根据需求设计组件 API（Props、事件、插槽等）
2.  开发符合项目规范的组件代码，包含类型定义、样式、逻辑
3.  生成组件测试用例，确保组件稳定性
4.  生成组件使用文档，包含示例、API 说明、注意事项
5.  优化组件性能，确保组件可复用、可维护
## 工作流程
1.  接收主代理的组件开发需求
2.  输出组件设计方案（API、结构、样式）
3.  开发组件代码，同步遵循项目 Rules 规范
4.  生成测试用例与使用文档
5.  提交给主代理审核
## 约束条件
- 必须严格遵循项目的编码规范与架构约束
- 组件必须兼容项目的技术栈（React/Vue/TS 等）
- 组件必须添加完整的类型定义与注释

（2）Bug 排查子代理

# Bug 排查子代理
## 角色定位
专职负责前端项目的 Bug 排查、定位、修复，输出根因分析与预防方案
## 核心职责
1.  根据 Bug 描述、报错信息、复现步骤定位根因
2.  提供可落地的修复方案，包含完整代码
3.  分析 Bug 产生的根本原因，输出预防措施
4.  验证修复方案的有效性，确保 Bug 彻底解决
## 工作流程
1.  接收主代理的 Bug 排查需求
2.  分析报错信息、复现步骤，定位根因
3.  提供修复方案，包含完整代码
4.  输出根因分析与预防措施
5.  提交给主代理审核
## 约束条件
- 必须提供完整的修复代码，可直接复制使用
- 必须分析根因，不能只做表面修复
- 必须提供预防措施，避免同类 Bug 再次发生

（3）文档生成子代理

# 文档生成子代理
## 角色定位
专职负责前端项目的文档生成，包含接口文档、组件文档、架构文档、部署文档等
## 核心职责
1.  根据代码自动生成接口文档、组件文档
2.  根据项目架构生成架构文档、开发规范文档
3.  根据部署流程生成部署文档、运维文档
4.  维护文档的时效性，确保文档与代码同步
## 工作流程
1.  接收主代理的文档生成需求
2.  分析对应代码/流程，生成结构化文档
3.  输出 Markdown 格式文档，包含示例、说明、注意事项
4.  提交给主代理审核
## 约束条件
- 文档必须准确、完整，与代码/流程完全一致
- 文档必须结构化，便于阅读与维护
- 文档必须包含示例，便于开发者快速上手

2. 配置步骤

1. 进入当前页面，点击 Subagents 区域的 + New
2. 粘贴上述子代理内容，填写子代理名称（如 组件开发助手）
3. 配置调用方式：
   • 自动调用：主代理遇到对应任务时自动触发
   • 手动调用：在聊天框输入 /子代理名 需求 触发
4. 点击保存，子代理立即生效

---

五、前端项目配置最佳实践

1. 配置优先级

1. 先配 Rules：先把项目的「编码宪法」定好，确保所有 AI 输出符合规范
2. 再配 Skills：给 AI 加常用专项能力，提升开发效率
3. 最后配 Subagents：针对复杂任务配置专职助手，并行处理工作

2. 项目级配置（推荐）

• 点击页面顶部的 my_flutter_project（可切换为你的前端项目名），将配置绑定到项目，实现项目专属配置
• 开启 Include third-party Plugins, Skills, and other configs，自动导入其他工具的配置（如 VSCode 插件、ESLint 规则等）

3. 常见问题排查

• AI 不遵守 Rules ：检查 Rule 是否设置为 Always 生效，是否有语法错误
• Skills 不触发：检查触发关键词是否正确，是否开启自动触发
• Subagents 不工作：检查子代理配置是否完整，是否有权限调用

---

六、进阶：Cursor 与前端工程化深度集成

1. 与 ESLint/Prettier 联动

在 Rules 中添加md

- 所有代码必须通过项目 ESLint 校验，ESLint 配置文件为 .eslintrc.cjs
- 所有代码必须通过项目 Prettier 校验，Prettier 配置文件为 .prettierrc
- AI 输出代码后，自动执行 eslint --fix 与 prettier --write 格式化

2. 与 Git 联动

在 Hooks 中配置 Git 钩子，在提交代码前自动触发代码审查 Skill，确保代码符合规范

3. 与 CI/CD 联动

在 Subagents 中配置 CI/CD 子代理，自动生成 CI/CD 配置文件（GitHub Actions/GitLab CI 等），实现自动化构建、测试、部署

---

七、总结

通过上述配置，你可以让 Cursor 成为你的前端专属开发助手，从编码规范、专项技能到复杂任务全流程赋能，大幅提升开发效率与代码质量。