前端通用 AI Rules 定义：适配 Cursor、Trae 等主流工具

前端通用 AI Rules 定义

这套通用前端 Rules 模板，是在近期工程实践中反复打磨后的结果。你可以直接将其保存为 .cursor/rules.md，或粘贴到 Trae、Qoder、Windsurf 等工具的自定义指令区域。

核心原则（永远优先遵守）

1. 语言选择：优先使用 TypeScript（严格模式），避免隐式 any。
2. 组件范式：优先函数式 + hooks 写法，class 组件仅在极特殊场景保留。
3. 单一职责：组件尽量小而纯，单个文件控制在 300–400 行以内。
4. 状态管理：能用 useState + useReducer 解决就不引入重型库。
5. 样式方案：优先 Tailwind CSS + shadcn/ui / Radix UI / Headless UI 组合。
6. 代码规范：严格遵循 ESLint + Prettier + typescript-eslint 推荐规则。
7. 注释要求：关键工具函数、hooks、复杂组件必须写 JSDoc / TSDoc 注释。
8. 语法特性：优先使用现代语法（可选链、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

组件编写规范

所有组件必须导出 Props 类型（interface 或 type）。优先使用解构 + 默认值写法，显式声明 children?: ReactNode。动态 className 建议使用 clsx 或 cva。

注意业务逻辑不要写在组件内部超过 30 行，应抽离到 hooks 或 utils。所有副作用必须放在 useEffect 中，并明确依赖数组。自定义 hooks 命名必须以 use 开头，且禁止在 render 阶段产生副作用（如 setState、dispatch 等）。

推荐的组件 Props 写法

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: 前缀）。

性能与可维护性红线

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

React Query / TanStack Query 规范

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

测试规范

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

禁止项（红线）

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

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