How to write the perfect CLAUDE.md (with examples for every stack)

You install Claude Code. You open a project. You ask it to build something. And the output is... fine. Generic. It uses the wrong naming convention, picks a testing library you don't use, and structures the code in a way that doesn't match your codebase.

The fix is a CLAUDE.md file. It's the single biggest lever you have for improving Claude Code's output quality. But most people either skip it or write one that doesn't actually help.

This guide covers exactly what to include, what to skip, and how to structure it for maximum impact. If you want to skip the reading and generate one instantly, use our free CLAUDE.md generator - it takes 30 seconds.

What is a CLAUDE.md file?

CLAUDE.md is a markdown file in your project root that Claude Code reads at the start of every session. Think of it as a project brief for your AI coding assistant. It tells Claude:

• What tech stack you're using
• How your code is organized
• Your coding conventions and style preferences
• How to test and lint your code
• What to avoid doing

Without it, Claude makes reasonable guesses. With a good one, Claude writes code that actually fits your project.

The 5 sections every CLAUDE.md needs

After working with CLAUDE.md files across dozens of projects, these are the sections that consistently improve output quality. In order of impact:

1. Project overview (3-5 lines)

Keep it short. Claude doesn't need your product roadmap. It needs to know what it's working with.

## Project Overview

This is a Next.js 14 web application using the App Router, Tailwind CSS,
and Supabase for auth and database. It's a B2B SaaS dashboard for
managing inventory across multiple warehouses.

Why this works: Claude immediately knows the framework version (App Router, not Pages), the styling approach (Tailwind, don't generate CSS modules), and the domain (inventory management, use relevant terminology).

2. Code conventions (the highest-impact section)

This is where most CLAUDE.md files fail. They either include nothing, or they paste in their entire ESLint config. Neither helps.

Focus on the conventions that Claude gets wrong without guidance:

## Code Style & Conventions

- Only add comments where the logic is not self-evident
- No premature abstractions - three similar lines is better than a helper function
- Handle errors at system boundaries, not inside internal functions
- Use strict TypeScript everywhere, no `any` type
- Prefer named exports over default exports
- File naming: kebab-case for files, PascalCase for components
- Import order: external deps, then internal, then relative

Each rule here directly changes Claude's behavior. Without "no premature abstractions," Claude creates utility functions for everything. Without "strict TypeScript," you get any sprinkled everywhere.

3. Testing setup

## Testing

- Framework: Vitest
- Run tests: `npx vitest`
- Test files go next to source files (e.g., `user-service.test.ts`)
- Prefer integration tests for API routes
- Use descriptive test names: "should return 404 when user not found"

Without this, Claude might use Jest syntax in a Vitest project, put tests in a separate __tests__ directory when you co-locate them, or write unit tests when you want integration tests.

4. File structure

## File Structure

```
src/
  app/          # Next.js App Router pages
  components/   # Reusable UI components
  lib/          # Business logic and utilities
  hooks/        # Custom React hooks
  types/        # Shared TypeScript types
```

This prevents Claude from creating new directories that don't match your structure. It also helps Claude find existing code instead of reimplementing something that already exists in lib/.

5. Important notes (things to avoid)

## Important Notes

- Read existing code before suggesting modifications
- Prefer editing existing files over creating new ones
- Do not add features or refactoring beyond what was asked
- Use App Router patterns (server components by default)
- Database migrations go in supabase/migrations/

These "negative instructions" are surprisingly effective. "Do not add features beyond what was asked" stops Claude from adding error handling, logging, and type annotations to code you didn't ask it to touch.

Common mistakes that waste tokens

Including your entire README

Claude reads your CLAUDE.md every single session. Every line costs tokens. A 500-line CLAUDE.md that includes installation instructions, contribution guidelines, and deployment docs wastes tokens on information Claude rarely needs.

Rule of thumb: if a section doesn't change Claude's coding behavior, remove it.

Being too vague

"Write clean code" tells Claude nothing. "Use named exports, kebab-case file names, and co-locate test files" tells Claude exactly what to do. Every rule should be specific enough that you could check whether Claude followed it.

Duplicating what Claude already knows

You don't need to explain how React hooks work or what TypeScript generics are. Claude knows. Focus on your project-specific conventions that Claude can't infer from the code alone.

Real examples by stack

React + TypeScript (Next.js)

# Project Configuration

## Overview
Next.js 14 App Router, TypeScript strict, Tailwind CSS, Supabase.

## Conventions
- Server Components by default, "use client" only when needed
- Use Tailwind classes, never inline styles or CSS modules
- Strict TypeScript, no `any`
- Named exports only
- Use `cn()` from lib/utils for conditional classes

## Testing
- Vitest + Testing Library
- Run: `npx vitest`
- Co-locate tests next to source files

## File Structure
```
src/app/       # Pages and layouts
src/components # UI components
src/lib/       # Business logic
src/hooks/     # Custom hooks
```

Python (FastAPI)

# Project Configuration

## Overview
FastAPI backend with SQLAlchemy ORM and Alembic migrations. PostgreSQL database.

## Conventions
- Type hints on all function signatures
- Pydantic models for request/response validation
- Use dependency injection for database sessions
- Handle errors with HTTPException, not generic try/catch
- No print() for debugging, use structured logging

## Testing
- pytest with httpx for async tests
- Run: `pytest -v`
- Test files in tests/ mirroring src/ structure

## File Structure
```
app/
  routers/    # Route handlers
  models/     # SQLAlchemy models
  schemas/    # Pydantic schemas
  services/   # Business logic
  deps.py     # Dependency injection
```

Go (API server)

# Project Configuration

## Overview
Go REST API using standard library net/http and sqlx for database access.

## Conventions
- Follow Go conventions: short variable names, error returns
- Handle every error explicitly, no blank identifier
- Use context.Context for request-scoped values
- Interfaces in the consuming package, not the implementing package
- No global state, pass dependencies through constructors

## Testing
- go test with table-driven tests
- Run: `go test ./...`
- Test files next to source (*_test.go)

## File Structure
```
cmd/server/    # Entry point
internal/
  handler/     # HTTP handlers
  service/     # Business logic
  store/       # Database access
  model/       # Data types
```

Advanced: multi-tool configuration

If your team uses different AI coding tools, you need different config files. CLAUDE.md is for Claude Code. Cursor reads .cursorrules. GitHub Copilot reads AGENTS.md. Gemini CLI reads GEMINI.md.

The core rules are the same across tools - your conventions don't change because you switched editors. But the format and some tool-specific features differ.

ContextKit's free generator exports to all four formats from a single configuration. Answer the questions once, export for each tool your team uses.

Generate yours in 30 seconds

Writing a CLAUDE.md from scratch works, but you'll miss best practices that come from seeing hundreds of configurations. Our free generator includes 40+ proven rules, stack-specific templates, and multi-tool export.

Try the free ContextKit generator - no signup, runs in your browser, copy to clipboard in one click.

If you want to go deeper into building a complete AI-powered development workflow around Claude Code, check out the AI OS Blueprint - it covers the full system architecture including CLAUDE.md, skills, memory, and task automation.