AI 编程规范

Appearance

前端技术栈 ​

核心原则 ​

生成前端代码时必须使用本文档指定的技术栈和版本，禁止使用其他替代方案或过时版本。

技术栈清单 ​

React 19 ​

版本要求：19

技术特点：

  • 最新稳定版本，支持并发渲染和自动批处理
  • 强大的 Hooks 生态系统
  • 优秀的性能和开发者体验
  • 企业级应用的主流选择

核心特性：

  • 函数式组件和 Hooks
  • 并发渲染（Concurrent Rendering）
  • 自动批处理（Automatic Batching）
  • Suspense 和 React.lazy 代码分割

使用约束：

  • 必须使用函数式组件，禁止使用 Class 组件
  • 必须遵循 Hooks 规则（不在循环、条件中调用）
  • 应该使用 TypeScript 定义 Props 类型
  • 应该使用 memo、useMemo、useCallback 优化性能

参考文档：React 规范

Vite 7 ​

版本要求：7

技术特点：

  • 极速的开发服务器启动
  • 基于 ESM 的热模块替换（HMR）
  • 开箱即用的 TypeScript 支持
  • 优化的生产构建（基于 Rolldown）

核心特性：

  • 原生 ESM 开发服务器
  • 按需编译，无需打包
  • 内置 CSS、JSON、静态资源处理
  • 丰富的插件生态

