CLAUDE.md, explained by monkey

Every new conversation in Claude Code starts empty, so what you explained yesterday isn't in the chat any more. CLAUDE.md fixes that. It's a plain notes file in your project that Claude reads at the start of every session. Put your commands, your rules and your gotchas in it once, and you stop repeating yourself. (Claude also keeps notes of its own, called auto memory. More on that below.)

Fastest start: /init

Open Claude Code in your project and type /init. Claude reads your codebase and writes a starter CLAUDE.md with your build commands, test steps and conventions. If you already have one, it suggests improvements instead of overwriting it.

Want a more guided version? Turn on the interactive /init. It also sets up skills, hooks and a personal file, and shows you a proposal before writing anything:

$CLAUDE_CODE_NEW_INIT=1 claude
# then type /init

The template

Or write it yourself. Save this as CLAUDE.md in the top folder of your project, fill in the brackets, and delete any section you don't need. Short beats complete: aim for well under 200 lines.

# [Project name]

[One or two sentences: what this app does and who it's for.]
See @README for project overview

## Commands
- Install: [npm install]
- Run locally: [npm run dev]
- Test: [npm test]
- Lint and format: [npm run lint]

## How we work
- [Use pnpm, not npm]
- Run the tests before you say a task is done
- Ask before adding a new package
- Keep changes small, and tell me what you changed

## Code style
- [TypeScript everywhere, no "any"]
- [Components live in src/components, one per file]
- Match the style of the file you're editing

## Don't
- [Don't edit anything in generated/, it's rebuilt automatically]
- Don't touch .env files or put secrets in code

## Gotchas
- [The API tests need a local Redis instance running]
- [Anything you've had to explain to Claude twice goes here]

The @README line pulls your README in too. You can point @ at any file, so CLAUDE.md stays short and links out to the details.

Where CLAUDE.md files live

• Just you, every project: ~/.claude/CLAUDE.md
• Your team, this project: ./CLAUDE.md or ./.claude/CLAUDE.md (commit it so everyone gets it)
• Just you, this project: ./CLAUDE.local.md (add it to .gitignore)
• Your whole organisation (managed): on a Mac, /Library/Application Support/ClaudeCode/CLAUDE.md

Adding things as you go

The old trick of starting a line with # to save a memory was removed in v2.0.70. Now you just ask:

• Say "remember that the API tests need Redis" and Claude saves it to auto memory, its own notes about your project.
• Say "add this to CLAUDE.md" and it goes in your CLAUDE.md instead.
• Type /memory to open any CLAUDE.md in your editor (it creates the file if it doesn't exist yet), turn auto memory on or off, and look through what Claude has saved.

Auto memory is on by default. Claude decides what's worth keeping and saves it in ~/.claude/projects/<project>/memory/, with a MEMORY.md index and one file per topic. You'll see "Saved 2 memories" or "Recalled 2 memories" when it happens. It stays on the one computer: it isn't shared with your other machines or with cloud sessions.

The mid-session gotcha

Claude reads your project CLAUDE.md and your personal ~/.claude/CLAUDE.md once, when the session starts. Edit either one halfway through a chat and Claude keeps using the old version. The new one loads on your next /clear, /compact or restart.

Keep it short, and keep it in the file

• Aim for under 200 lines per CLAUDE.md. Longer files use more context and get followed less.
• Auto memory has a hard limit: only the first 200 lines or 25KB of MEMORY.md load each session.
• Rules that only matter for one part of your code can go in .claude/rules/*.md with paths: frontmatter, so they only load when Claude touches matching files.
• Run /context to see which memory files actually loaded.
• Put lasting rules in the file, not the chat. After /compact, the project CLAUDE.md is read again from disk, but instructions you only typed in chat can get lost.

One thing it can't do

CLAUDE.md is guidance, not a lock. Claude treats it as context, so if something must always or never happen, like never touching .env, use a hook instead. A hook runs every time, whatever Claude decides.

Monkey believe in you. Now go build.

follow @nocodemonkey