What is CLAUDE.md and what goes in it
CLAUDE.md is a text file with instructions about your project that Claude Code reads on its own at the start of every conversation. You write down once what it should always know (the key commands, the style, what's off limits), so you don't have to repeat it every day.
In short: CLAUDE.md is your project's memory. Below you'll learn why you need it, what to put in it and what to leave out, where it lives, how to create it in ten seconds and what a good example looks like.
Why do you need a CLAUDE.md file?
Because every new conversation with Claude Code starts from zero. Claude doesn't remember what you told it yesterday. Without CLAUDE.md, the next day it asks you again about things you've already told it, or it guesses. With CLAUDE.md, it knows from the start.
The official documentation says the same: each session begins with an empty context, and CLAUDE.md files are how you give it instructions that carry over from one day to the next (memory in Claude Code, checked on 7 October 2026).
Think of a note stuck on the fridge for someone looking after your home while you're away: "water the plants on Tuesday, no chocolate for the dog". The person is capable, but can't guess the rules of your house. And the note has to be short: nobody reads 30 pages.
What goes in CLAUDE.md?
Only what Claude should know in every conversation and couldn't work out from the files on its own:
- The commands that start and check the project.
- How the project is organized, in a few lines.
- The style: rules no automatic tool catches ("all text is in English, with proper punctuation").
- What's off limits: what it must not touch ("don't change prices without asking me").
A good sign a rule belongs there: you've told Claude twice. The official documentation recommends exactly that: add to CLAUDE.md whatever you find yourself explaining again.
Write concrete rules you can check. "Only use the index.html file" works better than "keep things organized".
What should you leave out of CLAUDE.md?
Leave out things that are obvious from the files, long explanations and the project's history. Every line is read at every start, so a long file costs more and confuses it.
The official documentation recommends staying under 200 lines per file. Longer files take up more of the conversation's memory and are followed less reliably. If two rules contradict each other, Claude may pick either one, so reread the file now and then and remove what's no longer true.
One more important thing: CLAUDE.md is advice, not a lock. Claude reads it and tries to follow it, but the program doesn't enforce it. For "never allowed", there are permissions, covered in module 03 of the course.
Where does the CLAUDE.md file live?
In the project folder, as CLAUDE.md. Next to it, you can also have:
- a personal one for all your projects:
~/.claude/CLAUDE.md(for example "always answer me in Spanish"); - one just for you inside the project:
CLAUDE.local.md, which you don't share with colleagues.
They all add up: Claude reads all of them at startup. To see which files it read, type /context in Claude Code and look at the list of memory files.
If your project already has an AGENTS.md file for other AI agents, Claude Code can read that one too. Details in the official documentation.
How do you create a CLAUDE.md in 10 seconds?
In Claude Code, type:
/init
Claude looks through the project and writes a first version of CLAUDE.md on its own, with the commands and habits it finds. If the file already exists, it suggests improvements instead of rewriting it. See also /init in the glossary.
To add a rule later, just tell it: "add this rule to CLAUDE.md: always answer me in plain English". It writes it into the file and shows you the change.
What does a good CLAUDE.md look like?
Short, concrete and specific to your project. Here's one for a cafe's website:
# The cafe's website
- The page is a single file: index.html. No libraries.
- All text is in English, written for customers, not developers.
- Don't change the phone number or address without asking me.
- After every change, open the page and check it at phone width.
Four lines. Each one says something Claude wouldn't know on its own or might break. Don't write "make a nice site" or "write good code": those don't help, because it already tries.
A bad example, to show the difference: a 300-line file that tells the story of how the cafe started, copies the whole menu and repeats "be careful" three times. Claude reads it at every start and loses sight of the rules that matter.
How is CLAUDE.md different from auto memory?
You write CLAUDE.md; Claude writes auto memory. The official documentation describes two systems that complement each other: CLAUDE.md holds instructions and rules, while auto memory keeps what Claude learns from your corrections. Both are read at the start of every conversation.
The simple rule: anything you want followed for sure, write it yourself in CLAUDE.md.
Frequently asked questions
Do I have to write CLAUDE.md in English?
No. You can write it in your own language. What matters is that it's clear and short.
What happens if I don't have a CLAUDE.md?
Claude Code works without it. You'll just have to repeat the project's rules in every conversation.
How often should I update it?
Whenever you notice you're repeating the same correction. And when a rule is no longer true, delete it.
Can I have more than one CLAUDE.md file?
Yes: a personal one, one for the project and a local one that's just yours. Claude reads all of them.
Learn it step by step
CLAUDE.md is module 02 of the "Claude Code for Beginners" course: where the file can live, how to keep it short, a complete example and a lab where you write one for your own project. The first two modules of the course are free; you'll also find the term in the glossary. If you're just starting, begin with the Claude Code tutorial or the whole course.