What Is a CLAUDE.md File and What Goes In It?

Last updated: August 2026

A CLAUDE.md file is a plain Markdown file in your project that Claude Code reads at the start of every session. It holds the standing facts and rules you would otherwise repeat: build commands, conventions, hard constraints. Anthropic's current guidance is to keep it under 200 lines, because a bloated CLAUDE.md file gets ignored, not obeyed.

The short version

• It is the instructions file Claude loads every session: without one you re-explain your project each time. With one, Claude starts already knowing.
• Short beats complete: the official target is under 200 lines, and Anthropic cut over 80% of Claude Code's own system prompt in July 2026 with no measurable loss on its coding evaluations.
• It is context, not enforcement: a rule in the file shapes behaviour, it does not guarantee it. Anything that must happen every time belongs in a hook.

What should you put in a CLAUDE.md file?

Whatever you find yourself saying more than twice. If you correct the same thing in three sessions, it belongs in the file. That is the whole test, and it is better than any template.

The trap is that the file feels like documentation, so people write documentation. It is not. It is a briefing that gets re-read at the top of every session, and every line you add competes for attention with every other line. Anthropic's best practices guide gives the sharpest version of the test: "For each line, ask: 'Would removing this cause Claude to make mistakes?' If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"

Here is how that sorts in practice:

Keeps earning its place	Cut it
Build and test commands Claude cannot guess	Anything Claude can work out by reading the code
Style rules that differ from the language defaults	Standard conventions the model already knows
Your test runner and how you want tests run	Detailed API documentation, link to it instead
Repo etiquette: branch naming, PR conventions	Information that changes frequently
Gotchas and non-obvious behaviour in this codebase	File-by-file descriptions of the project

My own file for this blog runs about thirty lines: two lines on what the site is, the stack it runs on, a voice section, and a short rules block that bans em dashes and marketing clichés. That is it, and it does more for output quality than any clever prompt I could write in the moment.

You do not have to start from a blank page. Running /init in a project generates a first CLAUDE.md from what Claude finds in your codebase, and if one already exists it suggests improvements rather than overwriting your work. Treat the output as a draft. A generated file describes your project; a good file records the things your project would never tell it.

One tuning trick worth knowing, because it fails in an unobvious way. If Claude keeps skipping a single instruction, add emphasis such as "IMPORTANT" to that one line. The catch is that emphasis only works while it is scarce: mark many lines important and none of them stands out, which is the same crowding problem as an over-long file wearing a different hat.

One student I worked with spent his first two sessions re-explaining his brand voice at the start of every chat, the same three corrections every time. We spent fifteen minutes writing a CLAUDE.md that captured his tone, his audience, and his hard rules. The repetition stopped. He spent his time editing real work instead of re-teaching the basics. If you are new to the tool, that is the first habit worth building after the initial setup.

How long should a CLAUDE.md file be?

Under 200 lines. That is not my preference, it is the number in Anthropic's own documentation: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence."

The reason this is worth restating in 2026 is that the advice moved, and most people have not noticed. On 24 July 2026, alongside the Opus 5 launch, Anthropic published new guidance on context engineering and disclosed something striking about its own work: "We removed over 80% of Claude Code's system prompt for models like Claude Opus 5 and Claude Fable 5 with no measurable loss on our coding evaluations."

Read that again. The team with the most to lose from a weaker prompt deleted four fifths of it and the evaluations did not move. Their guidance for your file follows the same logic: "Keep your CLAUDE.md lightweight and briefly describe what your repo is for, but spend most of the tokens on gotchas inside of the codebase."

So the instinct almost everyone has, that a longer instructions file means a better-behaved model, is backwards. Past a certain length the file stops being instructions and starts being noise. The documented failure mode is blunt: if your CLAUDE.md is too long, Claude ignores half of it because the important rules get lost.

There is now a tool for this. Running /doctor inside a session proposes trims for a checked-in CLAUDE.md, cutting content Claude can derive from the codebase and keeping the pitfalls and conventions that it cannot. Two details matter and are widely got wrong. It reports findings and asks for confirmation before changing anything, so it proposes rather than optimises. And the shell command claude doctor is a different thing: read-only installation diagnostics that changes nothing at all.

Why does Claude ignore what is in your CLAUDE.md file?

Because the file is context, not configuration. This is the single most useful mechanical fact about it, and almost nobody publishes it. In Anthropic's words: "CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions."

