前端通用 Rules 定义
（适用于 Cursor、Trae、Qoder、Windsurf、Zed + AI、Codeium、Copilot 等几乎所有主流 AI 代码助手）
这套规则是在多个项目中反复迭代后的沉淀，直接配置到 AI 助手的上下文里，能显著减少沟通成本。你可以直接复制粘贴到 Cursor 的 Rules / Custom Instructions / 项目 .cursor/rules.md 中，或者 Trae、Qoder 等工具的类似位置。
推荐的通用前端 Rules 结构（2026 年主流写法）
核心原则（永远优先遵守）
- 优先使用 TypeScript：开启严格模式，类型安全是基石。
- 函数式优先：优先函数式 + 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）。
- 优先使用解构 + 默认值写法，避免 props 传递混乱。
- 必须显式声明
children?: ReactNode。 - 动态 className 使用 clsx 或 cva（class-variance-authority）。
- 禁止在组件内部写业务逻辑超过 30 行 → 抽离到 hooks / utils。
- 所有副作用必须放在 useEffect 中，并写清楚依赖数组。
- 自定义 hooks 命名必须以 use 开头。
- 禁止在 render 阶段产生副作用（setState、dispatch 等）。
推荐的组件 Props 写法（现代风格）
interface ButtonProps extends React.ButtonHTMLAttributes<> {
?: | | | |
?: | | |
?:
?:
?: .
?: .
}
= .<, >(
{
}
)
. =
