CLAUDE.md Guide

~/.claude/CLAUDE.md           # Global defaults (all projects)
~/projects/my-app/CLAUDE.md   # Project root (most common)
~/projects/my-app/src/CLAUDE.md  # Directory-specific

# Project Name

## Overview
Brief description of what this project does.

## Tech Stack
- Framework and version
- Key libraries
- Database/services

## Project Structure
Key directories and their purposes.

## Coding Conventions
Style guide, patterns, naming conventions.

## Common Tasks
Frequent operations and how to perform them.

# E-Commerce Platform

## Overview
A full-stack e-commerce platform built with Next.js,
featuring product catalog, shopping cart, and checkout.

## Tech Stack
- **Framework**: Next.js 14 (App Router)
- **Language**: TypeScript 5.x (strict mode)
- **Styling**: Tailwind CSS 3.x
- **Database**: PostgreSQL with Prisma ORM
- **Auth**: NextAuth.js with Google/GitHub providers
- **Payments**: Stripe

## Project Structure
\`\`\`
src/
├── app/              # Next.js App Router pages
├── components/       # React components
│   ├── ui/          # Reusable UI components
│   └── features/    # Feature-specific components
├── lib/             # Utility functions
├── hooks/           # Custom React hooks
├── types/           # TypeScript type definitions
└── styles/          # Global styles
\`\`\`

## Coding Conventions

### Components
- Use functional components with TypeScript
- Props interface named `{ComponentName}Props`
- Export components as named exports
- Co-locate component styles and tests

### Naming
- Components: PascalCase (`ProductCard.tsx`)
- Utilities: camelCase (`formatPrice.ts`)
- Constants: SCREAMING_SNAKE_CASE
- CSS classes: kebab-case

### State Management
- Server state: React Query
- Client state: Zustand for global, useState for local
- Form state: React Hook Form

## Database

### Running Migrations
\`\`\`bash
pnpm prisma migrate dev    # Development
pnpm prisma migrate deploy # Production
\`\`\`

### Seeding
\`\`\`bash
pnpm prisma db seed
\`\`\`

## Common Tasks

### Adding a New Page
1. Create file in `src/app/[route]/page.tsx`
2. Add metadata export for SEO
3. Create associated components in `src/components/features/`

### Adding a New API Route
1. Create file in `src/app/api/[route]/route.ts`
2. Use `NextResponse` for responses
3. Add Zod schema for validation

## Environment Variables
Required variables in `.env.local`:
- `DATABASE_URL` - PostgreSQL connection string
- `NEXTAUTH_SECRET` - Auth encryption key
- `STRIPE_SECRET_KEY` - Stripe API key

## Testing
\`\`\`bash
pnpm test        # Run all tests
pnpm test:watch  # Watch mode
pnpm test:cov    # With coverage
\`\`\`

## Deployment
- Main branch auto-deploys to production
- PRs create preview deployments
- Run `pnpm build` locally to verify before pushing

## Overview
A real-time collaborative document editor supporting
multiple users, rich text formatting, and version history.
Built for teams who need Google Docs-like functionality
with self-hosting capabilities.

## Tech Stack
- React 18.2 with TypeScript 5.3
- Vite 5.0 for bundling
- TanStack Query v5 for data fetching
- Tailwind CSS 3.4
- Vitest for testing

## Conventions

### Error Handling
- Use custom `AppError` class for application errors
- Wrap async route handlers with `asyncHandler`
- Log errors to Sentry in production

### API Responses
Always return consistent shape:
\`\`\`typescript
{
  success: boolean;
  data?: T;
  error?: { code: string; message: string };
}
\`\`\`

# Test Directory

## Testing Conventions
- Use `describe` blocks for grouping
- Name tests: "should [expected behavior] when [condition]"
- Mock external services, not internal modules
- Aim for >80% coverage on business logic

# Scripts Directory

## Script Conventions
- Scripts should be idempotent when possible
- Include --dry-run flag for destructive operations
- Log progress to stdout, errors to stderr
- Exit with appropriate codes (0 success, 1 error)

## API Design
- RESTful endpoints under `/api/v1/`
- Use HTTP verbs correctly (GET, POST, PUT, DELETE)
- Return appropriate status codes
- Include pagination for list endpoints

## CLI Conventions
- Use Commander.js for argument parsing
- Support both `--flag` and `-f` short forms
- Provide helpful `--help` output
- Use chalk for colored output

## Library Guidelines
- Maintain backward compatibility in minor versions
- Document all public APIs with JSDoc
- Include TypeScript declarations
- Provide migration guides for breaking changes