Without a CLAUDE.md, you explain your project all over again every session.
Here, you get Claude to write it with one command, then you learn what to keep
in it.
The problem
Every new session with Claude Code is like a new coworker showing up on Monday morning. They know nothing about your project or your habits. They ask questions, and their choices change from one session to the next.
The result: you spend 10 to 15 minutes per session repeating the same things. At 10 sessions a day, that's 2 hours gone.
An instructions file
A text file that lives in your project. Claude Code reads it on its own at the start of every session and keeps it in front of it until the end. You put in it what it always needs to know: what the project is for, which tools it's built with, your rules, the pitfalls you've already run into.
It exists in two places:
- In your project: this project's instructions. That's the one we build in this chapter.
- In your home folder (
~/.claude/CLAUDE.md): preferences that apply everywhere, for example "keep your answers short".
Plan on half an hour to get your CLAUDE.md right. After that, no more
reminders at the start of a session: Claude writes in the right style from its
first answer.
Create it with one command
You don't write it yourself. In the conversation, type:
/init
Claude goes through your project, spots the tools in use and the useful commands, then writes a starter CLAUDE.md. You read it over and add what it can't guess: who your app is for, your vocabulary, your rules.
If your folder is still empty, /init has nothing to read. Give it the context instead:
"I'm going to build a [description] app for [who]. The interface will be in English. Write a
CLAUDE.mdwith the conventions, how the files are organized, the commands and the pitfalls to avoid."
What goes in it
Eight sections cover the essentials. /init fills in some of them, and you complete the rest as the project moves along.
| Section | What you put in it | Example |
|---|---|---|
| Description | What the project does, and for whom | "Booking app for a hair salon" |
| Commands | How to run the app and check it | npm run dev runs the app on localhost:3000 |
| Stack | The tools the app is built with | Next.js, Supabase for the database, Stripe |
| Organization | Where each type of file goes | "Pages in src/app, components in src/components" |
| Style | Your coding conventions | "Lowercase file names with hyphens" |
| Palette | Your colors and what they're for | "Coral #E8634A for buttons, nothing outside the palette" |
| Vocabulary | The words specific to your business | "A 'service' = something a client can book" |
| Pitfalls | Mistakes you've already hit, so you don't repeat them | "Always keep API keys server-side" |
The commands are essential: they're how Claude knows how to check its own work. Without them, it doesn't know what to run.
Pitfalls is the section that pays off the most. Every mistake that cost you an hour, you write down once, and Claude doesn't make it again.
A real example: Panettone
I built Panettone, my personal branding SaaS for freelancers, in under a week. Here's an excerpt from the CLAUDE.md that ran behind it:
# Panettone - SaaS Personal Branding pour Freelances
## Commandes
- npm run dev → Next.js dev sur localhost:3000
- npm run typecheck → Vérification TypeScript
- npx supabase migration up --local → Appliquer les 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 pour l'IA
- Resend pour les emails
## Palette - "Dolce Vita"
- Primary (Corail doux): #E8634A - CTAs, éléments actifs
- Background (Ivoire): #FFFBF7 - fond de page
- Ne JAMAIS utiliser de couleurs hors palette
## Gotchas
- JAMAIS supabase db reset (détruit les données)
- Claude API : toujours côté serveur
- Interface en français avec accents corrects
You don't need to understand every line. Look at the shape: headings, then short lists of clear rules.
Keeping it up to date
The CLAUDE.md grows with your project. Every time you make an important decision, ask Claude to add it to the right section:
| When | Example request |
|---|---|
| You add a tool | "Add Resend to the CLAUDE.md, Stack section" |
| A bug keeps coming back | "Add to Pitfalls: never use redirect() inside a try/catch" |
| You settle on a rule | "Add: every form shows its errors under the field" |
| A business term shows up | "Add the 'Brand score' concept to the CLAUDE.md" |
It's just a text file: you can also open it and edit it yourself.
When the change kicks in. This one often surprises people: you add a rule mid-session, and Claude carries on as before. That's normal, it read the file at startup. The new rule applies from the next session (or after /clear, which empties the conversation). If it matters right now, restate it in your message.
Keep it short. The official docs recommend staying under 200 lines. I aim for 60 to 100. Beyond that, Claude follows the instructions less reliably, even when they're in capital letters. And the whole file is sent to the model again with every message, so it takes up room for the entire session.
When it gets too long
Once your file goes past a hundred lines or so, there are two places to move things:
- Rules: rule files by topic (database, design, security), stored in
.claude/rules/. A rule can load only when Claude touches certain files. - Skills: long procedures (deploying, publishing a release) that Claude only loads when the task calls for them. You create one in chapter 8.
No need to do it all by hand: "My CLAUDE.md is too long. Move everything that's only about the database into a rule, and suggest what could become a skill."
For later: the finer settings
Load a rule only for certain files. Add a paths: header at the top of the rule file:
---
paths:
- "supabase/**"
- "src/lib/actions/**"
---
# Supabase rules
- Always enable RLS on a new table
- Regenerate the types after every migration
These rules only enter the context when Claude touches the listed files, here the database and the code that calls it. A design session doesn't load them. Without paths:, a rule loads at startup, like the CLAUDE.md. Rules also exist at the global level, in ~/.claude/rules/.
Import another file. A line @docs/architecture.md in the CLAUDE.md pulls that file in. It keeps things tidy, but the imported file still loads at startup, like everything else.
Compaction instructions. When a conversation gets long, Claude Code summarizes it to free up room (chapter 6). A Compact instructions section tells it what to keep:
## Compact instructions
- Keep the list of modified files and architecture decisions
- Keep the test commands that are still failing
- Drop log output and abandoned leads
Cleaning up. /doctor prompt-audit goes through your CLAUDE.md files, rules and skills, and flags instructions written for older models.
An AGENTS.md in the project? That's the instructions file other coding agents use. Claude Code reads it when there's no CLAUDE.md (chapter 10).
Question
Mid-session, you ask Claude to add a rule to your CLAUDE.md. It does. When does the rule apply?
Pick an answer to see the explanation.
Key takeaways
- Run
/initfrom the start, then ask Claude to add every important decision. - Under 200 lines (I aim for 60 to 100). Whatever isn't needed for every message goes into rules or skills.
- A rule added mid-session applies from the next session.
End-of-part quiz
Part 1: Getting started
6 questions. You pass the part with 5 correct answers or more.