bencium-code-conventions（Bencium 代码约定）

Code Conventions

Core Technologies

• Frontend: ReactJS, Next.js (App Router structure), TypeScript
• Styling: TailwindCSS v3.x (never v4), Shadcn UI
• Build Tools: Vite (when applicable)
• Backend: Postgres compatible convex.dev or Supabase (always ask, never local postgres)
• Deployment: Netlify or Vercel or Fly - suggest
• Environment: Mac M2, Python3 with virtual environments, no CUDA, no Docker
• Alternative Languages: Avoid python if you can, try using RUST

Code Style & Structure

• Use ES modules (import/export) syntax
• Destructure imports when possible
• Use TypeScript for all new code
• Use async/await instead of Promise chains
• Prefer const/let over var; use early returns
• Use consts instead of functions: const toggle = () =>. Define types.
• Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError)
• Use lowercase with dashes for directory names (e.g., components/auth-wizard)

Framework Conventions

• Next.js: Use App Router (app directory) structure and page.tsx files
• React: Functional and declarative patterns; avoid classes
• State Management: Zustand, TanStack React Query
• Validation: Zod for schema validation

Component Library & Styling

• Component Library: Prefer shadcn components from @/components/ui
• Styling: Tailwind utility classes
• Layout: Grid/flex wrappers with gap for spacing
• Icons: @phosphor-icons/react
• Toasts: sonner for notifications
• Always add loading states, spinners, placeholder animations

Quality Assurance & Testing

• TDD: Write failing tests first, commit them, then iterate until suite passes
• Never mock tests - if there's a test script, execute all until done
• Always write SQL in chunks with test steps after each chunk
• Typecheck after making code changes
• Run tests before committing
• Prefer running single tests for performance, not whole suite

Error Handling

• Implement proper error handling and user input validation
• Error messages should be understood by non-technical people
• Use early returns for error conditions
• Test APIs via curl commands first, then implement in code

Performance & Architecture

• Minimize 'use client', useEffect, setState; favor RSC and Next.js SSR
• Implement dynamic imports for code splitting
• Optimize images: WebP format, size data, lazy loading
• Favor small, simple, well-named modules

Development Workflow

Process: Explore → Plan → Code → Commit

• Read relevant files
• Think through a plan
• Implement
• Then commit
• Never local backend, always ask (usually Supabase, Neon)
• Minimal dependency, no docker

Environment & Deployment

• Add.env files for API keys; warn me to save keys in Vercel/Netlify env variables
• Write code deployable to Netlify or Vercel; prepare to build locally first
• Document progress in progress.md; ask for implementation plan