What Is A CLAUDE.md File? And what goes in it.

Ryan “RyMac” McKinney · USMC · 22 August 2026 · 4 minute read

A CLAUDE.md file is a plain text note that sits in your folder and gets read before your AI does anything else. That is the entire idea. It is not code, it is not a setting, and there is nothing to install. It is a note on the front of the drawer.

What the name means

The .md ending means markdown. You may hear that word and assume it is a format you have to learn. It simply means a text file where a hash mark at the start of a line makes that line a heading. That is the entire technology, and any text editor opens one. If nobody has explained any of the words yet, start there instead.

The CLAUDE part is just the name the tool looks for. Nothing magic about the letters.

What it is actually for

Every session, your AI starts with nothing. You know your business. It does not. So either you explain it again this morning, or you wrote it down once somewhere it will look.

CLAUDE.md is that somewhere. It is read first, every time, without you asking. And if you have ever watched an AI lose the thread halfway through a job, this is the thing that was missing.

Where it goes

3 places, and they stack:

1. In your project folder. The main one. It describes this piece of work, and it travels with the folder.

2. In your home folder. A personal one that applies to everything you do, everywhere. This is where the rules about how you like to be spoken to belong, not in the project.

3. In a subfolder. When the work moves into a subfolder that has its own note, that note gets read too. This is the part people discover late and it is the reason several businesses can live under one roof without bleeding into each other.

The details on all 3 are in Anthropic’s own documentation, and it is worth 5 minutes even if you skip the code parts.

What goes in it

What this folder is. One or 2 lines. Not a mission statement.

Where to go next. The single most important line in the file: before you touch anything, go read the desk file. That is the pointer that makes the rest of the folder structure work.

The rules you are sick of repeating. Mine says never use an em dash. Mine says numbers are digits. Mine says I am not a coder, so explain it like I am in 9th grade. Small, specific, and they save an argument a day.

Where the material lives. The paths. Boring, and it stops the guessing.

What does not go in it

Today's work. That belongs in the desk file, which changes daily. The map should barely change at all.

Everything you know. This is the big one. A long map costs you on every single session, because it is re-read every time. Every line has to earn its seat, which is the same reasoning behind how much room the AI has to work in.

Secrets. Passwords and keys do not belong in a file that gets read out loud and shared with the folder.

The mistake that makes it useless

People make the map do the work.

They put standing instructions in it, then also keep a desk file, and now 2 files give orders. When they disagree, and they will, your agent picks one and you cannot tell which. The map points. It does not instruct.

The full argument for why the pointing is separate from the instructing is interpretable context methodology, which is the method this file comes out of. Jake Van Clief teaches the folder version of it at Clief Notes, and that is an affiliate link.

Write yours in 10 minutes

1. Make a file called CLAUDE.md at the top of the folder you work in.

2. Line 1: what this folder is.

3. Line 2: before you do anything, read Context.md.

4. Then 3 rules you are tired of repeating, in your own words.

5. Stop. Do not add anything else today.

If you would rather start from a written one than a blank page, take my template, and the things I got wrong first are in the best practices post.