前端通用AI rules定义，适用于Cursor ，Trae，Qorder等AI开发工具

前端通用 AI Rules 定义
（适用于 Cursor、Trae、Qoder、Windsurf、Zed + AI、Codeium、Copilot 等几乎所有主流 AI 代码助手）

以下内容是 2025–2026 年在前端圈被大量验证、反复迭代后相对好用的“通用前端 Rules”模板。
你可以直接复制粘贴到 Cursor 的 Rules / Custom Instructions / 项目 .cursor/rules.md 中，或者 Trae、Qoder 等工具的类似位置。

推荐的通用前端 Rules 结构（2026 年主流写法）

# 前端通用 Rules - 适用于 React / Vue / TypeScript 项目 ## 核心原则（永远优先遵守） 1. 优先使用 TypeScript（严格模式） 2. 优先函数式 + hooks 写法，class 组件仅在极特殊场景使用 3. 组件尽量小而纯（单一职责），单个文件不超过 300–400 行 4. UI 优先使用可组合、可复用的原子组件 + 组合组件模式 5. 状态管理：能用 useState + useReducer 解决就不引入 Zustand / Jotai / Redux 6. 样式：优先 Tailwind CSS + shadcn/ui / Radix UI / Headless UI 组合 7. 代码风格严格遵循 ESLint + Prettier + typescript-eslint 推荐规则 8. 永远写 JSDoc / TSDoc 注释（尤其是工具函数、hooks、复杂组件） 9. 优先使用现代语法（可选链、nullish 合并、top-level await 等） ## 文件与目录命名规范 - 组件文件：PascalCase.tsx（例：UserProfileCard.tsx） - hooks 文件：camelCase.ts（例：useDebounce.ts） - 工具函数：camelCase.ts（例：formatCurrency.ts） - 常量：UPPER_SNAKE_CASE 或 camelCase（看语义） - 类型定义：统一放在 types/ 或同文件内以 I、T、S 前缀（视团队习惯） - 测试文件：同名 + .test.tsx / .spec.tsx - Storybook 文件：同名 + .stories.tsx ## 组件编写规范 1. 所有组件必须导出类型 Props（interface 或 type） 2. 优先使用解构 + 默认值写法 3. 必须显式声明 children?: ReactNode 4. 动态 className 使用 clsx 或 cva（class-variance-authority） 5. 禁止在组件内部写业务逻辑超过 30 行 → 抽离到 hooks / utils 6. 所有副作用必须放在 useEffect 中，并写清楚依赖数组 7. 自定义 hooks 命名必须以 use 开头 8. 禁止在 render 阶段产生副作用（setState、dispatch 等） ## 推荐的组件 Props 写法（现代风格） ```tsx interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' size?: 'sm' | 'default' | 'lg' | 'icon' asChild?: boolean loading?: boolean leftIcon?: React.ReactNode rightIcon?: React.ReactNode } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( ( { className, variant = 'primary', size = 'default', asChild = false, loading = false, leftIcon, rightIcon, children, ...props }, ref ) => { // ... } ) Button.displayName = 'Button' 

Tailwind + shadcn/ui 使用规范

1. 禁止 inline style（style={{}}），全部走 Tailwind
2. 复杂组件样式使用 cva + cn 组合
3. 颜色一律使用主题变量（theme.colors.*）或 CSS 变量
4. 响应式优先 mobile-first（sm: md: lg: xl: 2xl:）
5. 暗黑模式支持 class 策略（dark: 前缀）

性能与可维护性红线

1. 禁止在循环/渲染中使用匿名函数作为 props（会导致子组件重复渲染）
2. useMemo / useCallback 只在真正有性能问题时使用，先测再加
3. 列表渲染必须加 key，且 key 稳定（不要用 index 做 key）
4. 图片必须设置 width/height 防止布局偏移，或使用 next/image
5. 禁止直接操作 DOM（document.getElementById 等），用 ref

React Query / TanStack Query 规范

1. 所有服务端数据请求一律走 useQuery / useMutation
2. queryKey 必须是数组且稳定（[…deps]）
3. 全局配置 staleTime / gcTime / retry 等默认值
4. 错误处理统一走 ErrorBoundary + toast

测试规范

1. 单元测试覆盖 hooks、纯函数、工具函数（vitest + @testing-library）
2. 组件测试写交互测试（userEvent）
3. 优先测试用户行为而非实现细节
4. 至少覆盖 80% 的核心业务组件和 hooks

禁止项（红线）

1. 禁止 console.log / console.error 留在生产代码（改用 logger 或移除）
2. 禁止 any 类型（除非极特殊场景并加 @ts-expect-error 说明）
3. 禁止 ! 非空断言（改用 ? 可选链 + 类型保护）
4. 禁止直接 import 第三方库的 css（应走 postcss / tailwind）
5. 禁止写超过三层的条件嵌套（抽成函数或单独组件）

最后一条终极原则：
“写给人看的代码，让 AI 帮你生成，让测试帮你验证，让未来的自己能快速理解。”

 ### 快速复制粘贴版（直接丢进 Cursor Rules） 你可以把上面整个 markdown 内容保存为 `.cursor/rules.md` 或直接粘贴到工具的 Rules 区域。 如果你的项目有特殊技术栈（Next.js / Nuxt / Remix / Svelte / Vue3 + TS / Electron 前端等），可以告诉我，我再帮你做针对性调整。 祝你和 AI 一起写出更干净、更快、更可维护的前端代码～