CLAUDE.md Examples: 50+ Templates for Every Framework

Learn how to configure Claude Code for any framework using CLAUDE.md templates. This guide provides 50+ real-world examples organized by language and framework, plus best practices for writing your own.

Prerequisites

• Claude Code installed
• A project where you want to configure Claude Code's behavior
• Basic understanding of your framework's conventions

What Is CLAUDE.md?

CLAUDE.md is a configuration file you place in your project root that tells Claude Code how to work with your codebase. When Claude Code starts a session, it reads this file to understand your project's conventions, architecture, preferred patterns, and constraints.

Think of it as a .editorconfig for AI — instead of configuring tab width and line endings, you're configuring how an AI assistant understands and contributes to your project.

# Create a CLAUDE.md in your project root
touch CLAUDE.md

CLAUDE.md vs .cursorrules vs AGENTS.md

All serve the same purpose — configuring AI coding assistants. The content is often transferable between formats.

CLAUDE.md Template Structure

Every effective CLAUDE.md follows this pattern:

# Project Name

## Overview
[One paragraph: what the project does, tech stack, architecture]

## Tech Stack
- Frontend: [framework, version]
- Backend: [framework, version]
- Database: [type]
- Deployment: [method]

## Project Structure
[Key directories and what they contain]

## Development Commands
- `npm run dev` — Start development server
- `npm test` — Run tests
- `npm run build` — Production build

## Coding Conventions
[Language-specific patterns, naming, formatting]

## Important Rules
[What to NEVER do, critical constraints]

Templates by Framework

JavaScript / TypeScript

React + TypeScript

# Project: [Name]

## Tech Stack
- React 19 with TypeScript 5.x
- Vite for bundling
- React Router v7 for routing
- TanStack Query for server state
- Tailwind CSS for styling
- Vitest + React Testing Library for tests

## Project Structure
- `src/components/` — Reusable UI components
- `src/pages/` — Route-level page components
- `src/hooks/` — Custom React hooks
- `src/api/` — API client and type definitions
- `src/stores/` — Global state (Zustand)

## Coding Conventions
- Functional components only, no class components
- Use `const` arrow functions for components: `const Button = () => {}`
- Custom hooks must start with `use` prefix
- Colocate tests: `Button.test.tsx` next to `Button.tsx`
- Use absolute imports via `@/` alias
- Prefer composition over prop drilling — use hooks and context

## Styling
- Tailwind utility classes only, no CSS modules
- Use `cn()` helper for conditional classes
- Component variants via `cva` (class-variance-authority)
- Design tokens in `tailwind.config.ts`

## Testing
- Run: `npm test`
- Every component needs at least a render test
- Test user interactions, not implementation details
- Mock API calls with MSW, not jest.mock

## Important Rules
- NEVER use `any` type — use `unknown` and narrow
- NEVER mutate state directly — use immutable patterns
- NEVER use index as key in lists with dynamic items
- Always handle loading and error states in data fetching

Next.js 15 (App Router)

# Project: [Name]

## Tech Stack
- Next.js 15 with App Router
- TypeScript 5.x strict mode
- Server Components by default
- Prisma ORM + PostgreSQL
- NextAuth.js for authentication
- Tailwind CSS + shadcn/ui

## Project Structure
- `app/` — App Router pages and layouts
- `app/api/` — API Route Handlers
- `components/` — Shared UI components
- `lib/` — Utility functions and configurations
- `prisma/` — Database schema and migrations

## Architecture Rules
- Default to Server Components — only add 'use client' when needed
- Data fetching in Server Components, never in Client Components
- Use Server Actions for mutations, not API routes
- Colocate loading.tsx and error.tsx with page.tsx

## Development Commands
- `npm run dev` — Start dev server (port 3000)
- `npx prisma studio` — Database GUI
- `npx prisma migrate dev` — Run migrations
- `npm run build` — Production build with type checking

## Coding Conventions
- File naming: kebab-case for files, PascalCase for components
- One component per file
- Zod for all input validation (forms, API params)
- Use `next/image` for all images, never `<img>`
- Prefer `fetch` with `cache` and `revalidate` options

## Important Rules
- NEVER use `getServerSideProps` or `getStaticProps` — these are Pages Router patterns
- NEVER import server-only code in Client Components
- NEVER store secrets in client-side code — use server-only env vars
- Always add `loading.tsx` for pages with data fetching

