CLAUDE.md Examples

Copy-paste templates for common project types. All validated by ClaudeCheck's 12 rules.

TypeScript React 18 Next.js 14 Tailwind

# My App

## Tech Stack
- TypeScript 5.3, strict mode enabled
- React 18 with functional components and hooks only
- Next.js 14 using App Router (not Pages Router)
- Tailwind CSS 4 for all styling (no CSS modules)
- Prisma ORM with PostgreSQL
- Vitest + React Testing Library for tests

## Code Style
- Named exports only, no default exports
- Use `const` by default, `let` only when reassignment is needed
- Prefer early returns over nested conditionals
- Use `async/await`, never `.then()` chains
- File naming: kebab-case (`user-profile.tsx`)
- Component naming: PascalCase (`UserProfile`)
- Import order: React, Next.js, third-party, local (separated by blank lines)

## Project Structure
- `src/app/` — App Router pages, layouts, and route handlers
- `src/components/` — Shared React components
- `src/components/ui/` — Design system primitives (Button, Input, etc.)
- `src/lib/` — Utilities, hooks, and shared logic
- `src/server/` — Server-only code (DB queries, auth)
- `prisma/` — Database schema and migrations

## Testing
- Run all: `npm test`
- Run one file: `npm test -- user-profile.test.tsx`
- Use `describe` / `it` blocks (not `test`)
- Mock external APIs with MSW, never mock internal modules
- Test user behavior, not implementation details
- New components need at least one render + interaction test

## Git Conventions
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`
- Branch from `main`, squash merge back
- PR titles match commit format

## Common Commands
- `npm run dev` — Dev server on localhost:3000
- `npm run build` — Production build
- `npm test` — Run Vitest
- `npm run lint` — ESLint + Prettier check
- `npx prisma migrate dev` — Run DB migrations
- `npx prisma studio` — Open DB browser

Python 3.12 FastAPI SQLAlchemy

# My API

## Tech Stack
- Python 3.12
- FastAPI with Pydantic v2 for validation
- SQLAlchemy 2.0 with async session (not legacy 1.x patterns)
- PostgreSQL 16
- Alembic for migrations
- pytest with pytest-asyncio for testing
- uv for dependency management

## Code Style
- Type hints on all function signatures (no `Any` unless unavoidable)
- Use `async def` for all route handlers and DB operations
- Pydantic models for all request/response schemas
- Snake_case for everything (variables, functions, files)
- Docstrings only on public functions with non-obvious behavior
- Prefer `raise HTTPException` over returning error dicts
- Use `Depends()` for dependency injection, never global state

## Project Structure
- `src/app/` — FastAPI application and configuration
- `src/app/routers/` — Route handlers grouped by domain
- `src/app/models/` — SQLAlchemy models
- `src/app/schemas/` — Pydantic request/response schemas
- `src/app/services/` — Business logic layer
- `src/app/deps.py` — Shared dependencies (DB session, auth)
- `alembic/` — Database migrations
- `tests/` — Test files mirroring src structure

## Testing
- Run all: `uv run pytest`
- Run one: `uv run pytest tests/test_users.py -v`
- Use `pytest.mark.asyncio` for async tests
- Use factory fixtures for test data, not raw SQL
- Integration tests hit a real test database (no mocks for DB)
- API tests use `httpx.AsyncClient` with `app` fixture

## Common Commands
- `uv run fastapi dev` — Dev server with hot reload
- `uv run pytest` — Run tests
- `uv run alembic upgrade head` — Run migrations
- `uv run alembic revision --autogenerate -m "desc"` — Generate migration
- `uv run ruff check .` — Lint
- `uv run ruff format .` — Format

Go 1.22 Chi PostgreSQL

# My Service

## Tech Stack
- Go 1.22
- chi router for HTTP
- pgx for PostgreSQL (not database/sql)
- sqlc for type-safe SQL queries
- zerolog for structured logging
- testify for test assertions

## Code Style
- Follow standard Go conventions (gofmt, go vet)
- Use context.Context as first parameter for functions that do I/O
- Return errors, never panic (except in init)
- Wrap errors with `fmt.Errorf("doing X: %w", err)`
- Use table-driven tests
- Interface definitions go in the consumer package, not the implementer
- No global mutable state; pass dependencies via struct fields

## Project Structure
- `cmd/server/` — Application entrypoint
- `internal/api/` — HTTP handlers and middleware
- `internal/domain/` — Core business types and interfaces
- `internal/store/` — Database queries (generated by sqlc)
- `internal/service/` — Business logic
- `sql/` — SQL queries and migrations

## Testing
- Run all: `go test ./...`
- Run one package: `go test ./internal/api/ -v`
- Integration tests use build tag: `go test -tags=integration ./...`
- Table-driven tests for all functions with multiple cases
- Use `testify/assert` and `testify/require`

## Common Commands
- `go run cmd/server/main.go` — Run server
- `go test ./...` — Run all tests
- `go vet ./...` — Static analysis
- `sqlc generate` — Regenerate DB queries
- `migrate -path sql/migrations -database $DB_URL up` — Run migrations

Rust Axum SQLx

# My Service

## Tech Stack
- Rust (latest stable)
- Axum 0.7 for HTTP
- SQLx with compile-time checked queries
- PostgreSQL 16
- Tokio runtime
- tracing for structured logging
- serde for serialization

## Code Style
- Prefer `thiserror` for library errors, `anyhow` for application errors
- Use `?` operator for error propagation, avoid `.unwrap()` in production code
- Derive `Debug` on all public types
- Keep functions under 40 lines; extract helpers when longer
- Use `impl Into<String>` for string parameters that accept both `&str` and `String`
- Module per file, `mod.rs` only for re-exports

## Project Structure
- `src/main.rs` — Entrypoint and server setup
- `src/api/` — Route handlers and extractors
- `src/models/` — Database models and domain types
- `src/db/` — Database pool and queries
- `src/error.rs` — Error types and conversions
- `migrations/` — SQLx migrations

## Testing
- Run all: `cargo test`
- Run one: `cargo test test_name`
- Integration tests in `tests/` directory
- Use `#[sqlx::test]` for DB-dependent tests
- Prefer `assert_eq!` with descriptive messages

