.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Every Claude Code session starts from zero. The model doesn't remember that your project uses pnpm, that the integration tests need a Docker Postgres or that you told it three sessions ago to stop touching the migrations folder. CLAUDE.md is the fix: a plain markdown file that gets loaded into context at session start, so the agent begins every conversation already knowing how your project works. I run mine on an Ubuntu 24.04 VPS, but everything here applies identically on macOS and Windows.
This guide covers what /init generates, the full file hierarchy with load order, imports, path-scoped rules, the automatic memory feature and my opinion on why most CLAUDE.md files are three times longer than they should be. If you haven't got the CLI running yet, the Claude Code install guide for Ubuntu gets you there in about two minutes.
Generate a starter CLAUDE.md with /init
Open a session in your project root and run:
cd ~/projects/acme-api
claude
/initClaude analyzes the codebase (package manifests, build scripts, directory layout, existing docs) and writes a starter CLAUDE.md with build commands, test instructions and the conventions it can infer. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting your work. The generated file is a decent skeleton and a bad final product, because Claude can only infer what's visible in the repo. It can't know that the staging database resets every night or that one flaky test is fine to ignore. You add that part.
Rerun /init after structural changes: a new package in a monorepo, a switch from npm to pnpm, a test framework migration. For small updates, just edit the file directly. It's markdown, nothing more.
The CLAUDE.md file hierarchy and load order
Claude Code reads memory files from four levels, loaded in this order, per the official memory documentation:
Managed policy comes first. On Linux that's /etc/claude-code/CLAUDE.md, deployed by an admin, and individual users can't override it. Unless you're the one writing company policy, you'll never touch this level.
User memory lives at ~/.claude/CLAUDE.md and loads in every project you open. Mine is short: preferred shell habits, "ask before adding new dependencies" and a note that I want commit messages in imperative mood. Anything project-specific does not belong here, tempting as it is.
Project memory is ./CLAUDE.md in the repo root (or ./.claude/CLAUDE.md if you'd rather keep the root tidy). This is the file /init creates, it's checked into git and it's where 90% of your effort should go, because it's the only level your teammates benefit from.
Local project memory is ./CLAUDE.local.md, for personal notes that don't belong in version control: your sandbox URLs, the test account you use, a reminder that your machine needs nvm use 22 first. Add it to .gitignore.
On top of these, any subdirectory can carry its own CLAUDE.md. Those nested files load on demand, only when Claude reads files in that part of the tree. In a monorepo this is the difference between one bloated root file and a lean root plus a focused packages/billing/CLAUDE.md that only costs tokens when billing code is in play.
Example CLAUDE.md for a Node.js API
Here's a trimmed version of the file I use on an Express and Prisma project, which you can adapt directly:
# acme-api
Node 22 Express API with Prisma and PostgreSQL 16. Package manager is pnpm, never npm.
## Commands
- pnpm dev: start with hot reload on port 3000
- pnpm test: unit tests (vitest)
- pnpm test:integration: needs Docker Postgres, start it with pnpm db:up first
- pnpm lint and pnpm typecheck must both pass before a task counts as done
## Conventions
- TypeScript strict mode. No `any` without a comment explaining why
- Route handlers in src/routes stay thin; logic goes in src/services
- All errors flow through AppError (src/lib/errors.ts), no raw throws
- Schema changes go through prisma migrate dev, never hand-edited SQL
## Things you keep getting wrong
- Tests are vitest, not jest. There is no jest.mock() here
- The dev server is already running in another terminal. Do not start a second one
- .env is gitignored and off limits; .env.example is the referenceThat last section earns its keep more than the other two combined. Every project has two or three mistakes the model repeats, and naming them bluntly in the file kills the loop. Write the instruction the way you'd write it for a sharp new hire on day one: specific, testable and with the reason attached when the rule looks arbitrary.
Split large files with @path imports
CLAUDE.md supports imports with an @ prefix:
See @README.md for the project overview.
## Extended docs
- API conventions: @docs/api-conventions.md
- Git workflow: @docs/git-workflow.mdImports resolve recursively up to 4 hops deep, and the syntax is ignored inside code blocks (so a code sample containing @user/handle won't trigger a file read). Two things to know before you get import-happy. Imported content still costs context tokens, every session, exactly as if you'd pasted it inline, so importing your whole docs folder is a tax with no refund. And a broken path fails quietly rather than loudly, which is one of the reasons the debugging commands below exist.
Path-scoped rules in .claude/rules
Rules files solve the token problem more elegantly than imports. Drop markdown files into .claude/rules/ with a paths glob in the frontmatter:
---
paths:
- "src/api/**/*.ts"
---
All endpoints validate input with zod schemas from src/schemas.
Return 422 on validation failure, never 400.A rule like this loads only when Claude works with matching files. Your frontend conventions stay out of context during backend work and the reverse, which keeps sessions cheaper and instructions sharper. On a project with more than a handful of conventions, I'd move everything path-specific out of CLAUDE.md and into rules, leaving the root file for commands and truly global facts.
Auto memory and MEMORY.md
Separate from anything you write by hand, Claude Code maintains its own notes. As it works, it records durable observations (a quirky build step, a dependency pin, the reason a test is skipped) into MEMORY.md under ~/.claude/projects/<project>/memory/. The first 200 lines, capped at 25KB, load automatically each session.
Run /memory to see and edit what it has collected. Worth doing every few weeks; I've found genuinely useful entries in there alongside notes about problems solved months ago. The feature is governed by the autoMemoryEnabled setting if you'd rather run without it.
Debug an instruction Claude ignores
When an instruction isn't being followed, resist rewriting it in angrier capitals and check what's loaded first. /memory lists every memory file in play with its source level, which catches the classic failure: the instruction sits in CLAUDE.local.md on your laptop while you're debugging on the server, or in a nested file whose directory Claude hasn't touched yet.
/context shows the same information from the token side: a breakdown of what's occupying the context window and what each piece costs. If CLAUDE.md plus imports eat a five-figure chunk of tokens before you've typed a word, instructions start competing with each other for the model's attention and compliance drops. I covered what that costs in real money in the guide to Claude Code costs and usage limits.
Keep CLAUDE.md short
Every line in CLAUDE.md is prepended to every conversation, so a 400-line file means the model processes 400 lines before reading your request. The practical ceiling is lower than people think. My root files run 30 to 60 lines, and when I inherit a bloated one, half of it is restating defaults the model already follows ("write clean code", "add comments where helpful") and the other half is stale.
My pruning test is simple: would removing this line change the model's behavior on a real task this week? Commands, conventions and known mistakes pass. Aspirations don't. And for rules where compliance has to be guaranteed rather than requested, a memory file is the wrong tool anyway; that's what Claude Code hooks are for, since a hook blocks the action instead of politely suggesting against it. Instructions in CLAUDE.md are strong hints. The model follows them the vast majority of the time, and "vast majority" is exactly the phrase you don't want attached to "never run destructive migrations".
A good CLAUDE.md compounds quietly. Each mistake you record is one you stop seeing, and after a month the file reads like a map of everything non-obvious about your project, which pays off again the moment you start exploring the rest of the toolchain in our guide on how to use Claude Code. The changelog on the Claude Code GitHub repo is worth watching too, since the memory system has been picking up features steadily through the 2.x line.