Nuxt 3 + Vue 3

# Project: [Name]

## Tech Stack
- Nuxt 3 with Vue 3 Composition API
- TypeScript strict mode
- Auto-imports enabled (components, composables, utils)
- Pinia for state management
- Tailwind CSS for styling

## Project Structure
- `pages/` — File-based routing
- `components/` — Auto-imported components
- `composables/` — Auto-imported composables (use* prefix)
- `server/api/` — Nitro API endpoints
- `stores/` — Pinia stores

## Coding Conventions
- Composition API with `<script setup lang="ts">` only
- No Options API patterns
- Composables must start with `use` prefix
- Use `defineProps` with TypeScript generics, not runtime declaration
- SSR-safe: check `import.meta.client` before accessing browser APIs

## Development Commands
- `npm run dev` — Start Nuxt dev server
- `npm run build` — Production SSR build
- `npm run generate` — Static site generation

## Important Rules
- NEVER use `this` — Composition API does not have `this`
- NEVER access `window`, `document` without `import.meta.client` guard
- NEVER put business logic in components — extract to composables
- Use `useFetch` or `useAsyncData` for data fetching, never raw `fetch` in setup

Python

Python + FastAPI

# Project: [Name]

## Tech Stack
- Python 3.12+
- FastAPI with Pydantic v2
- SQLAlchemy 2.0 async + Alembic migrations
- PostgreSQL via asyncpg
- pytest for testing
- uv for package management

## Project Structure
- `app/` — Application package
- `app/api/` — Route handlers (routers)
- `app/models/` — SQLAlchemy models
- `app/schemas/` — Pydantic request/response schemas
- `app/services/` — Business logic layer
- `app/core/` — Config, security, dependencies
- `tests/` — Test files mirroring app structure
- `alembic/` — Database migrations

## Coding Conventions
- Type hints on all function signatures
- Pydantic models for all request/response validation
- Async/await everywhere — no sync database calls
- Dependency injection via `Depends()`
- Service layer pattern: routes → services → repositories

## Development Commands
- `uv run fastapi dev` — Start dev server
- `uv run pytest` — Run tests
- `uv run alembic upgrade head` — Apply migrations
- `uv run alembic revision --autogenerate -m "desc"` — Create migration

## Important Rules
- NEVER use raw SQL queries — use SQLAlchemy ORM
- NEVER store secrets in code — use environment variables via pydantic-settings
- NEVER catch broad `Exception` — catch specific exceptions
- Always return Pydantic models from endpoints, never dicts
- All database operations in async context managers

Django 5.x

# Project: [Name]

## Tech Stack
- Django 5.x with Python 3.12+
- Django REST Framework for APIs
- PostgreSQL database
- Celery + Redis for background tasks
- pytest-django for testing

## Project Structure
- `config/` — Django settings, URLs, WSGI/ASGI
- `apps/` — Django applications (one per domain)
- `apps/{name}/models.py` — Database models
- `apps/{name}/views.py` — View logic
- `apps/{name}/serializers.py` — DRF serializers
- `templates/` — Django templates
- `tests/` — Test files

## Coding Conventions
- Class-based views for APIs (ViewSets)
- Model methods for business logic, not views
- Fat models, thin views pattern
- Use `select_related()` and `prefetch_related()` to avoid N+1
- Signals only for cross-app side effects

## Development Commands
- `python manage.py runserver` — Start dev server
- `python manage.py test` — Run tests
- `python manage.py makemigrations` — Create migrations
- `python manage.py migrate` — Apply migrations

## Important Rules
- NEVER write raw SQL unless absolutely necessary
- NEVER put business logic in views or serializers
- NEVER use `Model.objects.all()` without pagination in APIs
- Always use Django's ORM query optimization
- Run `makemigrations` after any model change

Go

Go + Standard Library / Chi

# Project: [Name]

## Tech Stack
- Go 1.23+
- chi router for HTTP
- sqlc for type-safe SQL
- golang-migrate for migrations
- PostgreSQL database
- testify for test assertions

## Project Structure
- `cmd/server/` — Application entrypoint
- `internal/api/` — HTTP handlers
- `internal/service/` — Business logic
- `internal/repository/` — Database access (sqlc generated)
- `internal/model/` — Domain types
- `db/migrations/` — SQL migration files
- `db/queries/` — sqlc query files

