Production-ready CLAUDE.md template establishing architecture context, coding constraints, test protocols, and CLI commands for Claude Code.
CLAUDE.md Guidelines & Project Memory
This file provides persistent instructions and architectural context for Claude Code when working in this repository.
1. Project Overview & Architecture
- Framework & Runtime: Node.js 20+, React 18 / Next.js 14, TypeScript (Strict Mode).
- Styling: Tailwind CSS + shadcn/ui components. Avoid inline styles or custom ad-hoc CSS classes.
- Backend & Database: Express / Hono API with Drizzle ORM and PostgreSQL.
- State & Routing: Wouter / Next.js App Router with TanStack Query for server state.
2. Core Development Rules
1. TypeScript Strictness: Never use any. Use unknown and narrow via type guards or Zod schemas.
2. Component Conventions:
- Keep components focused and under 250 lines.
- Separate business logic into custom hooks in
src/hooks/.
- Use Lucide React icons for all UI iconography.
3. Database Operations:
- Never write raw SQL in route handlers; use the storage layer in
server/storage.ts.
- Always wrap multi-table modifications in transactions.
4. Error Handling:
- Always return standardized JSON error objects:
{ error: string, code?: string, details?: any }.
- Never leak stack traces or internal environment variables to client responses.
3. Essential Commands
# Development server
npm run dev
# Type check & linting
npm run check
npm run lint
# Database migrations
npm run db:push
# Test suites
npm run test
npm run test:e2e
4. Verification Protocol Before Completing Tasks
- [ ] Run
npm run check and verify 0 TypeScript diagnostic errors.
- [ ] Ensure all modified functions have corresponding unit tests in
tests/.
- [ ] Verify that no
console.log or debug comments remain in source files.
- [ ] Check responsive layout on both desktop and 390px mobile viewport widths.