## Common Commands
- `cargo run` — Run in debug mode
- `cargo test` — Run all tests
- `cargo clippy` — Lints
- `cargo fmt` — Format
- `sqlx migrate run` — Run DB migrations

Node.js 20 Express TypeScript

# My API

## Tech Stack
- Node.js 20 LTS
- TypeScript 5.3 in strict mode
- Express 4 with express-async-errors
- Drizzle ORM with PostgreSQL
- Zod for runtime validation
- Jest for testing
- pnpm for package management

## Code Style
- Explicit return types on all exported functions
- Use Zod schemas for all request validation (not manual checks)
- Throw `AppError` (custom class) for expected errors
- Use dependency injection via constructor parameters
- No `any` type; use `unknown` and narrow with type guards
- Prefer `Map` and `Set` over plain objects for dynamic keys

## Project Structure
- `src/index.ts` — Server entrypoint
- `src/routes/` — Express route definitions
- `src/controllers/` — Request handlers
- `src/services/` — Business logic
- `src/db/` — Drizzle schema and migrations
- `src/middleware/` — Express middleware (auth, errors, logging)
- `src/types/` — Shared TypeScript types

## Testing
- Run all: `pnpm test`
- Run watch: `pnpm test -- --watch`
- Unit tests colocated: `user.service.test.ts` next to `user.service.ts`
- Integration tests in `tests/integration/`
- Use `supertest` for API endpoint tests
- Seed test DB with fixtures, never use production data

## Common Commands
- `pnpm dev` — Dev server with tsx watch
- `pnpm build` — TypeScript compilation
- `pnpm test` — Jest
- `pnpm lint` — ESLint
- `pnpm db:push` — Push schema to DB
- `pnpm db:generate` — Generate migration

Turborepo pnpm TypeScript

# My Platform

## Tech Stack
- Turborepo with pnpm workspaces
- TypeScript 5.3 across all packages
- Apps: Next.js 14 (web), Fastify (api), React Native (mobile)
- Shared packages: `@repo/ui`, `@repo/db`, `@repo/config`

## Code Style
- All rules from individual app CLAUDE.md files apply within those apps
- Shared packages use barrel exports (`index.ts`)
- Cross-package imports must use package names (`@repo/ui`), never relative paths
- Changes to shared packages require testing all dependent apps

## Project Structure
- `apps/web/` — Next.js frontend (has its own CLAUDE.md)
- `apps/api/` — Fastify API server (has its own CLAUDE.md)
- `apps/mobile/` — React Native app
- `packages/ui/` — Shared React component library
- `packages/db/` — Drizzle schema, shared DB client
- `packages/config/` — Shared ESLint, TypeScript, Tailwind configs
- `turbo.json` — Pipeline configuration

## Testing
- Run all: `pnpm test` (turborepo runs per-package test scripts)
- Run one app: `pnpm --filter web test`
- Run one package: `pnpm --filter @repo/ui test`
- Shared packages must have 90% coverage
- Apps must have 80% coverage

## Common Commands
- `pnpm dev` — Start all apps in dev mode
- `pnpm build` — Build all (respects dependency graph)
- `pnpm test` — Run all tests
- `pnpm --filter web dev` — Start only web app
- `pnpm add -D pkg --filter @repo/ui` — Add dep to specific package
- `turbo run lint` — Lint all packages with caching

Validate before committing

Paste any of these examples (or your own CLAUDE.md) into the validator to check for issues:

Open ClaudeCheck Validator

Need more guidance? Read the complete CLAUDE.md writing guide.