前端通用 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. 所有组件必须导出类型 Propsinterface 或 type 2. 优先使用解构 默认值写法 3. 必须显式声明 children?: ReactNode 4. 动态 className 使用 clsx 或 cvaclass-variance-authority 5. 禁止在组件内部写业务逻辑超过 30 行 → 抽离到 hooks / utils 6. 所有副作用必须放在 useEffect 中并写清楚依赖数组 7. 自定义 hooks 命名必须以 use 开头 8. 禁止在 render 阶段产生副作用setState、dispatch 等 ## 推荐的组件 Props 写法现代风格 tsx interface ButtonProps extends React.ButtonHTMLAttributesHTMLButtonElement { variant?: primary | secondary | outline | ghost | destructive size?: sm | default | lg | icon asChild?: boolean loading?: boolean leftIcon?: React.ReactNode rightIcon?: React.ReactNode } const Button React.forwardRefHTMLButtonElement, ButtonProps( ( { className, variant primary, size default, asChild false, loading false, leftIcon, rightIcon, children, ...props }, ref ) { // ... } ) Button.displayName ButtonTailwind shadcn/ui 使用规范禁止 inline stylestyle{{}}全部走 Tailwind复杂组件样式使用 cva cn 组合颜色一律使用主题变量theme.colors.*或 CSS 变量响应式优先 mobile-firstsm: md: lg: xl: 2xl:暗黑模式支持 class 策略dark: 前缀性能与可维护性红线禁止在循环/渲染中使用匿名函数作为 props会导致子组件重复渲染useMemo / useCallback 只在真正有性能问题时使用先测再加列表渲染必须加 key且 key 稳定不要用 index 做 key图片必须设置 width/height 防止布局偏移或使用 next/image禁止直接操作 DOMdocument.getElementById 等用 refReact Query / TanStack Query 规范所有服务端数据请求一律走 useQuery / useMutationqueryKey 必须是数组且稳定[…deps]全局配置 staleTime / gcTime / retry 等默认值错误处理统一走 ErrorBoundary toast测试规范单元测试覆盖 hooks、纯函数、工具函数vitest testing-library组件测试写交互测试userEvent优先测试用户行为而非实现细节至少覆盖 80% 的核心业务组件和 hooks禁止项红线禁止 console.log / console.error 留在生产代码改用 logger 或移除禁止 any 类型除非极特殊场景并加 ts-expect-error 说明禁止 ! 非空断言改用 ? 可选链 类型保护禁止直接 import 第三方库的 css应走 postcss / tailwind禁止写超过三层的条件嵌套抽成函数或单独组件最后一条终极原则“写给人看的代码让 AI 帮你生成让测试帮你验证让未来的自己能快速理解。”### 快速复制粘贴版直接丢进 Cursor Rules 你可以把上面整个 markdown 内容保存为 .cursor/rules.md 或直接粘贴到工具的 Rules 区域。 如果你的项目有特殊技术栈Next.js / Nuxt / Remix / Svelte / Vue3 TS / Electron 前端等可以告诉我我再帮你做针对性调整。 祝你和 AI 一起写出更干净、更快、更可维护的前端代码