CLAUDE.md Explained: How to Give Claude Code Memory of Your Project

CLAUDE.md is a plain Markdown file that Claude Code reads at the start of every session. It is how you give Claude Code a memory of your project: your build and test commands, coding rules, folder layout and "always do X" habits. Put one at the root of your project (./CLAUDE.md), run /init to generate a first draft, keep it under about 200 lines, and Claude will follow it in every new session without you repeating yourself. This guide explains where the file goes, what to write, and how it works with Claude Code's newer auto memory, as of October 2026.

Why does Claude Code need a CLAUDE.md file?

Every Claude Code session starts with a fresh context window. Claude does not remember what you told it yesterday. Without help, you would explain your project again and again.

Anthropic's docs describe two ways to carry knowledge across sessions:

Both are loaded at the start of every conversation. Think of CLAUDE.md as the onboarding note you would give a new teammate.

Where do I put CLAUDE.md?

You can have several CLAUDE.md files. Each has a different reach. Claude Code loads them from broadest to most specific:

For most people, two files are enough: a project CLAUDE.md in the repo, and a personal ~/.claude/CLAUDE.md for habits you want everywhere.

How do I create a CLAUDE.md file?

The fastest way is to let Claude write the first draft.

1. Open your project in a terminal and start Claude Code:

cd your-project
claude

2. Run the init command:

/init

3. Claude analyzes your codebase and creates a CLAUDE.md with build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.
4. Open the file and edit it. Add the things Claude could not discover on its own.
5. Check that it loaded. Run /context and look for the file under Memory files.

Want a more guided setup? Set the CLAUDE_CODE_NEW_INIT environment variable to 1 before running /init. It then asks which things to set up (CLAUDE.md files, skills and hooks), asks follow-up questions, and shows you a proposal before writing anything.

You can also open and edit any memory file from inside a session with /memory. Or just ask: "add this to CLAUDE.md".

What should I write in CLAUDE.md?

Anthropic's rule of thumb: write down what you would otherwise re-explain. Add a line when:

• Claude makes the same mistake a second time
• A code review catches something Claude should have known
• You type the same correction you typed last session
• A new teammate would need the same context

Keep it to facts Claude needs in every session: build commands, conventions, project layout and firm rules.

Be concrete. Anthropic's own examples:

Here is a short example for a web app:

# Project: Shop API

## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Tests: `npm test` (run before every commit)
- Lint: `npm run lint`

## Conventions
- TypeScript strict mode. No `any`.
- Use 2-space indentation.
- API handlers live in `src/api/handlers/`.

## Rules
- Never edit files in `src/generated/`. They are rebuilt by `npm run codegen`.
- Ask before changing the database schema.

## Compact instructions
When you are using compact, focus on test output and code changes.

That last section matters. Anthropic notes you can tell Claude what to keep when it summarizes a long conversation.

How long should CLAUDE.md be?

Anthropic recommends under 200 lines per CLAUDE.md file. Longer files use more context and Claude follows them less reliably.

Three ways to stay lean:

1. Move long procedures into skills. A skill loads only when it is used, so a 50-line deploy checklist costs almost nothing until you need it. See our guide to Claude Code skills, hooks and slash commands.
2. Use path-scoped rules for instructions that only matter in part of the codebase (see below).
3. Run an audit. /doctor prompt-audit checks your instruction files for outdated or conflicting content and proposes edits. It needs Claude Code v2.1.283 or later.

Shorter files also save money, since CLAUDE.md is sent with every request. Our Claude Code cost guide covers this.

Tip: HTML comments like <!-- note for humans --> are stripped before Claude sees the file. Use them for maintainer notes that cost no tokens.

How do I import other files into CLAUDE.md?

Use @path/to/file anywhere in CLAUDE.md. The imported file loads at launch with it.

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

A few rules from the docs:

• Relative paths resolve from the file that contains the import.
• Imports can nest up to four levels deep.
• Wrap a path in backticks if you want to mention it without importing it.
• The first time a project imports a file from outside the project folder, Claude Code asks you to approve it.

Imports help organize a long file. They do not reduce context, because imported files still load at launch.

