How to Write a CLAUDE.md File: What Goes In, What Stays Out

A conversation with AI can be picked back up. One continuous stretch of conversation, from start to whenever you stop, is called a session. Claude Code has claude --continue, which picks up the last conversation exactly where it left off, and claude --resume, which lets you choose an older session to reopen. If you assumed everything vanishes the moment you close the window, that's not the case.

But resuming doesn't cover every case. A new session starts from zero, and the early part of a long conversation gets compressed into a summary. Someone else working on the same project doesn't inherit your conversation in their session. Keep handing off work like this and you end up repeating the same "here's how we do things on this project" explanation every single time.

CLAUDE.md is the file where you write that repeated explanation down once. Claude reads it every time a session starts, so once you've written it, it keeps getting referenced without you having to repeat yourself. The .md at the end of the name means it's a Markdown file: a plain-text writing format that marks up structure with symbols like # before a heading and - before a list item. This piece walks through what the file looks like, where to put it, how long it should be, and how to use it alongside other instruction files.

Inside the file, you'll find plain sentences like this.

# Rules for this project
- Write answers in plain English
- Lead reports with the conclusion
- Use YYYY-MM-DD for dates
- Don't delete draft files

A heading and a list are all you need to get started; there's no fixed format. If you've already written one and find yourself wondering "why isn't this being followed," start by checking the location, the length, and the wording. This piece is current as of August 2026, and everything in it is sourced from the official docs.

CLAUDE.md

CLAUDE.md is a Markdown file where you write down what you want Claude to keep following. It's read in full every time a session starts, so it's the place for facts and rules you'd otherwise have to explain every time.

File location: what decides the scope

The same content applies differently depending on where the file sits. Before the table, let's unpack the path notation, since it can look unfamiliar. A path is an address for where a file lives on your computer.

A terminal is a window where you type commands instead of clicking. ~ stands for your home folder, and ./ stands for the project folder currently open in your terminal. A name starting with a dot, like .claude, is often hidden from a normal file listing. So ~/.claude/CLAUDE.md reads as "the CLAUDE.md file inside the hidden .claude folder in my home folder."

The table below lists them in the order Claude Code reads them.

None of these overwrite each other; they all get appended together. They're read in the order above, and the one read later is treated as the closer, more specific instruction.

The one you'll use most is the project-level CLAUDE.md. Save it alongside your project files, and the same instructions apply to everyone who gets a copy of that project.

CLAUDE.local.md is for settings only you use: a test URL, a personal preference, that kind of thing. This file needs to go in .gitignore, the list of filenames that don't get uploaded to Git, meaning files you don't share with anyone else.

How it searches: parent and child folders

Claude Code starts at the current folder and climbs outward, one parent folder at a time, looking for a CLAUDE.md. That's why, even if you start deep inside a nested folder, the instructions in an outer folder still get picked up.

Going the other direction, a CLAUDE.md in a child folder isn't read immediately when the session starts. It gets pulled in only when Claude reads a file in that folder.

Auto memory: the record Claude keeps itself

Here's a spot that's easy to mix up. Claude Code draws on two different kinds of memory. You write CLAUDE.md yourself; auto memory is something Claude writes on its own while it works.

Auto memory is on by default. Even if you never create a CLAUDE.md, Claude can still remember what it picks up while working. If you've seen a note like "2 memories saved," that means it got written to auto memory.

What Claude saves falls into four categories: your role and preferences (user), corrections you've given (feedback), progress that isn't obvious from the project files alone (project), and where to find outside material (reference). It doesn't save things like folder structure or file paths that it can figure out just by reading the project.

Anything starting with /, like /memory, is a command you run in the Claude Code input box. If you're curious what's accumulated, run /memory and open the auto memory folder it points to. It's Markdown too, so you can read, edit, or delete what's in there.

If you want to turn auto memory off, change the setting from that same /memory screen, or add this to your project settings.

{
  "autoMemoryEnabled": false
}

So what goes where? Rules that need to hold every single time go in CLAUDE.md, written by you. Things Claude just needs to remember from working on the task can be left to auto memory. Say "remember this" mid-conversation, and it lands in auto memory. Say "add this to CLAUDE.md," and it goes into the instruction file you manage.

Length: keep it under 200 lines

It's tempting to think a more detailed CLAUDE.md is always better, but past a certain length, instructions start getting buried instead. The official docs recommend keeping each file under 200 lines.

Context is the window of conversation and material Claude references at once. The longer CLAUDE.md gets, the more of that window it eats up, and the less reliably its instructions get followed.

CLAUDE.md isn't a hard lock that's always enforced. It's reference material delivered the same way any message you send in conversation is. Claude reads it and tries to follow it, but if it's long and vague, some of it can slip through.

It's the same reason nobody reads a manual once it gets thick enough.

What to cut: anything visible in the files

If the file has grown long and you're not sure what to cut, you can ask Claude Code itself. Type /doctor into the input box. It's a health-check command that scans your install and settings, but it also flags content in CLAUDE.md that's worth trimming.

If you're deciding for yourself, there's one test: can Claude figure this out on its own?

Cut anything that's visible just by opening the project files: how the folders are laid out, what stack you're using, the overall structure. Claude scans the files directly when it starts a task, so writing this stuff into CLAUDE.md just means it reads the same information twice.

Keep what the files alone can't tell you: what you do differently from the norm, why you decided it that way, and the rules that need to hold.

"On this project, we do it this way, unlike everywhere else" is exactly the kind of thing CLAUDE.md is for.

When to add a rule: the same explanation, twice

If you're unsure when to add a rule, watch for these four moments.

