CLAUDE.md Templates & Examples

# CLAUDE.md

## Project Overview
{{project_name}} — {{one-line description}}

## Tech Stack
- Framework: Next.js 14+ (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS + shadcn/ui
- Database: {{database}} (e.g., PostgreSQL via Supabase)
- ORM: {{orm}} (e.g., Drizzle ORM, Prisma)
- Auth: {{auth_provider}}

## Commands
```bash
npm run dev       # Start dev server
npm run build     # Production build
npm run lint      # Run ESLint
npm run test      # Run tests
```

## Directory Structure
```
src/
├── app/          # App Router pages and layouts
├── components/
│   ├── ui/       # shadcn/ui primitives
│   └── {{domain}}/  # Feature-specific components
├── lib/
│   ├── actions/  # Server actions
│   ├── hooks/    # Custom React hooks
│   └── utils.ts  # Shared utilities
└── types/        # TypeScript type definitions
```

## Conventions
- Components: PascalCase.tsx
- Utilities: kebab-case.ts
- Server actions: kebab-case-actions.ts
- Use `cn()` from lib/utils for conditional classes
- Prefer server components; add 'use client' only when needed
- Import order: React > external > @/ aliases > relative > types

# CLAUDE.md

## Project Overview
{{project_name}} — {{one-line description}}

## Tech Stack
- Language: Python 3.11+
- Framework: FastAPI
- ORM: SQLAlchemy 2.0 (async)
- Database: PostgreSQL
- Migrations: Alembic
- Testing: pytest + pytest-asyncio
- Linting: ruff

## Commands
```bash
uv run uvicorn app.main:app --reload   # Dev server
uv run pytest                           # Run tests
uv run ruff check .                     # Lint
uv run alembic upgrade head             # Apply migrations
uv run alembic revision --autogenerate -m "description"  # New migration
```

## Directory Structure
```
app/
├── main.py           # FastAPI app + middleware
├── api/
│   └── v1/           # Versioned route handlers
├── models/           # SQLAlchemy models
├── schemas/          # Pydantic request/response schemas
├── services/         # Business logic
├── repositories/     # Database queries
└── core/
    ├── config.py     # Settings via pydantic-settings
    ├── database.py   # Async engine + session
    └── security.py   # Auth utilities
```

## Conventions
- Type hints on all function signatures
- Async by default for all DB operations
- Use dependency injection via FastAPI Depends()
- Pydantic models for all API input/output
- Never use raw SQL strings — use SQLAlchemy query builder
- snake_case for everything (files, functions, variables)

# CLAUDE.md

## Project Overview
{{project_name}} — {{one-line description}}

## Tech Stack
- Language: Go 1.22+
- Router: chi v5
- Database: PostgreSQL via pgx
- Migrations: goose
- Testing: standard library + testify
- Config: envconfig

## Commands
```bash
go run ./cmd/server          # Start server
go test ./...                # Run all tests
goose -dir migrations up     # Apply migrations
golangci-lint run            # Lint
```

## Directory Structure
```
cmd/
└── server/main.go       # Entrypoint
internal/
├── api/                 # HTTP handlers
│   ├── middleware/       # Auth, logging, CORS
│   └── handlers/        # Route handlers
├── domain/              # Business logic + types
├── repository/          # Database queries
└── config/              # Environment config
pkg/                     # Shared/exported packages
migrations/              # SQL migration files
```

## Conventions
- Follow standard Go project layout
- Errors are values — return them, don't panic
- Use context.Context for cancellation and timeouts
- Interfaces defined by consumers, not providers
- Table-driven tests with clear subtest names
- No init() functions — explicit initialization in main
- Use pgx directly, not GORM

# CLAUDE.md

## Project Overview
{{project_name}} — {{one-line description}}

## Tech Stack
- Framework: React Native via Expo SDK 51+
- Language: TypeScript
- Navigation: Expo Router (file-based)
- Styling: NativeWind (Tailwind for RN)
- State: Zustand
- API: React Query (TanStack Query)
- Auth: {{auth_provider}}

## Commands
```bash
npx expo start          # Dev server
npx expo run:ios        # iOS build
npx expo run:android    # Android build
npm run test            # Jest tests
```

## Directory Structure
```
app/                    # Expo Router file-based routes
├── (tabs)/             # Tab navigator group
├── (auth)/             # Auth flow screens
└── _layout.tsx         # Root layout
components/
├── ui/                 # Reusable primitives
└── {{domain}}/         # Feature components
lib/
├── api/                # API client + React Query hooks
├── stores/             # Zustand stores
└── utils/              # Shared utilities
```

## Conventions
- Use Expo modules over bare RN when available
- NativeWind className for all styling (no StyleSheet)
- Platform-specific code: .ios.tsx / .android.tsx suffixes
- Always test on both iOS and Android
- Use expo-secure-store for sensitive data, never AsyncStorage
- Screens are thin — business logic lives in hooks/stores

# CLAUDE.md

## Project Overview
{{project_name}} — {{one-line description}}

## Tech Stack
- Language: Python 3.11+
- Framework: Django 5.0+ / Django REST Framework
- Task Queue: Celery + Redis
- Database: PostgreSQL
- Testing: pytest-django
- Linting: ruff

## Commands
```bash
python manage.py runserver           # Dev server
python manage.py test                # Run tests
celery -A config worker --loglevel=info  # Start worker
python manage.py makemigrations      # Generate migrations
python manage.py migrate             # Apply migrations
```

## Directory Structure
```
config/                  # Django project settings
├── settings/
│   ├── base.py          # Shared settings
│   ├── local.py         # Dev overrides
│   └── production.py    # Prod overrides
apps/
├── {{app_name}}/
│   ├── models.py
│   ├── serializers.py   # DRF serializers
│   ├── views.py         # ViewSets
│   ├── urls.py
│   ├── tasks.py         # Celery tasks
│   ├── services.py      # Business logic
│   └── tests/
```

## Conventions
- Fat models, thin views — complex logic in model methods or services.py
- Use ModelSerializer for standard CRUD, custom serializers for complex input
- Celery tasks for anything that takes > 500ms
- Always use select_related/prefetch_related to avoid N+1 queries
- Permissions in permissions.py, not inline in views
- Use Django signals sparingly — prefer explicit service calls

# CLAUDE.md

## Project Overview
{{project_name}} — {{one-line description}}

## Tech Stack
- Language: Rust (latest stable)
- Web framework: Axum 0.7+
- Database: PostgreSQL via SQLx (compile-time checked queries)
- Serialization: serde + serde_json
- Error handling: thiserror + anyhow
- Auth: {{auth_approach}}
- Tracing: tracing + tracing-subscriber

## Commands
```bash
cargo run                    # Dev server
cargo test                   # Run tests
cargo clippy -- -D warnings  # Lint
sqlx migrate run             # Apply migrations
sqlx prepare                 # Prepare offline query cache
```

## Directory Structure
```
src/
├── main.rs              # Server setup + routing
├── routes/              # Axum handler functions
├── models/              # Database models (FromRow)
├── services/            # Business logic
├── extractors/          # Custom Axum extractors
├── error.rs             # App error type + IntoResponse
└── config.rs            # Environment config
migrations/              # SQLx migrations
```

## Conventions
- Use typed extractors (Json<T>, Path<T>, Query<T>)
- Custom AppError type that implements IntoResponse
- All DB queries via sqlx::query_as! (compile-time checked)
- Use Arc<AppState> for shared state
- Prefer &str over String in function parameters
- No unwrap() in production code — use ? operator
- Run `sqlx prepare` before committing if queries changed

# CLAUDE.md

## Project Overview
{{project_name}} — {{one-line description}}

## Tech Stack
- Language: {{language}}
- Framework: {{framework}}
- Database: {{database}}
- Testing: {{test_framework}}

## Commands
```bash
{{dev_command}}      # Start dev server
{{test_command}}     # Run tests
{{lint_command}}     # Lint
{{build_command}}    # Production build
```

## Key Rules
- {{rule_1}} (e.g., "Always use TypeScript strict mode")
- {{rule_2}} (e.g., "Prefer composition over inheritance")
- {{rule_3}} (e.g., "No console.log in committed code")
- {{rule_4}} (e.g., "All API responses use camelCase")
- {{rule_5}} (e.g., "Tests required for all business logic")

## Import Order
1. Standard library
2. External dependencies
3. Internal modules
4. Relative imports
5. Type-only imports