前端通用 AI Rules 定义
在当前的 AI 辅助编程环境下，Cursor、Trae、Qoder 等工具虽然强大，但输出的质量高度依赖于上下文规则。整理了一套经过验证的前端通用 Rules 模板，涵盖 TypeScript 严格模式、组件规范、样式策略及性能红线。直接配置至项目规则文件即可生效，减少沟通成本，让 AI 生成更符合团队规范的代码。
核心原则（永远优先遵守）
- 类型安全：优先使用 TypeScript（严格模式），禁止
any类型（除非极特殊场景并加说明）。 - 架构风格：优先函数式 + hooks 写法，class 组件仅在极特殊场景使用。
- 单一职责：组件尽量小而纯，单个文件不超过 300–400 行。
- 原子化设计：UI 优先使用可组合、可复用的原子组件 + 组合组件模式。
- 状态管理：能用 useState + useReducer 解决就不引入 Zustand / Jotai / Redux。
- 样式方案：优先 Tailwind CSS + shadcn/ui / Radix UI / Headless UI 组合。
- 代码规范：严格遵循 ESLint + Prettier + typescript-eslint 推荐规则。
- 文档习惯：永远写 JSDoc / TSDoc 注释（尤其是工具函数、hooks、复杂组件）。
- 现代语法：优先使用可选链、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 阶段产生副作用。
这里有一个推荐的 Button 组件写法示例，展示了现代风格的 Props 定义和 forwardRef 用法：
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive'
?: | | |
?:
?:
?: .
?: .
}
= .<, >(
{
}
)
. =
