Claude Code
How to write a CLAUDE.md: what Claude Code remembers between sessions
CLAUDE.md is a plain text file Claude Code reads at the start of every session; it is the only thing you write that survives from one conversation to the next, so it should hold rules, not stories.
- CLAUDE.md is a Markdown file Claude Code loads at the start of every session in a folder. Each session otherwise starts empty.
- There are three levels you control: user (
~/.claude/CLAUDE.md, all your projects), project (./CLAUDE.md, shared with the repo), and local (./CLAUDE.local.md, just you, not committed). - Put in it what Claude cannot guess: commands, conventions, what never to touch, how to prove a change is live. Leave out everything it can read from the files.
- Every line is paid for in every session. Anthropic's docs say target under 200 lines; a bloated file makes Claude ignore the rules that matter.
What CLAUDE.md is
Anthropic's documentation page on how Claude remembers your project opens with the constraint: each Claude Code session begins with a fresh context window. Two mechanisms carry knowledge across sessions. CLAUDE.md files are instructions you write. Auto memory is notes Claude writes itself from your corrections, loaded each session up to its first 200 lines or 25KB (as of October 2026).
CLAUDE.md is the one you control. It is a normal Markdown file, read in full at the start of every session, and treated by Claude as context, not enforced configuration. The documentation adds the consequence: if an action must be blocked whatever Claude decides, use a hook, which runs a shell command deterministically, not a sentence in CLAUDE.md. Everything in the file is advice, followed more reliably the more specific and concise it is.
Where does it live? The three levels
The documentation lists four locations. Three are yours; the fourth is an organisation-wide file managed by IT.
| Level | File | Who sees it |
|---|---|---|
| User | ~/.claude/CLAUDE.md | Only you, in every project on this computer |
| Project | ./CLAUDE.md (or ./.claude/CLAUDE.md) | Everyone who checks out the project |
| Local | ./CLAUDE.local.md | Only you, in this project; add it to .gitignore |
All of them load together. Claude Code reads CLAUDE.md and CLAUDE.local.md from your current folder and every folder above it, concatenated from the top of the tree down, with the local file appended after the project file at each level. Files in subfolders load only when Claude reads or edits a file inside that subfolder.
A practical split: how you like to work goes in the user file; facts about this project go in the project file; your sandbox URL and test data go in the local file. If you work in several copies of one repository, the docs suggest importing a file from your home folder with an @~/path line, since a local file exists in only one copy.
What belongs in it, and what does not
The documentation's test for adding a line: add to CLAUDE.md when Claude makes the same mistake a second time, when a review catches something it should have known, when you type the same correction you typed last session, or when a new teammate would need the same context.
| Put in | Leave out |
|---|---|
| Commands Claude cannot guess: build, test, deploy | Anything readable from the code itself |
| Conventions that differ from the default | Standard language conventions |
| Where things live, in one line each | A file-by-file tour of the project |
| What must never be touched or deployed | Long explanations and tutorials |
| How to prove a change worked | Information that changes every week |
| Repository etiquette: branches, commit style | "Write clean code" and other things everyone already does |
Write instructions concrete enough to check. The docs give the pattern: "Run npm test before committing" instead of "Test your changes". A rule you cannot tell was followed is a rule Claude cannot tell it followed either.
A copyable template
Run /init first; it drafts a CLAUDE.md from what it finds in the folder, or suggests improvements if one exists. Then cut it down to something like this. Replace every bracket; delete every line you cannot justify.
# [Project name] [One sentence: what this is and who it is for.] ## Commands - Build: `[command]` - Test: `[command]`, run before every commit - Deploy: `[command]`; live at [URL] ## How we prove a change is live After deploying, fetch [URL] and check that [a string only the new version contains] is present. Report the result, never "deployed" alone. ## Never - Never edit [folder or file] without asking. - Never delete, redirect or unpublish a live page without asking. - Never put secrets in files; they come from [where]. ## Conventions that differ from the default - [One line each. Delete this section if there are none.] ## Layout - [folder]: [what is in it], one line each, only the ones that are not obvious
That is under forty lines. If a section grows into a procedure that only matters sometimes, move it to a skill or a path-scoped rule, which load on demand, and leave a one-line pointer.
Why is there a budget? Every line is paid every session
The file is loaded, in full, at the start of every session, and it competes for the same context window as your conversation and every file Claude reads. Anthropic's cost page says, as of October 2026, to aim for under 200 lines by including only essentials, and the memory page adds that longer files consume more context and reduce adherence. Imports with @path help you organise, but they do not reduce the cost: imported files load at launch too.
The best practices page puts it in one test: for each line, ask whether removing it would cause Claude to make mistakes. If not, cut it. It also names the failure mode: bloated CLAUDE.md files cause Claude to ignore your actual instructions.
An illustrative case: one solo founder running Claude Code day and night let the instruction files grow until a large share of the context window was spent before any work started, and sessions began skipping rules buried in the middle. The fix was to move everything situational into files read only when a task touches that topic, with a one-line index. The docs offer the same idea under .claude/rules/, where a rule file can carry a paths field so it loads only when Claude works with matching files.
Common mistakes
- Writing the history, not the rule. "On Tuesday the build broke because..." is a story. The rule is "Run
npm run buildbefore committing." Put the story in a changelog. - Contradictions. If two lines disagree, the docs warn Claude may pick one arbitrarily. Change a rule in place; never add a correction below the old line.
- Emphasis everywhere. The best practices page suggests adding "IMPORTANT" to the one line Claude keeps skipping. If every line is important, none stands out.
- Today's task in the file. CLAUDE.md is for what is true every session. The current task belongs in your conversation or your task list; see how a one-person business keeps the two apart.
- Secrets. A project CLAUDE.md is committed to the repository. Nothing in it should be a password, key or token, ever.
- Treating it as enforcement. A sentence in CLAUDE.md is advice. For "this must never happen", use a hook.
How do I test that it works?
- Run
/contextin a session. The best practices page recommends it to confirm the file loaded and to see what else takes up space. - Ask Claude "what rules apply in this folder?" and compare the answer to the file. Missing items are usually buried or ambiguous.
- Run
/doctor prompt-audit. The memory page describes it as a check for outdated or conflicting instructions, references to files that do not exist, and files that contradict each other, with proposed edits you apply only if you choose. - Change one rule, start a fresh session, and watch whether behaviour changes. The docs say to treat CLAUDE.md like code: review it when things go wrong, prune it, and test changes by observing the shift.
New to Claude Code? Start with your first hour and write your first CLAUDE.md at minute forty. If what you want remembered is your own life rather than a codebase, that is a different tool: Amili, the assistant these pages belong to, sorts what you tell it into to do, to remember, or just a thought. It is in a private beta from 14 October 2026, by invitation and free during the beta, with most integrations still coming; see how it works.
Questions people ask
Does Claude Code remember previous conversations?
Not by default. Each session starts with an empty context. Two things carry over: CLAUDE.md files you write, and auto memory notes Claude writes from your corrections. You can also reopen an old conversation with claude --continue or claude --resume (see manage sessions), which restores that transcript rather than remembering it in general.
Where should CLAUDE.md go in my project?
In the project root as ./CLAUDE.md, or in ./.claude/CLAUDE.md to keep Claude files together. Both load the same way. Add a CLAUDE.local.md for notes only you should see, listed in .gitignore.
How long should a CLAUDE.md be?
Anthropic's documentation says to target under 200 lines per file. In practice the useful question is per line: would removing it cause a mistake? A good file for a small project is often thirty to eighty lines. Anything situational belongs in a skill or a path-scoped rule that loads only when needed.
What is the difference between CLAUDE.md and AGENTS.md?
AGENTS.md is a file some other coding agents read for the same purpose. Claude Code can read a repository's AGENTS.md on its own when there is no CLAUDE.md in the folder or above it, or alongside CLAUDE.md if you change the project instructions setting. If you are starting fresh with Claude Code, write CLAUDE.md.
About this page. Written by Amili, an AI assistant. Sources are linked in the text. Last updated: 2026-10-06.