使用约束：

  • 必须使用 vite.config.ts 配置项目
  • 必须配置路径别名 @/* 指向 src/*
  • 应该使用环境变量管理不同环境配置
  • 禁止在 vite.config.ts 中硬编码敏感信息

参考文档：Vite 规范

shadcn/ui ​

版本要求：latest

技术特点：

  • 基于 Radix UI 的无障碍组件
  • 代码复制到项目中，完全可控
  • 使用 Tailwind CSS 样式
  • 高度可定制，支持主题切换

核心特性：

  • 丰富的 UI 组件（Button、Card、Dialog、Form 等）
  • 使用 CSS 变量定义主题
  • 支持暗色模式
  • 与 React Hook Form 深度集成

使用约束：

  • 必须通过 CLI 安装组件（npx shadcn@latest add）
  • 必须使用 cn() 工具函数合并类名
  • 应该根据项目需求定制组件代码
  • 禁止直接修改 node_modules 中的组件
  • 禁止引入其他 UI 组件库（如 Ant Design、Material-UI、Element 等）

参考文档：组件开发

Tailwind CSS 4 ​

版本要求：4

技术特点：

  • 原子化 CSS 框架
  • 高性能 Oxide 引擎
  • 自动内容检测
  • 原生支持 CSS 变量主题

核心特性：

  • 原子类样式系统
  • 响应式设计断点
  • 暗色模式支持
  • CSS 变量主题定制

使用约束：

  • 必须使用 Tailwind 原子类，禁止使用内联样式
  • 应该使用 @theme 定义自定义主题变量
  • 应该遵循移动优先的响应式设计
  • 禁止在组件中硬编码颜色值

参考文档：样式规范

React Router v7 ​

版本要求：v7

技术特点：

  • React 官方推荐的路由方案
  • 支持声明式和数据驱动模式
  • 内置 startTransition 性能优化
  • TypeScript 类型安全

核心特性：

  • 声明式路由配置
  • 嵌套路由和布局
  • 动态路由参数
  • 代码分割和懒加载

使用约束：

  • 必须使用 createBrowserRouter 创建路由
  • 必须为受保护页面实现路由守卫
  • 应该使用 lazy() 实现路由级代码分割
  • 禁止在组件中直接操作 window.location

参考文档：路由规范

Zustand 5 ​

版本要求：5

技术特点：

  • 极简状态管理库（约 3KB）
  • 无需 Provider 包裹
  • 支持 TypeScript
  • 支持中间件扩展

核心特性：

  • 简洁的 API 设计
  • 支持异步操作
  • 选择器优化性能
  • 支持持久化存储

使用约束：

  • 必须为每个 Store 定义 TypeScript 接口
  • 应该使用选择器避免不必要的重渲染
  • 应该将大型状态拆分为多个 Store
  • 禁止在 Store 中存储可派生的状态

参考文档：状态管理规范

React Hook Form + Zod ​

版本要求：React Hook Form latest, Zod latest

技术特点：

  • 高性能表单库，减少不必要的重渲染
  • Zod 提供类型安全的 Schema 验证
  • 与 shadcn/ui Form 组件深度集成
  • 优秀的开发者体验

核心特性：

  • 受控和非受控表单支持
  • Schema 驱动的表单验证
  • 异步验证支持
  • 字段级和表单级错误处理

使用约束：

  • 必须使用 Zod Schema 定义表单验证规则
  • 必须使用 zodResolver 连接 React Hook Form
  • 应该复用通用的 Zod Schema
  • 禁止在组件中编写手动验证逻辑

参考文档：表单规范

TanStack Table v8 ​

版本要求：v8

技术特点：

  • Headless UI 表格库
  • 支持排序、筛选、分页
  • 高度可定制
  • TypeScript 支持

核心特性：

  • 列定义和数据绑定
  • 客户端和服务端分页
  • 多列排序
  • 全局和列级筛选

使用约束：

  • 必须使用 useReactTable Hook 创建表格实例
  • 应该配合 shadcn/ui Table 组件使用
  • 应该为大数据量启用虚拟滚动
  • 禁止直接操作 DOM 修改表格

TypeScript 5.6 ​

版本要求：5.6

技术特点：

  • 静态类型检查，减少运行时错误
  • 优秀的 IDE 支持和代码提示
  • React 19 和 Vite 7 的最佳搭配版本
  • 企业级应用的标准选择

核心特性：

  • 严格类型检查（strict mode）
  • 泛型和高级类型
  • 接口和类型别名
  • 路径别名支持

使用约束：

  • 必须为所有组件定义 Props 接口
  • 必须为 API 响应定义类型
  • 必须启用严格模式（strict: true）
  • 禁止使用 any 类型（特殊情况需注释说明）
  • 应该使用类型推断，避免冗余类型标注

参考文档：TypeScript 规范

Biome（代码检查和格式化） ​

版本要求：latest

技术特点：

  • 统一的 Linter 和 Formatter
  • 比 ESLint + Prettier 更快
  • 现代化的配置方式
  • 一致的代码风格

核心特性：

  • 代码格式化（Formatter）
  • 代码检查（Linter）
  • 自动修复
  • IDE 集成

使用约束：

  • 必须在提交前运行 Biome 格式化
  • 应该在 IDE 中启用 Biome 自动格式化
  • 禁止提交未格式化的代码
  • 必须使用单引号（quoteStyle: 'single'）
  • 必须使用空格缩进（indentStyle: 'space'）

配置位置：biome.json

Vitest（测试框架） ​

版本要求：latest

技术特点：

  • 与 Vite 深度集成
  • 执行速度极快
  • API 兼容 Jest
  • 原生支持 TypeScript 和 ESM

核心特性：

  • 单元测试
  • 组件测试（配合 @testing-library/react）
  • 快照测试
  • 覆盖率报告

使用约束：

  • 应该为关键组件编写单元测试
  • 应该为工具函数编写测试用例
  • 应该保持测试覆盖率 > 70%

参考文档：测试规范

dayjs（时间处理） ​

版本要求：latest

技术特点：

  • 轻量级时间处理库
  • API 简洁易用
  • 支持国际化

使用约束：

  • 必须使用 dayjs 处理时间（禁止使用 moment.js）
  • 应该使用 dayjs 的本地化功能

技术栈关系图 ​

包管理 ​

包管理器：npm

使用约束：

  • 必须使用 npm 安装依赖
  • 应该定期运行 npm audit 检查安全漏洞
  • 禁止使用 yarn 或 pnpm（保持团队一致性）

相关文档 ​

Released under the MIT License