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

前端通用 AI Rules 定义

以下是一套经过广泛验证的前端通用 AI Rules 模板，适用于 React、Vue、TypeScript 项目。你可以直接将其保存为 .cursor/rules.md 或粘贴到 Trae、Qoder 等工具的自定义指令区域。

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

1. 优先使用 TypeScript：开启严格模式，避免隐式 any。
2. 函数式优先：首选 Hooks 写法，Class 组件仅在极特殊场景保留。
3. 组件单一职责：保持组件小而纯，单个文件控制在 300–400 行以内。
4. 原子化设计：UI 优先采用可组合的原子组件 + 组合组件模式。
5. 状态管理克制：能用 useState + useReducer 解决就不引入重型库。
6. 样式方案：优先 Tailwind CSS 搭配 shadcn/ui、Radix UI 或 Headless UI。
7. 代码风格统一：严格遵循 ESLint + Prettier + typescript-eslint 推荐规则。
8. 注释规范：关键工具函数、Hooks 及复杂组件必须编写 JSDoc/TSDoc 注释。
9. 现代语法：优先使用可选链、空值合并运算符、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 写法（现代风格）

import React from 'react';

   .<> {
  ?:  |  |  |  | ;
  ?:  |  |  | ;
  ?: ;
  ?: ;
  ?: .;
  ?: .;
}

  = .<, >(
   {
    
  }
);

. = ;