bencium-code-conventions

代码约定

核心技术

• 前端： 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 模块（import/export）语法
• 尽可能解构导入内容
• 所有新代码都使用 TypeScript
• 使用 async/await，而不是 Promise 链
• 优先使用 const/let 而不是 var；尽早返回
• 使用常量而不是函数：const toggle = () =>。定义类型。
• 使用描述性变量名，并包含辅助动词（例如 isLoading、hasError）
• 目录名使用小写并以连字符分隔（例如 components/auth-wizard）

框架约定

• Next.js： 使用 App Router（app 目录）结构和 page.tsx 文件
• React： 使用函数式和声明式模式；避免使用类
• 状态管理： Zustand、TanStack React Query
• 验证： 使用 Zod 进行模式验证

组件库与样式

• 组件库： 优先使用 @/components/ui 中的 shadcn 组件
• 样式： Tailwind 工具类
• 布局： 使用带有 gap 间距的 Grid/flex 容器
• 图标： @phosphor-icons/react
• Toast： 使用 sonner 发送通知
• 始终添加加载状态、旋转指示器和占位动画

质量保证与测试

• TDD： 先编写失败的测试并提交，然后迭代，直到测试套件通过
• 绝不模拟测试——如果有测试脚本，就执行所有测试，直到完成
• 始终分块编写 SQL，并在每个代码块后添加测试步骤
• 修改代码后进行类型检查
• 提交前运行测试
• 为提升性能，优先运行单个测试，而不是整个测试套件

错误处理

• 实现恰当的错误处理和用户输入验证
• 错误消息应让非技术人员也能理解
• 遇到错误情况时尽早返回
• 先通过 curl 命令测试 API，再在代码中实现

性能与架构

• 尽量减少 'use client'、useEffect 和 setState 的使用；优先采用 RSC 和 Next.js SSR
• 使用动态导入进行代码拆分
• 优化图片：使用 WebP 格式、调整数据大小并启用懒加载
• 优先采用小型、简单且命名清晰的模块

开发工作流

流程： 探索 → 规划 → 编码 → 提交

• 阅读相关文件
• 仔细考虑计划
• 实施
• 然后提交
• 绝不使用本地后端，务必先询问（通常使用 Supabase、Neon）
• 尽量减少依赖，不使用 docker

环境与部署

• 添加 .env 文件存放 API 密钥；提醒我将密钥保存到 Vercel/Netlify 环境变量中
• 编写可部署到 Netlify 或 Vercel 的代码；先准备在本地构建
• 在 progress.md 中记录进度；询问实施计划