How do CLAUDE.md files load in subfolders?

Claude Code reads CLAUDE.md and CLAUDE.local.md from your current folder and every folder above it. Run Claude in foo/bar/ and it loads both foo/CLAUDE.md and foo/bar/CLAUDE.md.

The files are joined together, not overridden. The file closest to where you started is read last.

CLAUDE.md files in subfolders below you load on demand. They load once Claude reads or edits a file in that subfolder. This is handy in a monorepo: put frontend rules in frontend/CLAUDE.md and they only appear when Claude works there.

What are .claude/rules and path-specific rules?

For bigger projects, split instructions into topic files under .claude/rules/:

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md

Add paths frontmatter to make a rule load only for matching files:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format

Rules without paths load every session. Personal rules for all projects go in ~/.claude/rules/.

Does Claude Code read AGENTS.md?

Yes, since v2.1.277. If your repo has an AGENTS.md and no CLAUDE.md or CLAUDE.local.md, Claude Code reads AGENTS.md instead. If both exist, it reads only CLAUDE.md by default.

To keep one shared file for every coding tool, put this in a CLAUDE.md next to it:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

This is useful if your team also uses Cursor or Copilot. Both can read AGENTS.md too, as we cover in Claude Code vs Cursor vs GitHub Copilot. And when you run /init, Claude Code pulls in relevant parts of .cursor/rules/, .cursorrules and .github/copilot-instructions.md.

What is auto memory, and how is it different?

Auto memory is the second system. Claude writes it, not you. When you correct Claude or state a preference, it may save a short note.

• Notes live in ~/.claude/projects/<project>/memory/.
• A MEMORY.md index in that folder loads every session (the first 200 lines or 25KB, whichever comes first).
• Other topic files load only when Claude needs them.
• Auto memory stays on your machine. It is not shared with your team.

Say "remember that the API tests need a local Redis instance" and Claude saves it to auto memory. Say "add this to CLAUDE.md" if you want it in the shared project file instead. Toggle auto memory on or off in /memory.

Why is Claude ignoring my CLAUDE.md?

CLAUDE.md is guidance, not a hard rule. Claude reads it and tries to follow it, but vague or conflicting instructions can slip. Try this checklist:

1. Run /context and confirm the file is listed under Memory files.
2. Make the instruction specific and checkable.
3. Look for conflicts between your user file, project file and rules.
4. If something must happen every time, such as formatting after each edit, use a hook. Hooks run as shell commands and do not depend on Claude's choices.

After /compact, the project-root CLAUDE.md is re-read from disk, so it survives. Instructions given only in chat do not. Move them into CLAUDE.md if you want them to stick.

Frequently asked questions

Where is the CLAUDE.md file located? The project file goes at ./CLAUDE.md or ./.claude/CLAUDE.md in your repo. Your personal file goes at ~/.claude/CLAUDE.md. Private project notes go in ./CLAUDE.local.md.

Should I commit CLAUDE.md to git? Yes, commit the project CLAUDE.md so your team shares it. Do not commit CLAUDE.local.md. Add it to .gitignore.

Does CLAUDE.md use up tokens? Yes. It loads into context at the start of every session. That is why Anthropic recommends keeping each file under 200 lines and moving long procedures into skills.

What is the difference between CLAUDE.md and auto memory? You write CLAUDE.md to give instructions. Claude writes auto memory to record what it learned from you. Both load every session.

Can I have more than one CLAUDE.md? Yes. Claude Code combines files from your user folder, the project root, parent folders and subfolders. Files in subfolders load when Claude works in them.

How do I edit CLAUDE.md from inside Claude Code? Run /memory and pick the file, or ask Claude "add this to CLAUDE.md".

Learn the full Claude Code workflow for free

A good CLAUDE.md is one of the biggest upgrades you can make. If you are just starting, read our beginner's guide to installing Claude Code, then take the free course Claude Code from Zero. It shows you how to set up project memory, write better prompts and build a setup that grows with your work.

Sources

• Claude Code docs: How Claude remembers your project (CLAUDE.md and auto memory)
• Claude Code docs: Commands
• Claude Code docs: Manage costs effectively
• Claude Code docs: Overview