🎯

This chapter teaches you how to create and grow the most important file in your entire setup. If you only remember one thing from this guide, make it this one. Reading time: 10 minutes.

The problem it solves

Without CLAUDE.md, every new conversation with Claude Code is like hiring a new developer on a Monday morning:

They know nothing about your project
They don't know which technologies you use
They don't know your code conventions
They don't know where to put files
They'll ask you 50 questions before getting started
They'll make random choices that end up inconsistent from one session to the next

Result: you spend 10-15 minutes per session re-explaining the same things. Multiply by 10 sessions a day, and you lose 2 hours of pure productivity.

The solution

CLAUDE.md is a text file placed at the root of your project that Claude Code reads automatically at the start of every conversation. It's your permanent brief.

Think of it as an onboarding doc for a new developer covering: the tech stack, code conventions, project architecture, useful commands, pitfalls to avoid, business vocabulary. Except instead of reading it once and forgetting it, Claude rereads it instantly at every session.

⚡

Real impact: with a good CLAUDE.md, Claude produces consistent code from the very first reply. The return on investment is immediate, 30 minutes of writing that save dozens of minutes on every dev day.

How to create it

You don't write it from scratch yourself. You ask Claude to generate it, then you enrich it.

Step 1, initial generation

If you're starting a new project, give Claude the context:

"I'm going to build a SaaS for [description]. The stack will be Next.js + Supabase + Stripe. The interface will be in English. Generate a complete CLAUDE.md with conventions, architecture, commands, and pitfalls to avoid."

If you already have an existing project:

"Analyze this project and generate a complete CLAUDE.md. Explore the architecture, the conventions in use, the tech stack, and document everything a developer should know to be productive immediately."

Claude will explore all your files and produce a tailored CLAUDE.md.

Step 2, enrichment over time

For every important decision, add it to CLAUDE.md:

New convention, add it under "Code style"
Pitfall encountered, add it under "Gotchas"
New technology, add it under "Stack"
New business concept, add it under "Concepts"

"Add to CLAUDE.md that we now use Resend for emails, and that we must never send more than 3,000 emails per month on the free plan."

The 8 essential sections

1. Project description

A single sentence saying what it is and who it's for.

# MyApp - SaaS project management for freelancers

Claude uses this line to understand the business context of every decision.

2. Commands

How to run the app, the tests, the database. Claude uses these to verify its own work automatically.

## Commands
- npm run dev → Run the app on localhost:3000
- npm run build → Production build
- npm run typecheck → TypeScript type check
- npm run lint → Code style check
- npm run test → Run tests
- npx supabase migration up --local → Apply migrations

💡

Why this is crucial: when Claude modifies code, it runs typecheck and lint to verify everything is correct. Without these commands in CLAUDE.md, it doesn't know what to run.

3. Tech stack

The technologies you use. Claude adapts its code accordingly.

## Stack
- Next.js 16 App Router, TypeScript strict, React 19
- Supabase (PostgreSQL, Auth, RLS, Storage)
- shadcn/ui + Tailwind CSS
- Stripe for payments
- Resend for emails

4. File architecture

Where each type of file goes. Without this, Claude creates files anywhere and your project becomes a mess.

## Architecture
- src/app/ → Pages and layouts (App Router)
- src/components/ → Reusable components
- src/lib/actions/ → Server-side business logic (Server Actions)
- src/lib/validators/ → Validation schemas (Zod)
- supabase/migrations/ → SQL migrations

5. Code style

Naming and writing conventions. Guarantees consistency across all sessions.

## Code style
- Files in kebab-case (e.g. brand-profile.tsx)
- No default exports
- Server Components by default, 'use client' only when necessary
- Prefer Server Actions over API routes for mutations

6. Color palette

If your app has a defined visual identity, document it. Otherwise Claude will use random colors.

## Palette
- Primary: #E8634A (coral) - buttons, active links
- Background: #FFFBF7 (ivory) - page background
- NEVER use colors outside the palette

