CLAUDE.md: The Notes It Reads the Moment It Walks In

In short

CLAUDE.md is a text file Claude reads at the start of every session.
It's there so you stop repeating the same things: it's the notes pinned up in the studio.
It can live in the project (and applies there) or among your own stuff (and applies everywhere). They're not mutually exclusive: they stack.
With /init it proposes one by looking at your folder.

The problem it solves

You already know the model has no memory and every session starts from a blank page. In practice, that turns into one specific annoyance: every single time you have to re-explain the same four things. How your files are organized, what you want them named, what shouldn't be touched, what the client is called.

The solution is obvious, and that's exactly why it's brilliant: leave them written down. A text file, in the working folder, that it reads the moment it walks in — before you even open your mouth.

It's called CLAUDE.md. It's the equivalent of the notes you'd leave pinned up in the studio for a collaborator who shows up every morning remembering nothing from the day before.

Where to put it, and what changes

In the project — a CLAUDE.md file in the working folder. It applies to that job, and if you share the folder with someone, it applies to them too.
Among your own stuff — a CLAUDE.md in your personal Claude folder. It applies in every project you open, because it's attached to you.

The question that'll come to mind is: what if I have both? They're not mutually exclusive: they stack. It reads yours and then the project's, one after the other.

Hence the common-sense rule: in yours you put how you work (what language to reply in, what tone to use, your habits); in the project's you put the specifics of that job.

Getting it written for you: /init

You don't need to start from a blank page. The /init command has it explore the folder you're in and propose a starting CLAUDE.md, with what it figured out on its own: how things are organized, what's in there, what conventions it spots.

If the file already exists it won't erase it: it proposes improvements.

Keep one thing in mind though, because it's the whole point of the next lesson: what /init writes is what shows from the folder. The real value is what you add, and it's made of the things the folder can't reveal — because they're in your head.

Checking that it's actually reading it

If you suspect it's not seeing it, don't guess: open /context, the one we used to check usage. In there is the list of loaded memory files. If yours doesn't show up, it's not reading it, and the problem is where you put it.

Careful: these are instructions, not rules

A point that ties back to the last chapter, because it's the most costly confusion: CLAUDE.md is context, not a prohibition. It steers behavior, but it doesn't prevent anything by design.

If something must never happen, go back to permissions. The instructions file is there to make it work better, not to stop it from getting things wrong.

What's next

Now you know what it is and where to put it. But there's a trap here that catches almost everyone: the temptation to write everything into it. In the next lesson we look at why a long file makes results worse instead of better.

Did you get it?

Two minutes, no grade. Trying to answer — even getting it wrong — cements the concepts far more than rereading. Not in the mood? Skip it: the lesson still counts as complete.

When is CLAUDE.md read?

You have a CLAUDE.md in your personal folder and one in the project. Which one wins?

What's the fastest way to get started with a CLAUDE.md?

1
1. 1
2. 2
3. 3
2
1. 4
2. 5
3. 6
4. 7
3
1. 8
2. 9
3. 10
4. 11
5. 12
4
1. 13
2. 14
3. 15
4. 16
5. 17
6. 18
5
1. 19
2. 20
3. 21
4. 22
5. 23
6. 24
6
1. 25
2. 26
3. 27
4. 28
5. 29
6. 30
7
1. 31
2. 32
3. 33
4. 34
8
1. 35
2. 36
3. 37
4. 38
9
1. 39
2. 40
3. 41
10
1. 42
2. 43
3. 44
11
1. 45
2. 46