CLAUDE.md is the file Claude Code reads at the start of every session: a plain Markdown file where you write down who you are, how your project is structured, and how Claude should behave in that context. Without it, every new session starts from zero. With it, Claude knows your rules before you type the first line.
I run my business with a workforce of eight AI employees on Claude, each with its own CLAUDE.md as a role description. What belongs in that file and what doesn't is something I learned across many of these files, usually at the point where one grew too long or too vague to be followed. The other building blocks of my Claude setup are on the Claude overview page.
What taught me the most was a file with no code in it at all: the CLAUDE.md for Frieda, my office package that handles the inbox, appointments, and receipts. It's further down in this post, in full.
What CLAUDE.md is, and what it isn't
CLAUDE.md is context, not an enforced rule. Claude reads the file at the start of every session and weighs it while answering, the same way it weighs any other information in its context window. A line like "never delete files in the invoices folder" is a strong instruction, but it isn't a technical lock. If you need a hard ban, you have to add it separately as a hook or in permissions.deny, according to Anthropic's memory documentation (code.claude.com/docs/en/memory).
That's the difference from classic chat tools, which start every session from zero and force you to retype context over and over. Why this forgetting is the basic mechanics of every language model, not a weakness of one vendor, is something I've taken apart in Why ChatGPT Forgets and AI Employees Don't. CLAUDE.md is one of several answers to exactly that problem, built for the terminal workplace that is Claude Code.
The four levels: where CLAUDE.md lives
According to Anthropic's memory documentation (code.claude.com/docs/en/memory), there are four levels that get merged together rather than overriding each other. A company-wide managed policy comes first, then your personal preferences, then the project, then your local notes.
| Level |
Path |
What it's for |
| Managed policy |
set by the organization |
company-wide rules |
| User |
~/.claude/CLAUDE.md |
your personal rules, across every project |
| Project |
./CLAUDE.md or ./.claude/CLAUDE.md |
role, rules, and knowledge for this project |
| Local |
./CLAUDE.local.md |
your own notes, kept out of git via gitignore |
For a single AI employee, the project level is usually enough. You can move additional, modular rules into .claude/rules/*.md, optionally with a paths: frontmatter that limits a rule to certain folders. You can also import extra files into CLAUDE.md with @path, instead of cramming everything into one file.
/init, /memory, and /context in daily use
Three commands cover most of the day-to-day work with CLAUDE.md. /init generates a first starting file in a new project, derived from your project folder. /memory opens the currently loaded CLAUDE.md files directly for editing, so you don't have to hunt down the right path first. /context shows you what is actually loaded right now, useful when a rule doesn't seem to take effect and you want to check whether the file was even read.
Separate from that, there's Auto Memory, which Claude Code drops automatically from your sessions under ~/.claude/projects/<project>/memory/. You write CLAUDE.md yourself, deliberately; Auto Memory accumulates in the background. I cover the difference from the memory feature in claude.ai, which remembers things from your chats, in more detail in Claude Memory: How to Use It.
A CLAUDE.md as a personnel file: the Frieda example
Most examples online treat CLAUDE.md as a tech-stack note: which framework, which conventions, which linter. For an AI employee who doesn't write code but, say, sorts the inbox, the file needs a different shape: it describes a role, not a codebase.
Here's what that looks like for Frieda, my office package for inbox, appointments, and receipts, shortened and without any real client data:
# Frieda: Office Assistant
## Task
You sort the inbox, suggest appointments, and prepare receipts for
bookkeeping. You are the first stop for everything that arrives by email
or mail, and make sure nothing gets left unhandled.
## Rules
- File invoices under `receipts/incoming/<year>/<month>/`, named by date
and sender.
- Suggest appointments with two alternatives, never with just one.
- Summarize unclear requests in at most three sentences instead of
forwarding the whole email.
- Keep your tone short and friendly, no filler phrases like "I hope
this email finds you well."
## Boundaries
- You never send replies on your own, you prepare drafts for approval.
- You never commit to prices or dates without approval.
- For invoices over 500 euros, ask before filing whether the amount
is correct.
## Files
- `inbox/` for new, unprocessed messages
- `receipts/incoming/` for checked invoices and receipts
- `contacts.md` for recurring senders and how to handle them
## Approvals
Anything that leaves the office outward, such as a reply email or an
appointment confirmation, gets created as a draft and waits for approval.
Internal sorting and filing you handle on your own.
Five blocks, each with a clear purpose: what the job is, what the rules are around it, where the boundaries sit, which files belong to it, and what needs approval before it leaves the house. I carry this same pattern, role instead of topic folder, into Claude Projects too, where the same logic works without a terminal: How to Use Claude Projects Right.
What belongs in CLAUDE.md, and what belongs in Skills or Rules
CLAUDE.md carries the role: who is working here, under which rules, within which boundaries. A recurring task, such as "how I put together a quote" with fixed steps, belongs in a Skill instead, which only loads when needed and keeps CLAUDE.md lean. Rules that only apply to one subfolder, say only to receipts/, belong in a .claude/rules/*.md file with a matching paths: frontmatter rather than in the main file.
Hard bans belong in neither: if something must never happen under any circumstances, such as a delete command on a specific folder, that's a job for hooks or permissions.deny, not a sentence in CLAUDE.md. That keeps the file doing what it's meant to do: context, not a firewall.
Staying under 200 lines
Anthropic's documentation recommends keeping CLAUDE.md under roughly 200 lines. The reason isn't aesthetics: every line in the file takes up room in the context window of every single session, even when it isn't needed at that moment. Nobody reads a file that long all the way through anymore, and in my experience, the more rules sit side by side, the less reliably any single one of them lands.
Being specific helps more than being long. "Write professionally" is a weak rule because it leaves room for interpretation. "Invoices over 500 euros need a check before filing" is a specific rule because Claude can follow it without guessing. If your CLAUDE.md keeps growing, that's usually a sign to move parts into Skills or Rules rather than keep appending to the same file.
Frequently asked questions
Where exactly does my CLAUDE.md live?
For a single project, usually under ./CLAUDE.md or ./.claude/CLAUDE.md in the project folder. For rules that should apply across all your projects, ~/.claude/CLAUDE.md comes in as well. Use /memory to open the currently loaded files directly, without hunting for the path.
Does Cowork read my CLAUDE.md too?
According to Anthropic's memory documentation (code.claude.com/docs/en/memory), Cowork sessions do read CLAUDE.md, but skip imports that live outside the working folder. For the core of your role that's enough; for extra files brought in via @path, check the specific case.
How long can a CLAUDE.md be?
The documentation recommends staying under roughly 200 lines. There's no hard technical limit, but the longer the file, the more context window it consumes in every session, and the more individual rules start diluting each other.
What's the difference from Auto Memory?
You write CLAUDE.md yourself, deliberately, and it describes a role. Claude Code collects Auto Memory automatically from your sessions under ~/.claude/projects/<project>/memory/, without you actively maintaining it. The two complement each other but don't replace each other.
Why does Claude ignore my rule in CLAUDE.md?
Usually because the rule is worded too vaguely, or because the file has grown long enough that individual sentences get lost in the context. Check with /context whether the file is being loaded at all, and make the rule in question more specific. For a truly hard ban, you also need a hook or an entry in permissions.deny.
How to write your first CLAUDE.md
Don't start with a wish list. Start with /init in a real project, let Claude draft a first version, and then add the five blocks from the Frieda example: task, rules, boundaries, files, approvals. After the first sessions, check with /context what's actually getting through, and trim rather than keep appending.
I show how a role like this grows from the first onboarding conversation into ongoing work in Claude Code: A Guide for Beginners. All eight ready-made packages, each with its own CLAUDE.md, are in my community.