• Claude makes the same mistake a second time
• You're reviewing code and spot something Claude needs to know
• You're typing out the same explanation you gave last time
• It's something you'd have to tell a new teammate too

If you've said the same thing twice, it's time to write it down. Stick to just this one rule and the file won't balloon with things it doesn't need.

How to phrase it: rules you can verify

Write rules so you can tell at a glance whether they were followed. The official docs' development examples make the difference clear.

Indentation is the space pushed in at the start of a line. npm test is the command that runs a project's checks, and an API handler is the file that processes an incoming request. Don't worry about the exact dev terminology; look at the difference between the left and right columns instead. The right side names a specific spacing, a specific command to run, a specific folder to save into. A rule only functions as a real instruction if you can tell whether it was followed.

Notes for humans: HTML comments

An HTML comment is a note you place between <!-- and -->. Inside CLAUDE.md, it gets stripped out before Claude ever sees it, so it's a way to leave context only for someone who opens the file directly.

<!-- This rule exists because of the January 2026 deploy incident. Check with the owner before changing it -->
 
- Always verify on staging before deploying

That comment doesn't count against anything Claude reads. It's useful for leaving the reason behind a rule, or a note to check with someone before changing it, for a human only. One exception: a comment inside a fenced code block, shown as example code, stays exactly as written.

Splitting the file: importing with @

Once the file gets long, you can split its content across other files. Write @ followed by the path of the file you want to pull in.

See @README for the project overview.
 
# Additional instructions
- Git workflow: @docs/git-instructions.md

Imported files are read together with the main one when a session starts. If an imported file imports another file in turn, that chain can run up to four levels deep.

Here's a common misunderstanding: splitting the file doesn't reduce context. Importing only helps you organize the content. Since every imported file gets read at the start, the total volume stays the same.

To actually cut down how much Claude reads up front, you need path-based rules or skills instead.

A path-based rule is an instruction that only matters when Claude is touching a specific set of files. Put a rule file in the .claude/rules/ folder and list the paths it applies to under paths at the top. Then the instruction only gets read when Claude touches those files.

---
paths:
  - "src/api/**/*.ts"
---
 
# API writing rules
- Add input validation to every endpoint

This example means: read the input-validation rule whenever you're working with any TypeScript file under src/api.

A skill is a file that spells out the steps for a specific kind of task, separately. If it's a step-by-step procedure, it belongs in a skill rather than CLAUDE.md. A skill only gets read when that particular task actually comes up.

Put facts Claude should always know in CLAUDE.md. Put rules that only matter for specific files in a path-based rule, and put the steps for a specific task in a skill.

AGENTS.md: using it together with @

If you use several different AI coding tools, you may already have an AGENTS.md with your shared rules in it.

Claude Code reads CLAUDE.md, but not AGENTS.md. Copy the same rules into both files and the two will drift the moment you update only one.

The approach the official docs recommend is the @ import from earlier. Create CLAUDE.md and write this as its first line.

@AGENTS.md
 
## Claude Code only
 
Use plan mode when changing anything under `src/billing/`.

This example is a Claude Code-only rule: don't edit src/billing/ directly, plan first.

Keep shared rules in AGENTS.md and nowhere else. Anything specific to Claude Code goes underneath the import. I use this setup myself. Updating a shared rule means touching one file, so the two never drift apart.

If you have nothing Claude Code-specific to add, a symlink works too. A symlink points one filename at another file.

ln -s AGENTS.md CLAUDE.md

On Windows, a symlink needs admin rights or developer mode enabled. In that case, use the @AGENTS.md import instead.

Getting started: an /init draft

Writing one from scratch feel like a lot? Type /init into the Claude Code input box and it drafts one for you.

/init

Claude scans your project files and drafts something out of the build commands you need to run it, how to test for errors, and any project rules it finds. If a CLAUDE.md already exists, it won't overwrite it; it'll suggest improvements instead.

If the project already has settings for another tool, like AGENTS.md or .cursorrules, it reads those too and folds them in.

The draft is a starting point. It only becomes useful once you fill in what Claude can't tell from the project files alone, especially the "why" behind how things are done.

I used to run the file /init generated without even opening it. Whenever Claude broke a rule, I'd bolt on more emphasis: bold the text, move the rule to the top, add a priority label. The file that started as a few lines grew past a hundred, and the rate at which rules got broken never budged.

The fix turned out to be trimming, not emphasizing. Once I cut the overlapping instructions, what actually needed to be followed became clear. This is exactly why the 200-line guideline matters: length doesn't make instructions stick better, it buries the ones that matter among all the others.

Troubleshooting: the order to check things in

If you've written an instruction and Claude still isn't following it, check things in this order.

1. Check whether the file was actually read. Run /context and it lists every CLAUDE.md that got pulled into this session. If yours isn't on the list, the file is probably in the wrong location. /memory opens files for editing, so it'll show you files you haven't even created yet; use /context, not /memory, to check whether one was actually read.
2. Check whether the instruction is specific. As in the earlier table, it needs a defined action, command, or location.
3. Check for conflicting instructions. When the organization, personal, project, and local files are all read together, they can contain instructions that disagree with each other. If two collide, Claude picks one on its own.
4. Check whether it's something that has to run, no exceptions. If a specific command needs to run before every commit or every file edit, a hook is the right tool, not CLAUDE.md. A hook fires a command automatically at a set moment, so it doesn't depend on Claude's judgment at all.

You might wonder whether an instruction survives once a long conversation gets summarized and the early part compresses. A CLAUDE.md at the project's root, the outermost folder, gets read again after that summary happens. A CLAUDE.md in a child folder doesn't come back automatically; it only re-enters when Claude reads a file in that folder again.