8 min · +130 XP
Leave Claude a note: CLAUDE.md
A short file that Claude reads at the start of every session.
By the end of this lesson
You will be able to create a CLAUDE.md for your project and add a rule that Claude follows in every new session.
Each new Claude Code session starts with a clean slate: Claude does not remember yesterday's conversation. CLAUDE.md is a plain text file in your project where you write what Claude should know every time. Claude Code reads it at the start of each session, so you do not have to explain the same things again.
When someone looks after your flat for a week, you leave a note: where the keys are, how to switch on the boiler, which plant must not be watered. You write it once, and every visitor reads it. CLAUDE.md is that note, written for Claude.
What to write in it
Things that belong in CLAUDE.md
- 1What the project is, in one or two sentences.
- 2How to run and check it: which file to open, which command starts it.
- 3Rules that must always hold, for example "never delete data.json".
- 4Style: the language of the interface, the look you want, how you want answers (short, in Russian, without jargon).
- 5Anything you have had to correct more than once.
# Family budget tool
A one-page budget tracker for our family. Opens in the browser, no server.
## How to run
- Open index.html in the browser. There is no build step.
## Rules
- All data lives in data.json. Never delete or overwrite it; make a copy first.
- The interface is in Russian. Keep the code comments in English.
- Amounts are in euros, with two decimals.
## Style
- Large buttons and text: my parents use this on a tablet.
- Explain changes to me in plain words, without jargon.The docs give a simple rule: if Claude makes the same mistake a second time, write it down. Write concrete lines, such as "Amounts are in euros", rather than general wishes such as "be careful". Keep the file short; the docs advise under 200 lines, because a long file takes more space and is followed less reliably.
Create it and edit it
“Look through this project and create a CLAUDE.md for it: what the project is, how to run and check it, and the rules you notice. Keep it short, under 50 lines, and show me the result.”
Claude reads the project and writes the file. Read it and add what Claude could not know, such as who uses the tool.
“Add to CLAUDE.md: amounts are in euros, with two decimals. Show me the line you added.”
Say this whenever you catch yourself correcting the same thing twice.
/init
Typed inside Claude Code, it does the same job as the first request. If the file already exists, /init suggests improvements instead of overwriting it.
/memory
Shows a list of memory files: your personal one, the project one and others. Choose one with the arrow keys and press Enter, and it opens in your text editor; a file that does not exist yet is created. The same screen has the switch for auto memory.
›What a .md file is and how to edit it
.md means Markdown: an ordinary text file where a line starting with # is a heading and a line starting with - is a list item. You can edit it in any text editor. You can also simply tell Claude: "Add to CLAUDE.md: amounts are in euros." It will add the line for you.
Where CLAUDE.md files live
- 1./CLAUDE.md in the project folder: the rules for this project. If you share the project, other people get it too.
- 2~/.claude/CLAUDE.md in your home folder: your personal preferences for all projects. Say "add to my personal CLAUDE.md for all projects: answer me in Russian".
- 3./CLAUDE.local.md in the project folder: your personal notes for this one project. Ask Claude to add it to .gitignore so it is not shared.
Claude Code reads these files when a session starts. If you change CLAUDE.md in the middle of a session, Claude keeps working with the old version until you type /clear or /compact, or start Claude Code again. To check which files were loaded, type /context and look under Memory files.
Auto memory: notes Claude keeps itself
Besides your CLAUDE.md, Claude keeps its own notes for each project: your corrections, your preferences, decisions it cannot see in the code. This is called auto memory, and it is on by default. When you see "Saved 1 memory" on the screen, Claude has written such a note.
“Remember that I prefer short answers in plain words, without jargon.”
Claude saves this in auto memory and follows it in later sessions of this project.
How to use the two kinds of memory
- 1Say "remember that …": Claude saves it in auto memory.
- 2Say "add this to CLAUDE.md" when it is a rule for the project that you want to see and edit yourself.
- 3Ask "what have you saved in your memory about this project?", or type /memory and open the auto memory folder. The notes are plain text; you can correct or delete them, or ask Claude to.
- 4Turn auto memory off or on with the switch in /memory.
Claude reads CLAUDE.md and tries to follow it, but nothing forces it to. For something that must never happen, such as reading your .env file, use permission rules in /permissions; they apply whatever Claude decides. If lines in different files contradict each other, Claude may follow either one, so keep them consistent.
Split large instructions into .claude/rules/*.md; a rule with paths: frontmatter (for example "src/api/**/*.ts") loads only when Claude touches matching files. @path imports organise a file but do not save context, because imports load together with the file. If the repository has AGENTS.md and no CLAUDE.md, Claude Code reads AGENTS.md; to use both, put @AGENTS.md at the top of CLAUDE.md. Block-level HTML comments are stripped before loading, so they cost no tokens. /doctor prompt-audit looks for outdated or contradicting instructions and proposes edits without applying them.
Do it now
0/5For the second time this week Claude saved amounts in dollars, although your tool works in euros. What is the most useful thing to say?
You want Claude to answer you in Russian in all your projects. Where does this line go?
Facts checked against the official Claude Code docs October 24, 2026 · source
Author
Evgenii Arsentev
PhD · Chief Executive Officer, digital health