CLAUDE.md: The Configuration File That Supercharges Claude Code

Updated April 2026 · 10 min read

If you use Claude Code without a CLAUDE.md file, you're leaving 50% of its power on the table. This file is how you teach Claude your project's conventions, commands, and gotchas — so it produces better code from the very first message. Here's everything we've learned from months of daily use.

📋 What is CLAUDE.md?

CLAUDE.md is a markdown file you place in your project root. Claude Code reads it at the start of every session, loading your instructions into its context. Think of it as onboarding documentation for your AI assistant.

📐 The Ideal Structure

Keep it under 150 lines. Every line costs attention — if Claude would figure it out from the code alone, don't include it.

# CLAUDE.md — Keep it under 150 lines

## Project Overview
One line: tech stack + what it does

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

## Architecture
- Where code lives (src/routes/, src/models/)
- Key patterns (repository pattern, CQRS, etc.)

## Conventions
- Coding style (functional, async/await)
- Naming (camelCase for variables, PascalCase for components)
- Error handling approach

## Gotchas
- Things that aren't obvious from the code
- "Run migrations before testing"
- "The auth module must be imported first"

✅ Best Practices

• Be positive, not negative. Write "use async/await" not "don't use callbacks". Positive instructions are followed more reliably.
• Include test commands. Claude can run tests and fix failures — but only if it knows the command.
• Document non-obvious dependencies. "Must run `npm run generate` after changing the schema" saves hours of confusion.
• Keep it updated. When Claude makes a mistake, add a line to prevent it. Tell Claude: "Update CLAUDE.md so this doesn't happen again."
• Use progressive disclosure. Put task-specific rules in separate files (.claude/rules/) for larger projects.

❌ Common Mistakes

• Too long (>200 lines). LLMs lose compliance beyond ~150-200 instructions. Less is more.
• Stating the obvious. "Use good variable names" wastes a line — Claude already does this from code context.
• Generic advice. "Write clean code" doesn't help. "Use the repository pattern for all database access" does.
• No build/test commands. Without these, Claude can't verify its own work.
• Negatives. "Don't use var" is weaker than "Use const and let for all declarations".

📝 Real Example

# CLAUDE.md — Production SaaS App

## Project
Next.js 15 + TypeScript + Prisma + PostgreSQL
SaaS tool for project management with real-time collaboration

## Commands
- Dev: `npm run dev` (port 3000)
- Build: `npm run build`
- Test: `npm test`
- Test single: `npx jest src/__tests__/filename.test.ts`
- Migrate: `npx prisma migrate dev`
- Generate client: `npx prisma generate`

## Structure
- `src/app/` — Next.js App Router pages
- `src/components/` — React components (shadcn/ui)
- `src/lib/` — Utilities and shared logic
- `src/server/` — API route handlers
- `prisma/` — Database schema and migrations

## Conventions
- Server components by default, client only when needed
- Use Zod for all API input validation
- All database queries through Prisma
- Error responses: { error: string, code: string }
- Auth: check `session` from `getServerSession()`

## Important
- Always run `npx prisma generate` after schema changes
- The realtime module uses WebSockets via Socket.io
- Rate limiting is in `src/middleware.ts`
- Environment variables are validated in `src/env.ts`

🔧 Advanced: Multiple CLAUDE.md Files

For monorepos or large projects, use hierarchical CLAUDE.md files:

• • Root CLAUDE.md — Global rules and project overview
• • packages/frontend/CLAUDE.md — Frontend-specific rules
• • packages/backend/CLAUDE.md — Backend-specific rules
• • .claude/rules/typescript.md — TypeScript-specific conventions

Claude Code loads all applicable CLAUDE.md files based on where you start it. This keeps context focused on the relevant part of your project.