CLAUDE.md: project memory

What you’ll be able to do

Create and maintain a CLAUDE.md file that makes every session in your project start with the right knowledge, so you stop repeating the same instructions and corrections.

Why this matters

Every Claude Code conversation starts with an empty context window. Without help, Claude has to rediscover your project each time: how to run the tests, which libraries you prefer, which folder must never be edited. You end up typing the same instructions again and again, and when you forget one, Claude makes a reasonable but wrong assumption.

CLAUDE.md solves this. It’s a plain Markdown file that Claude Code loads automatically at the start of every session in that project. Think of it as the onboarding note you’d give a new teammate on their first day: short, practical, and about this project.

Where CLAUDE.md files live

You can have several, each with a different scope. Claude Code loads all the ones that apply and combines them:

Location	Scope	Commit it to git?
./CLAUDE.md or ./.claude/CLAUDE.md	This project, everyone	Yes
./CLAUDE.local.md	This project, just you	No (gitignore it)
~/.claude/CLAUDE.md	All your projects	n/a
subfolder/CLAUDE.md	Loaded when Claude works with files in that folder	Yes

In practice: put team knowledge in the project’s CLAUDE.md and commit it, so everyone, and every Claude session, shares it. Put personal preferences for one project, such as your local test database URL, in CLAUDE.local.md and add it to .gitignore. Put preferences you want everywhere, such as “explain changes briefly”, in ~/.claude/CLAUDE.md in your home folder.

CLAUDE.md vs auto memory

Claude Code has a second, automatic kind of memory. Auto memory is notes Claude writes itself as it learns from your corrections and preferences during work. It’s stored per repository on your machine and also loaded at the start of each session.

	CLAUDE.md	Auto memory
Written by	You	Claude
Contains	Rules and instructions	Learnings and patterns
Best for	Things that must always be true	Preferences picked up along the way

Run /memory to open your CLAUDE.md files for editing, view what auto memory has recorded, or turn auto memory on and off.

Step 1: Generate a starting point

In a real project you work on, start Claude Code and run:

/init

What you’ll see: Claude explores the repository (the README, package or build files, folder structure, test setup) and writes a draft CLAUDE.md with the commands and conventions it found. If /init finds configuration from another coding agent, it offers to carry that over too.

Treat the result as a first draft. It’s usually too long and mixes useful facts with things Claude could work out by reading the code anyway.

Step 2: Edit it down to what matters

Everything in CLAUDE.md is loaded into every session, so every line costs context and competes for attention. A good CLAUDE.md is usually under a page. Keep what Claude can’t easily discover by itself:

• Commands: how to build, run the tests (including a single test file), lint, and run the app locally.
• Conventions you’d enforce in review: “use zod for validation”, “prefer named exports”, “dates are always UTC”.
• Gotchas: “the legacy/ folder is frozen”, “migrations must be reversible”, “integration tests need Docker running”.
• Workflow rules: “run the type checker before saying a task is done”, “branch names start with feat/ or fix/”.

Cut:

• Anything obvious from reading the code. Claude will see it anyway.
• Long explanations. Link to a doc in the repo instead.
• Generic advice (“write clean code”). It’s too vague to act on.

Here’s an example of a compact, effective file:

# Project: storefront-api

## Commands
- `pnpm dev`: run locally on :3000
- `pnpm test`: all tests · `pnpm test -- path/to/file`: one file
- `pnpm typecheck && pnpm lint`: run before saying a task is done

## Conventions
- Validation with zod schemas in `src/schemas/`, never ad-hoc checks
- DB access only through repositories in `src/repos/`
- No new dependencies without asking

## Gotchas
- `src/generated/` is produced by `pnpm codegen`. Never edit it by hand.

Notice how each line is a concrete fact or rule that Claude can act on directly, and how the most important rule (“never edit by hand”) explains why, so Claude can also handle situations the rule doesn’t spell out.

Step 3: Keep it alive

A CLAUDE.md is never finished. The best time to update it is when you catch yourself correcting Claude for the second time about the same thing. You can ask Claude to add the rule itself:

Add to CLAUDE.md: integration tests need `docker compose up -d db` first.

Or open the file with /memory and edit it yourself.

Over time, files collect outdated or contradictory rules, for example “use Jest” from last year next to “use Vitest” from this month. When two instructions contradict each other, Claude may follow either one. Run this every so often:

/doctor prompt-audit

What you’ll see: a report of contradictions, stale references to files or commands that no longer exist, and duplicated rules across your instruction files.

Exercise

1. In a real project, run /init and review the draft. What you’ll see: a new CLAUDE.md in the project root.
2. Cut the draft by at least a third, keeping commands, conventions and gotchas.
3. Add one gotcha that only you know about, something a new teammate would trip over.
4. Run /clear (so the conversation memory is gone), then ask: “How do I run a single test file here, and what must I never edit?” What you’ll see: Claude answers immediately from CLAUDE.md, without searching the codebase. That’s the file doing its job.
5. Commit CLAUDE.md so the rest of your team (and their Claude sessions) benefit.

Common mistakes

• Keeping /init’s draft unedited. It’s a starting point; long files waste context in every session.
• Writing vague rules. “Write good tests” can’t be acted on. “Every new function gets a unit test next to it” can.
• Relying on CLAUDE.md for hard limits. Use permissions or hooks for anything that must never happen.
• Putting secrets in it. It’s shared through git.
• Never revisiting it. Outdated rules mislead Claude; run /doctor prompt-audit from time to time.

Verify it worked

• Your project has a CLAUDE.md of roughly a page or less
• It includes the test commands (including running a single test) and at least one gotcha
• After /clear, Claude answered your project-convention question from the file
• The file is committed, and nothing personal or secret is in it