用途:这是一套代码约定(Code Conventions),用于约束 AI 或开发者在项目中的技术选型、代码风格与工作流程。
主要能力与规范要点: 前端采用 ReactJS、Next.js(App Router 结构)与 TypeScript;样式使用 TailwindCSS v3.x(明确不用 v4)与 Shadcn UI;构建工具在适用时使用 Vite。后端使用 Postgres 兼容的 convex.dev 或 Supabase,并强调“始终询问,不使用本地 Postgres”;部署建议 Netlify、Vercel 或 Fly。环境为 Mac M2、Python3 虚拟环境,无 CUDA、无 Docker;尽量避免 Python,尝试改用 Rust。
代码风格:使用 ES 模块语法,尽量解构导入,新代码用 TypeScript,以 async/await 替代 Promise 链,优先 const/let 而非 var,使用早返回;以 const 箭头函数(如 const toggle = () =>)代替函数声明并定义类型;变量名带辅助动词(如 isLoading、hasError);目录名小写加连字符。
框架约定:Next.js 使用 app 目录与 page.tsx;React 用函数式声明式模式,避免类;状态管理用 Zustand 与 TanStack React Query;校验用 Zod。组件优先使用 @/components/ui 的 shadcn 组件,用 Tailwind 工具类;图标用 @phosphor-icons/react,通知用 sonner;始终添加加载状态与占位动画。
质量与流程:TDD 先写失败测试并提交,再迭代至通过;不使用 mock 测试,若有测试脚本则全部执行;SQL 分块编写并在每块后加测试步骤;改代码后做类型检查,提交前运行测试,优先跑单个测试。实现错误处理与输入校验,错误信息需非技术人员可理解,用 curl 先测 API 再写代码。性能上减少 use client、useEffect、setState,倾向 RSC 与 SSR,动态导入做代码分割,图片用 WebP 并懒加载。
开发流程为探索→计划→编码→提交:先读相关文件、思考计划、实现、再提交。后端永远不用本地,需先询问(通常 Supabase、Neon);保持最小依赖、不用 Docker。用 .env 存放 API 密钥并提醒保存到 Vercel/Netlify 环境变量;代码需可部署到 Netlify 或 Vercel,先在本地构建;进度记录在 progress.md,实现计划需先询问。
限制:以上为约定文本描述,具体工具版本、配置与效果资料未提供细节。