A CLAUDE.md file is a plain text file of instructions that Claude Code reads at the start of every session, so you don't have to re-explain how your project or business works each time. Put it in your project folder, keep it under 200 lines, and remember that Claude treats it as guidance it usually follows, not a lock it has to obey.
If you're brand new to Claude Code, my beginner's walkthrough covers the basics. This page is the full reference: where the file goes, what earns a line in it, and what to do when Claude seems to ignore it.
CLAUDE.md in one minute
Every Claude Code session starts with a blank slate. Anthropic's memory page describes two ways knowledge carries over: CLAUDE.md files that you write, and auto memory, which is notes Claude writes for itself. Both load at the start of every conversation.
The single most useful sentence on that page for a business owner is this one: Claude treats both as context, not enforced configuration. To block an action regardless of what Claude decides, the page points you to a PreToolUse hook instead. So a line in CLAUDE.md is a request. A hook is a lock.
Skills are a different thing again. CLAUDE.md holds facts Claude should have in every session, while Claude skills hold step-by-step procedures that load only when a task needs them.
Where the file goes
You can have several CLAUDE.md files, each with a different reach. They load from broadest to most specific, so a project instruction lands in context after a personal one:
| Scope | Location | Who it's for |
|---|---|---|
| Managed policy | A system folder set by IT | Everyone in the organisation |
| User instructions | ~/.claude/CLAUDE.md | Just you, in every project |
| Project instructions | ./CLAUDE.md or ./.claude/CLAUDE.md | Your team, shared through source control |
| Local instructions | ./CLAUDE.local.md | Just you, in this project, kept out of the shared copy |
CLAUDE.md files in the folders above where you start Claude Code load at launch. Files in subfolders load on demand, when Claude starts working in that part of the project.
Create yours in four steps
- Open Claude Code in your project folder and type /init. Claude looks through your files and writes a starter CLAUDE.md with the commands and conventions it finds. If you already have one, /init suggests improvements rather than overwriting it.
- Type /memory to open the file in your editor. The same menu lists your personal and project CLAUDE.md locations, including ones that don't exist yet.
- Trim it. Anthropic's best practices page says the work after /init is mostly removing lines. Cut anything Claude could work out by reading your files.
- Run /context and check the list under Memory files to confirm Claude loaded it.
Here's a short example for a small business that uses Claude Code for content and admin. It's mine, not Anthropic's, and the point is what's missing: no description of the folder layout, because Claude reads that itself.
Example CLAUDE.md for a small business
Tone of voice
- British spelling, short sentences, no jargon
- Client emails end with my first name only
File naming
- Client name, then date, then document type
Never touch
- The invoices folder
- Any file with FINAL in its name
How to check work
- Read every draft against the brief in the briefs folder before saying it's done
Notice the Never touch section. Claude will follow it nearly every time, but nearly isn't always. If an accidental edit to your invoices would hurt, that rule belongs in a hook or a deny rule as well.
What earns a line, and what doesn't
Anthropic's best practices page gives a clear test. A line belongs in CLAUDE.md only if Claude couldn't work it out from the files itself, such as:
- How to confirm work is right, with the exact command or check to run.
- Places where your files are misleading, like an old folder that looks unused but isn't.
- Decisions that aren't written down anywhere Claude can see.
- Anything you've had to correct twice already.
Leave out descriptions of your architecture and file layout, because Claude reads the project itself. And stop piling on IMPORTANT or ALL CAPS. The page says that mostly makes Claude over-apply a rule. Write instructions concrete enough to check: "Use 2-space indentation" beats "format code nicely". Personal preferences go in CLAUDE.local.md, not the shared file.
How long is too long
The memory page says to target under 200 lines per CLAUDE.md file. Longer files use more context and reduce how reliably Claude follows them, and you'll see a warning at startup and in /status when a file runs long. Claude Code skips any file over 4 MiB entirely.
If one part of your instructions only matters for certain files, move it into path-scoped rules under .claude/rules/, which load only when Claude works on matching files. Splitting with @path imports keeps things tidy but doesn't save context, because imported files load alongside the CLAUDE.md that pulls them in. The /doctor checkup will also propose cuts.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
CLAUDE.md or auto memory?
This is the part people mean when they search for Claude Code memory. Auto memory is Claude's own notebook. It's on by default in local sessions, and Claude decides what's worth saving: your role and preferences, corrections you give it, project decisions it can't see in the files, and where to find outside information. The first 200 lines or 25KB of its MEMORY.md index load each session, whichever comes first.
Ask Claude to "remember" something and it goes to auto memory. Say "add this to CLAUDE.md" and it goes in your file. Use /memory to browse what Claude has saved, edit it, or switch auto memory off. It's all plain text you can read or delete.
One more rule if you use other AI coding tools. If a project has an AGENTS.md and no CLAUDE.md, Claude reads the AGENTS.md. If both exist, Claude reads only the CLAUDE.md files unless your CLAUDE.md imports AGENTS.md. Reading AGENTS.md directly needs Claude Code version 2.1.277 or later.
If Claude ignores it
Run /context first. If your file isn't listed under Memory files, Claude can't see it, so check it's in a location that loads for your session. The memory page explains why even a loaded file isn't obeyed every time: CLAUDE.md is delivered as a user message after the system prompt, so Claude reads it and tries to follow it, without a guarantee. Vague or conflicting lines make that worse, and when two files disagree, Claude may pick one arbitrarily.
If instructions seem to vanish after /compact, the page says your project-root CLAUDE.md is re-read from disk and survives. What gets lost is anything you only said in the conversation. Put it in the file and it'll stick. Once your file is set up, try a few ready-made Claude Code prompts to see the difference.
What I'd do this week
I'd run /init, then spend ten minutes deleting lines until only the things Claude can't guess are left: how you check work, what never to touch, and the decisions in your head. I'd skip auto memory settings, rules folders and imports until the file has been in use for a while and you know what's missing.
If your team wants a shared instructions file that makes Claude Code work the way your business does, that's the kind of AI enablement I help with. I run AI training and workshops for teams, and help businesses with AI enablement and workflow automation, so the busywork runs itself and people get time back. Most of that work is with SaaS marketing teams and small businesses. Here's how we can work together.
Frequently asked questions
What is a CLAUDE.md file?
It's a plain text file of instructions that Claude Code loads at the start of every session, used for things like how to check work, conventions and decisions Claude can't see in your files.
Where should I put my CLAUDE.md file?
For a project, put it at ./CLAUDE.md or ./.claude/CLAUDE.md in the project folder. For personal instructions across all projects, use ~/.claude/CLAUDE.md, and use ./CLAUDE.local.md for private notes on one project.
How long should CLAUDE.md be?
Anthropic's memory page says to target under 200 lines per file. Longer files use more context and reduce how reliably Claude follows them.
Does Claude always follow CLAUDE.md?
No. Claude treats it as context, not enforced configuration. For a rule that must always hold, use a hook or a deny rule.
What's the difference between CLAUDE.md and auto memory?
You write CLAUDE.md. Claude writes auto memory itself, from your corrections and preferences, and loads the first 200 lines or 25KB of its index each session.