## Coding Conventions
- Standard Go project layout (cmd/, internal/, pkg/)
- Accept interfaces, return structs
- Error wrapping with `fmt.Errorf("context: %w", err)`
- Context propagation through all layers
- Table-driven tests
- No global state — dependency injection via structs

## Development Commands
- `go run ./cmd/server` — Start server
- `go test ./...` — Run all tests
- `sqlc generate` — Regenerate from SQL queries
- `migrate -path db/migrations -database $DB_URL up` — Apply migrations

## Important Rules
- NEVER use `panic()` in library code — return errors
- NEVER ignore errors — handle or explicitly comment why
- NEVER use `init()` functions — pass dependencies explicitly
- Always close resources with `defer`
- Always check `context.Done()` in long operations
- Run `go vet` and `golangci-lint` before committing

Rust

Rust + Axum

# Project: [Name]

## Tech Stack
- Rust (latest stable)
- Axum web framework
- SQLx for async database access
- PostgreSQL
- tokio async runtime
- cargo-watch for development

## Project Structure
- `src/main.rs` — Application bootstrap
- `src/routes/` — Axum route handlers
- `src/models/` — Database models and queries
- `src/errors.rs` — Custom error types
- `src/state.rs` — Application state
- `migrations/` — SQLx migrations

## Coding Conventions
- Use `thiserror` for error types, `anyhow` only in main/tests
- Prefer `impl Trait` over `dyn Trait` when possible
- Use `Arc<AppState>` for shared application state
- Extractors for request parsing, not manual deserialization
- Document public APIs with `///` doc comments

## Development Commands
- `cargo watch -x run` — Dev server with hot reload
- `cargo test` — Run tests
- `cargo clippy` — Lint
- `sqlx migrate run` — Apply migrations

## Important Rules
- NEVER use `unwrap()` in production code — use `?` operator
- NEVER clone unnecessarily — prefer references
- NEVER block the async runtime — use `tokio::task::spawn_blocking`
- Always handle all match arms explicitly
- Run `cargo clippy` before every commit

Browse More Templates

These are just starting points. The community has created templates for dozens more frameworks and use cases:

• Browse all CLAUDE.md templates on TokRepo — 50+ searchable, downloadable templates
• Ruby on Rails, Laravel, Spring Boot, .NET, Flutter, Swift, and more
• Specialized templates for monorepos, microservices, and full-stack apps

Best Practices for Writing CLAUDE.md

1. Be Specific About Constraints

## Bad
- Follow best practices

## Good
- Use `const` for all variable declarations unless reassignment is needed
- Maximum function length: 30 lines
- Every exported function must have a JSDoc comment

2. Include Actual Commands

## Bad
- Run the tests before committing

## Good
- Run `npm test` before committing
- Run `npm run lint:fix` to auto-fix style issues
- Run `npm run typecheck` to verify TypeScript types

3. Document Architecture Decisions

## Why We Use X
We chose Zustand over Redux because:
- Simpler API, less boilerplate
- Better TypeScript support out of the box
- No need for middleware in our use case

4. Keep It Under 500 Lines

Claude Code reads CLAUDE.md into its context window. A 2,000-line file wastes tokens on information Claude may not need. Keep it focused on conventions and constraints.

FAQ

Q: What is CLAUDE.md? A: A markdown configuration file placed in your project root that tells Claude Code how to work with your codebase — coding conventions, project structure, development commands, and important constraints.

Q: Do I need a CLAUDE.md file? A: No, Claude Code works without one. But adding a CLAUDE.md significantly improves code quality by teaching Claude your project's specific patterns and constraints.

Q: Where should I put CLAUDE.md? A: In your project root directory (next to package.json, go.mod, etc.). Claude Code automatically reads it at session start.

Q: Can I use the same CLAUDE.md for Cursor? A: The content is transferable — save it as .cursorrules for Cursor, AGENTS.md for Codex CLI, or GEMINI.md for Gemini CLI. The format is nearly identical.

Next Steps

• Browse CLAUDE.md templates on TokRepo — find one for your framework
• How to Create Your First Agent Skill — go beyond CLAUDE.md with reusable skills
• What Are Claude Code Skills? — understand the full extension model
• Skills vs MCP vs Rules — when to use CLAUDE.md vs skills vs MCP
• Codex CLI vs Claude Code — choose the right AI coding tool