Claude Code CLAUDE.md: Documentation That Codes With You

Every project has its specifics. Its conventions. Its pitfalls. Its “we’ve always done it this way” that no one has ever documented.

The CLAUDE.md file is where you capture all of this so Claude Code works like you — not like a generic developer discovering the project.

CLAUDE.md vs README.md

README.md	CLAUDE.md
For humans	For Claude Code
How to install the project	How to work in the project
General technical stack	Specific conventions and patterns
Read once, rarely revisited	Loaded automatically every session

The README explains what the project is. CLAUDE.md explains how to contribute to it.

Where to place CLAUDE.md

Two options:

1. At project root: ./CLAUDE.md — for repo-specific conventions
2. Global: ~/.claude/CLAUDE.md — for your personal preferences (language, tools, workflow)

Both are loaded automatically. Local overrides global in case of conflict.

The structure that works

After testing different configurations across several projects, here’s the optimal structure:

# CLAUDE.md — Project Name

## Language
- Conversations: French
- Code & Commits: English

## Stack
- Framework: Next.js 15
- Database: PostgreSQL + Prisma
- Testing: Vitest + Playwright
- Styling: Tailwind CSS

## Commands
- Dev: `bun dev`
- Test: `bun test`
- Build: `bun run build`
- Lint: `bun run lint`

## Conventions

### Code Style
- Imports: sorted alphabetically
- Components: one file = one component exported by default
- Types: interfaces preferred over types

### Naming
- Components: PascalCase
- Functions: camelCase
- Files: kebab-case
- Constants: SCREAMING_SNAKE_CASE

### Git
- Branches: feat/fix/refactor/docs/test/chore
- Commits: conventional commits

## Architecture

### Key Files
- `src/app/` — App Router pages
- `src/components/` — Reusable components
- `src/lib/` — Utilities and helpers
- `src/types/` — Shared TypeScript types

### Patterns
- Server Components by default
- Client Components only when necessary (useState, useEffect)
- Actions in `src/actions/`

## Known Pitfalls
- Don't modify `src/lib/db.ts` directly
- Always use `cn()` for conditional classes
- E2E tests need DB running

## Business Context
This project is an invoicing SaaS for freelancers.
Terms:
- "Invoice" = Client invoice
- "Quote" = Quote/estimate
- "Expense" = Business expense

Essential sections

1. Language — MANDATORY

## Language
- Conversations: French
- Code & Commits: English

Claude Code speaks your conversation language but writes code and commits in English. This is the optimal setup for French-speaking teams.

2. Stack — For technical decisions

## Stack
- Runtime: Bun
- Framework: Hono.js
- ORM: Drizzle
- Auth: Better Auth

Claude uses this info to propose solutions coherent with your stack.

3. Commands — So you don’t have to search

## Commands
- Dev: `bun dev`
- Test: `bun test`
- DB Push: `bunx prisma db push`
- DB Generate: `bunx prisma generate`

When you ask “run tests”, Claude knows exactly what to execute.

4. Conventions — For consistency

## Conventions

### Code Style
- No `console.log` in production
- Imports sorted by type (React, external, internal)
- Components: arrow functions

### Git
- Never force push to main
- Always create a branch for features
- Commits: feat/fix/refactor/docs/test/chore

5. Known Pitfalls — To avoid classic mistakes

## Known Pitfalls
- Auth middleware breaks if not in specific order
- `useSearchParams()` requires Suspense boundary
- Tests need `DATABASE_URL` in env
- Don't use `fetch()` server-side, use `serverFetch()`

This is the most valuable section. You capture hours of debugging in 5 lines.

6. Business Context — For specific terms

## Business Context
Restaurant management application.

Terms:
- "Table" = Physical table (not DB table)
- "Service" = Lunch/dinner service
- "Couvert" = Number of guests
- "Ticket" = Current order

Business Rules:
- A closed service can no longer receive orders
- Tickets must be closed before closing

Anti-patterns to avoid

Too verbose

## Architecture

Our architecture is based on Clean Architecture principles
popularized by Robert C. Martin. We use a layer separation
with the dependency rule which states that dependencies
can only point inward...

Claude doesn’t need an architecture course. Give him facts.

Too generic

## Conventions
- Write clean code
- Follow best practices
- Use meaningful variable names

This adds nothing. Be specific to your project.

Not maintained

An outdated CLAUDE.md is worse than no CLAUDE.md. If you change conventions, update it.

Real examples

Next.js + Prisma project

# CLAUDE.md — SaaS Dashboard

## Language
- Conversations: French
- Code & Commits: English

## Stack
- Next.js 15 (App Router)
- PostgreSQL + Prisma
- Auth: Better Auth
- UI: shadcn/ui + Tailwind

## Commands
- Dev: `bun dev`
- Test: `bun test`
- DB: `bunx prisma db push && bunx prisma generate`
- Build: `bun run build` (ask confirmation)

## Conventions
- Server Components by default
- 'use client' only when necessary
- Actions in `src/actions/`
- Types in `src/types/`

## Known Pitfalls
- Don't modify `prisma/schema.prisma` without `bunx prisma generate`
- Server Actions must be async
- Middleware must match public routes

Symfony + Vue project

# CLAUDE.md — E-commerce Platform

## Language
- Conversations: French
- Code & Commits: English

## Stack
- Backend: Symfony 7 + API Platform
- Frontend: Vue 3 + Inertia.js
- Database: PostgreSQL
- Queue: RabbitMQ

## Commands
- Backend: `symfony server:start`
- Frontend: `bun dev`
- Tests: `php bin/phpunit`
- Queue: `php bin/console messenger:consume`

## Conventions
- API Platform resources in `src/Entity/`
- Vue components in `resources/js/components/`
- Tests: one class = one test file

## Known Pitfalls
- Redis cache to clear after API Platform changes
- Inertia shares props via middleware
- Functional tests need test DB

Automatic rules (Auto-Loaded)

Claude Code automatically loads certain rule files:

File	Trigger
rules/glm-delegator/glm-delegator.md	Expert routing
rules/planning/planning.md	Complex tasks
rules/agent-teams/agent-teams.md	2+ parallel agents

You can create your own auto-loaded rules in ~/.claude/rules/.

Maintenance workflow

1. Project start: Create a minimal CLAUDE.md
2. After encountering a pitfall: Add it to “Known Pitfalls”
3. After a convention change: Update “Conventions”
4. Monthly review: Remove what’s no longer relevant

What this actually changes

Without CLAUDE.md:

• Claude proposes generic solutions
• You repeat the same corrections
• Classic mistakes repeat

With CLAUDE.md:

• Claude follows your conventions from the start
• Architecture decisions are respected
• Known pitfalls are automatically avoided

The time invested in a good CLAUDE.md is recovered after 2-3 work sessions. It’s the highest ROI of anything you can configure in Claude Code.