7. Business concepts

The vocabulary specific to your app. Claude uses it in code, variable names, and the interface.

## Concepts
- "Streak": number of consecutive weeks of publishing
- "Capsule": video/audio recording repurposed in multi-format
- "Compass": matrix of pillars x categories x content goals

8. Gotchas (pitfalls to avoid)

The mistakes that waste time. Claude avoids them proactively.

## Gotchas
- NEVER use `supabase db reset` (destroys all data)
- AI API keys: always server-side, NEVER expose client-side
- Interface in French with correct accents (é, è, ê, à, ç)
- The Supabase server client uses cookies() - do not cache it

Real example, excerpt from Panettone's CLAUDE.md

Here's a real excerpt from the CLAUDE.md used to build a complete personal branding SaaS in less than a week:

# Panettone - Personal Branding SaaS for Freelancers

## Commands
- npm run dev → Next.js dev on localhost:3000
- npm run typecheck → TypeScript check
- npx supabase migration up --local → Apply migrations

## Stack
- Next.js 16 App Router, TypeScript strict, React 19
- Supabase (PostgreSQL, Auth, RLS, Storage)
- shadcn/ui + Tailwind CSS 4
- Stripe (Freemium + Pro)
- Anthropic Claude API for AI
- Resend for emails

## Palette - "Dolce Vita"
- Primary (Soft Coral): #E8634A - CTAs, active elements
- Background (Ivory): #FFFBF7 - page background
- NEVER use colors outside the palette

## Gotchas
- NEVER supabase db reset (destroys data)
- Claude API: always server-side
- Interface in French with correct accents

How to evolve it

CLAUDE.md is not set in stone. It needs to evolve with your project:

When	What to add	Example prompt
New tech added	Add it under Stack	"Add Resend to `CLAUDE.md`, Stack section"
Recurring bug solved	Add it under Gotchas	"Add to Gotchas: never use redirect() inside a try/catch"
New convention decided	Add it under Code style	"Add: all forms use react-hook-form + Zod"
New business concept	Add it under Concepts	"Add the 'Brand score' concept to `CLAUDE.md`"

⚠️

Pitfall: don't let CLAUDE.md get too long (more than 200 lines). Ideally, aim for 60 to 100 lines. Beyond that, Claude starts ignoring instructions, even ones in capital MUSTs. It's a phenomenon documented by the community.

Splitting with .claude/rules/ (for big projects)

When your CLAUDE.md grows too large, the answer isn't to dump everything into docs/. Claude Code has a dedicated mechanism: the .claude/rules/ folder.

The principle

Each .md file in .claude/rules/ is a specialized rule that Claude loads automatically based on context. It's like splitting your CLAUDE.md into thematic chapters.

.claude/rules/
  safety.md       → What is FORBIDDEN (rm -rf, sudo, db reset)
  supabase.md     → Required Supabase patterns
  nextjs.md       → Next.js conventions
  changelog.md    → Update CHANGELOG after every change

Why it's better than one big CLAUDE.md

Contextual loading: Claude loads the relevant rules at the moment it needs them, not all at once
Easy maintenance: each rule is independent, you can add or modify one without touching the others
No line limit: CLAUDE.md stays short (60-100 lines), the details live in the rules

Global and project levels

Rules exist at two levels:

~/.claude/rules/ (global): loaded in ALL your projects. Ideal for personal preferences (safety, style, tools)
.claude/rules/ (project): loaded only in this project. Ideal for project-specific conventions (DB schema, roadmap, business patterns)

💡

Best practice (Boris Cherny, creator of Claude Code): CLAUDE.md < 100 lines for the essential conventions. .claude/rules/ for everything else. Don't go beyond 6-7 rule files so you don't dilute the model's attention.

💡

Takeaway: CLAUDE.md is your #1 investment. 30 minutes of writing → hours saved on every dev day. Create it from the start of your project and enrich it with every important decision.

🎯