CLAUDE.md: give Claude Code a persistent project memory

🧠 What CLAUDE.md is and why I write it

A CLAUDE.md is a markdown file with persistent instructions for a project. I write it in plain text and Claude Code reads it at the start of every session, before I even type the first prompt. I don't rebuild the context by hand every time: build commands, conventions, directory layout and rules like «always do it this way» sit there and apply right away.

The question I use to decide what to put in it is always the same: would I re-explain this to a new teammate? If yes, it goes in the file. It ends up there when Claude makes the same mistake a second time, when a code review catches something it should have known about this repo, or when I notice I'm typing the same correction as last session.

What I don't put in it are long procedures or rules that only matter for one corner of the code: for those I use a skill or a scoped rule, which loads only when needed. The CLAUDE.md stays the place for the facts I want in every session, not the project manual.

# Project — rules for Claude Code

## Commands
- Build: `yarn build`   # never npm
- Test:  `yarn test`

## Conventions
- 2-space indentation
- API handlers live in `src/api/handlers/`
- Early return, no else after a return

🗂️ Where the files live: the memory hierarchy

CLAUDE.md files can live in several places, each with a different scope. Claude Code loads them from the broadest to the most specific, so a project instruction lands after a personal one and, on the same topic, the one closest to where I launch the command wins.

The four levels, from broadest to narrowest: the managed policy owned by the organization, my user preferences in ~/.claude/CLAUDE.md, the project one in ./CLAUDE.md (or ./.claude/CLAUDE.md) shared with the team via Git, and the local one in ./CLAUDE.local.md, which I keep in .gitignore for my own things in this repo.

A detail I exploit in monorepos: Claude walks up the directory tree from where I am and concatenates every CLAUDE.md it finds, while the ones in subdirectories load on demand, only when it touches files in there. Instructions don't override each other: they add up.

✍️ Writing instructions Claude actually follows

Since the CLAUDE.md enters the context at every launch, how I write the instructions matters as much as what I write. Three things make the difference. The first is size: I aim to stay under 200 lines, because a long file consumes context and, paradoxically, gets followed worse.

The second is specificity. «Format the code properly» isn't verifiable; «Use 2-space indentation» is. I always prefer the instruction a reviewer could tick off: «Run yarn test before committing» instead of «test your changes». The third is consistency: if two rules contradict each other, Claude picks one arbitrarily, so every now and then I re-read and prune the old or conflicting ones.

When the file grows too big, instead of bloating it I move the per-area instructions into .claude/rules/, one file per topic attached to precise paths via a glob in the frontmatter. That way the rules about components load only when I touch the components, and the rest doesn't take up context in every session.

🔗 Imports with @path and the bridge to AGENTS.md

A CLAUDE.md can pull in other files with the @path/to/file syntax: at launch they're expanded into context alongside the file that references them. I use them to avoid duplicating what already lives elsewhere — a @README for the overview, a @package.json for the scripts — with relative or absolute paths and a maximum depth of four hops.

Two things I've noted down. If I want to mention a path without importing it, I wrap it in backticks: outside backticks @README imports the file, inside it stays text. And the first time a project file imports something outside the working directory — say from my home — Claude Code asks for confirmation with a dialog: it's the protection from imports someone else might commit to a shared repo.

The bridge to AGENTS.md is handy too: Claude Code reads CLAUDE.md, not AGENTS.md, so if a repo already uses the latter I create a CLAUDE.md that imports it with @AGENTS.md and add the Claude-specific instructions below. One source of truth, read by every tool.

See @README for the overview and @package.json for the scripts.

# Common rules (shared with other agents)
@AGENTS.md

## Claude Code only
- Use plan mode for changes under `src/billing/`
- Mention `@docs/api.md` in backticks: stays text, not imported

🩺 /init, /memory and /context: generate and verify

I never start from a blank page: /init analyzes the codebase and generates a starting CLAUDE.md with build commands, test instructions and conventions it discovers on its own. If the file already exists, instead of overwriting it, it suggests improvements. From there I refine by hand with the things Claude couldn't guess from the code.

To understand what's really active I use two distinct commands. /memory lists the memory files — CLAUDE.md, CLAUDE.local.md and the others — across the various levels and opens them in the editor. /context instead shows me what was actually loaded in this session, under the Memory files entry: if a file isn't there, Claude isn't seeing it, and it's the first thing I check when a rule seems ignored.

Then there's auto memory, complementary: on by default, it's Claude that takes notes on its own — commands, debugging insights, preferences — under ~/.claude/projects/, while the CLAUDE.md stays the part I write. I inspect and prune it from the same /memory.

# generate a starting CLAUDE.md from the codebase
/init

# lists and opens the memory files (all levels)
/memory

# shows what is ACTUALLY loaded in this session
/context      # -> "Memory files" entry

⚠️ It's context, not a constraint: the limit to know

The most costly misunderstanding is treating the CLAUDE.md as configuration that enforces behavior. It isn't: its instructions arrive as a message after the system prompt, Claude reads them and tries to follow them, but there's no guarantee of strict compliance, especially if they're vague or in conflict. The more specific and concise they are, the more they're respected.

When a rule must fire at a precise point — before every commit, after every edit — I don't leave it to the CLAUDE.md: I write it as a hook, which runs a shell command at a lifecycle event and applies regardless of what Claude decides. The CLAUDE.md guides, the hook enforces: two different tools, kept separate.

One last thing: the project-root CLAUDE.md survives */compact* — after compaction Claude re-reads it from disk and re-injects it. The ones in subdirectories don't: they reload the next time I touch a file in there. That's why the always-on rules live in the root file.

✅ The flow I follow for a memory that stays useful

Put together, the CLAUDE.md isn't a document I write once and forget, but a living file I prune as the project changes. The mini-flow I follow, in order:

• Start from */init* for a baseline, then cut everything Claude can infer on its own from the code.
• Write verifiable instructions, under 200 lines, and move into .claude/rules/ what only matters for one area of the code.
• Import instead of copying: an @AGENTS.md or a @docs/… keeps one source of truth, with no duplicates that go stale.
• Verify with */context* when a rule seems ignored: if it isn't among the Memory files, the problem is where I put it.
• Promote to a hook what can't be skipped, and leave to the CLAUDE.md what only needs to guide.

More articles from the blog