CLAUDE.md: The Complete Guide to Claude Code Memory (2026)

Ask experienced Claude Code users for the single highest-leverage thing you can add to a project, and most will give the same answer: a good CLAUDE.md. It is a plain Markdown file that Claude Code reads automatically at the start of every session, and it is the difference between an agent that guesses at your conventions and one that already knows them. This guide covers what CLAUDE.md is, where Claude Code looks for it, exactly what to put inside, and the habits that make it pay off.

What is CLAUDE.md?

CLAUDE.md is Claude Code's project memory. When you start a session, the agent reads the file before doing anything else, so its contents act like standing instructions for the whole conversation. Think of it as the onboarding document you would hand a new engineer on their first day — except Claude Code re-reads it every single time, never forgets it, and never skims.

Because it lives in your repository, CLAUDE.md is durable and shared. It travels with the code through version control, so every teammate — and every future session — gets the same context for free. That persistence is what separates it from a one-off prompt. If you are new to the tool, the what is Claude Code guide covers the fundamentals; this article goes deep on the memory file specifically.

Why the memory file matters so much

An agent is only as good as the context it operates in. Without a memory file, Claude Code has to infer your conventions from the code it happens to read, which means it can pick the wrong test runner, follow a style you abandoned two refactors ago, or re-ask something you have already answered three sessions in a row. A good CLAUDE.md removes that friction by stating the rules once, authoritatively.

The payoff compounds. Every fact you write down — the command that runs the tests, the directory that is off-limits, the library you standardized on — is a mistake the agent no longer makes and a question it no longer asks. Over a week of sessions that adds up to markedly more consistent output and far less babysitting.

Where Claude Code looks for memory

Claude Code does not read just one file. It layers several, from broad to specific, and more specific files take precedence when they overlap:

• Project memory — CLAUDE.md at your repository root. This is the main one, committed to git and shared with the team.
• User memory — ~/.claude/CLAUDE.md in your home directory. Personal preferences that apply to every project you work on, like your preferred commit style.
• Subdirectory memory — a CLAUDE.md inside a specific folder. Claude Code pulls it in when it works on files in that part of the tree, which is ideal for a monorepo package or a module with its own rules.
• Local overrides — CLAUDE.local.md for personal notes you do not want to commit. Keep it out of version control with .gitignore.

The layering means you can keep the shared file lean and push niche details down to where they are relevant, instead of bloating the root file with rules that only apply to one corner of the codebase.

How to create one in seconds

You do not have to start from a blank page. Inside any project, run the built-in command:

/init

Claude Code scans the repository — its structure, dependencies, scripts, and conventions — and writes a first-draft CLAUDE.md for you. The draft is a scaffold, not a finished product: read it critically, delete the filler, and keep the handful of rules that genuinely change how the agent should behave. A tight, hand-edited file beats a long auto-generated one every time.

What to put in CLAUDE.md

Focus on the things that are not obvious from reading a single file. The most useful sections are:

• Commands — how to install, build, test, lint, and run. Exact invocations, so the agent never guesses.
• Architecture — the high-level shape of the project and where the important pieces live.
• Conventions — naming, formatting, error handling, and the patterns you want followed.
• Do-not-touch rules — generated files, protected paths, and things the agent should never edit or run.
• Gotchas — the non-obvious traps that trip up newcomers, human or otherwise.

Here is a compact example that shows the right altitude — specific enough to be useful, short enough to stay cheap:

# CLAUDE.md

## Commands
- Install: pnpm install
- Dev server: pnpm dev
- Run tests: pnpm test (Vitest). A single file: pnpm test path/to/file
- Lint + typecheck: pnpm check  (run this before every commit)

## Architecture
- Next.js App Router. Routes live in src/app; shared UI in src/components.
- Data access goes through src/lib/db.ts only — never import the client directly.

## Conventions
- TypeScript strict. No 'any'. Prefer named exports.
- Use the existing Button/Input primitives; do not add a new UI library.

## Do not
- Edit anything in src/generated/ — it is produced by codegen.
- Commit .env or secrets. Read config from src/lib/env.ts.

Notice what is absent: no restating of what the framework does, no essay on why tests matter. Every line is a decision the agent would otherwise get wrong.

Best practices for a memory file that works

• Keep it short and high-signal. The file is loaded on every session, so it competes for the same context budget as your actual task. Ruthlessly cut anything the agent can infer on its own.
• Be specific and imperative. Write "run pnpm check before committing," not "please try to keep the code tidy." Concrete rules are followed; vague aspirations are ignored.
• Treat it as living documentation. When you correct Claude Code on the same thing twice, that correction belongs in CLAUDE.md. The file should grow out of real friction, not speculation.
• Push niche rules down. Module-specific details go in a subdirectory CLAUDE.md, keeping the root file focused on what everyone needs.
• Pair it with settings. CLAUDE.md tells the agent what to do; a settings.json file controls what it is allowed to do. Read the settings and permissions guide to lock in guardrails, and browse ready-made configs in the settings catalog.
• Commit it. A memory file in git means the whole team — and code review — benefits from and vets the same rules.

Common mistakes to avoid

Two failure modes are worth calling out. The first is the kitchen-sink file: a sprawling document that documents everything and therefore emphasizes nothing. If the agent has to wade through three screens of prose to find the test command, the file is working against you. The second is the stale file: rules that describe the project as it was six months ago. An out-of-date CLAUDE.md is worse than none, because the agent trusts it. Review it whenever your build or conventions change.

How CLAUDE.md fits the bigger picture

Memory is one layer of Claude Code's customization stack, and it works best alongside the others. Delegate focused work to specialized subagents, automate repeated prompts with slash commands, and package reusable know-how as skills. The memory file is the connective tissue that makes all of them behave consistently, because they all inherit the same project context.

Where to go next

• What Is Claude Code? The Complete Guide
• Claude Code Settings and Permissions
• Claude Code Best Practices: 12 Tips
• The full Claude Code catalog

Start with /init, cut the result down to the rules that matter, and refine it every time you catch yourself explaining the same thing twice. A focused memory file is the cheapest, highest-return investment you can make in a Claude Code workflow.