That reframes the whole file. Vague rules get vague compliance. Contradictory rules get arbitrary resolution, because when two lines conflict the model may simply pick one. If a rule absolutely must hold every time, it does not belong in CLAUDE.md at all: it belongs in a hook, which runs as a shell command at a fixed point regardless of what the model decides.

The other half of this problem is the one I see constantly, and it costs people real work. A student of mine agreed two hard constraints in a session: no invented claims, and no em dashes. Both were agreed out loud. Neither was written into the file. The next session, the model invented twelve style categories that did not exist. She caught it immediately, but the lesson stuck: a constraint that lives only in the conversation does nothing.

The documentation explains exactly why. When a long session compacts, conversation-only instructions are among the first things that do not survive, while a project-root CLAUDE.md is re-read from disk and re-injected. If an instruction vanishes mid-session, the most likely reason is that it was never written down. Agreeing a rule with the model is not the same as setting it, which is also the difference between prompting and configuring.

The failure runs in the other direction too, and this one caught me. My own global instructions file had quietly accumulated lines I had not put there and did not want. Claude Code can now write its own notes across sessions, which is genuinely useful and also means the file you think you wrote is not always the file being loaded. Go and read yours. Run /context and check what appears under Memory files, then /memory to open and edit them. Two minutes, and most people have never done it once.

Where does the CLAUDE.md file go, and which one wins?

Four locations, loaded broadest to most specific. Enterprise managed policy first, then your personal file at ~/.claude/CLAUDE.md, then the project file at ./CLAUDE.md or ./.claude/CLAUDE.md, then ./CLAUDE.local.md for private preferences you keep out of version control.

The part that surprises people: these are concatenated, not overridden. Every discovered file is loaded, in order, with the most specific read last. Claude Code also walks up the directory tree, so launching in a subfolder still picks up the file at the repository root. If you have inherited instructions you cannot account for, this is usually where they came from.

You can also pull in other files with @path/to/import syntax, which expands them into context at launch, up to four hops deep. Useful for organisation, but be clear-eyed: an imported file still loads and still costs you context. Splitting a 400-line file into four imports does not make it shorter.

For anything that only matters occasionally, use a skill instead. Skills load on demand rather than every session, which is the entire difference and the reason a long reference document should never sit in your CLAUDE.md. If you want the file to help a future session recover a broken setup, that is a related but distinct job, and I wrote a whole build for it: a handoff file Claude can debug from.

Frequently Asked Questions

Where exactly does the CLAUDE.md file go?

At your project root as CLAUDE.md, or inside .claude/CLAUDE.md. Claude Code finds it and loads it automatically. Run /context and look under Memory files to confirm it actually loaded, which is the step most people skip.

What is the difference between a CLAUDE.md file and a skill?

Timing. A CLAUDE.md file loads at the start of every session whether it is relevant or not. A skill loads only when your request calls for it. Standing facts go in the file, occasional procedures go in a skill.

Does putting a rule in CLAUDE.md guarantee Claude follows it?

No. It is delivered as context, so there is no guarantee of strict compliance, especially for vague or conflicting rules. Make instructions specific and verifiable. For anything that must happen every time without exception, use a hook instead.

Will a CLAUDE.md file cost me more tokens?

Yes, on every session, which is precisely why length matters. It is a small fixed cost that usually pays for itself in wrong turns avoided, but only while the file stays lean. A bloated file costs you tokens and adherence at the same time.

I already have an AGENTS.md file. Does Claude Code read that?

No. Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already uses one for another coding agent, create a CLAUDE.md whose first line imports it with @AGENTS.md, then add any Claude-specific rules underneath. Both tools then read one source instead of two files that drift apart.

Does Claude Cowork read a CLAUDE.md file too?

Yes. Cowork sessions on your desktop do load CLAUDE.md files. The difference is in imports: in those sessions, an import in a user-scope file that points outside the working directory is skipped rather than prompted for, so keep anything load-bearing in the file itself rather than behind an import. If you are choosing between the tools, start with how to use Claude at work.

Want your setup done right the first time?

Most people do not need more Claude tips. They need someone to look at how they actually work and set it up so it holds. That is most of what a first session with us is: your CLAUDE.md, your skills, your rules, configured once so every session after is faster. Book a free 15-minute Discovery Call, and bring the corrections you keep repeating to Claude. We will turn them into a file that does the repeating for you.

Written by Michael Murr for AI Tutor Code: private 1-on-1 online tutoring for professionals learning Python, AI tools, Data Science, ML, and LLM engineering. 200+ students taught, 3,000+ hours delivered.