What Is CLAUDE.md? The Persistent Project Memory File for Claude Code

Trackline Academy · Updated July 30, 2026 · All articles

CLAUDE.md is a plain-text markdown file of standing instructions that Claude Code reads automatically at the start of every session. You write down the things you'd otherwise re-explain constantly (your conventions, key project facts, the commands that matter, and your do/don't rules), and Claude shows up to every conversation already knowing them. There's nothing to compile, no special syntax, nothing to "run." It's a sticky note for your project that Claude always reads first.

The reason it exists: Claude Code starts each new session with an empty memory of your past conversations. It doesn't recall what you discussed yesterday. Without a CLAUDE.md, that means re-typing the same context every day: "receipts go in the Receipts folder," "always ask before deleting," "we use pnpm here." Write those lines once in CLAUDE.md and they load automatically, every session, forever. It's the single highest-leverage file in any Claude Code project.

How CLAUDE.md actually works

When you launch Claude Code, you open it inside a particular folder. That folder is effectively your project. Claude can read and edit files there, and its memory is tied to that folder. At session start, Claude Code looks for instruction files and loads them into context before you type a single word. Open Claude in your invoicing project and you get invoicing context; open it in a different repo and you get a completely separate set of notes. Nothing leaks between projects unless you set it up that way.

One important nuance: CLAUDE.md is context Claude tries to follow, not enforced configuration. It's remarkably effective for shaping behavior, but if you need something guaranteed (say, blocking a dangerous command outright), that's a job for a hook or a managed setting, not a line in CLAUDE.md.

What goes in it: conventions, commands, guardrails

The best CLAUDE.md files are short and concrete. Everything worth writing falls into three buckets:

Preferences and conventions: how you like the work done. "Write in plain language, no jargon." "Name files like 2026-06-receipt.pdf." "Use TypeScript strict mode; prefer named exports."
Project facts: things Claude would otherwise have to ask about or rediscover. "Receipts live in /Receipts, named by date." "The API client lives in src/lib/api.ts." The build, test, and run commands for this repo.
Do/don't rules (guardrails): "Always ask before deleting or overwriting a file." "Never commit directly to main." "Never email anyone without showing me the draft first."

These are exactly the things you'd tell a new assistant on day one. Vague lines underperform: "name files nicely" does almost nothing, while "name files like 2026-06-receipt.pdf" changes behavior visibly. Concrete one-liners beat paragraphs every time.

Keep it well under a page. A short, sharp CLAUDE.md produces more reliable behavior than a giant one. Every line enters Claude's context window in every single session, so every line has to earn its place. Trim ruthlessly: if a fact only matters occasionally, it probably doesn't belong here.

A starter template you can copy

Paste this into a file named CLAUDE.md at your project root and fill in the brackets:

# Project: [one-line description of what this folder is] ## Commands - Build: [your build command] - Test: [your test command] - Run locally: [your dev/run command] ## Conventions - [e.g., "Use plain, friendly language in anything user-facing"] - [e.g., "Name files like 2026-06-receipt.pdf"] - [e.g., "Prefer small, focused functions; match existing code style"] ## Project facts - [e.g., "Client data lives in /data, one folder per client"] - [e.g., "The config that matters is settings.json at the root"] ## Do / Don't - Always ask before deleting or overwriting a file. - [e.g., "Never commit directly to main"] - [e.g., "Never send anything external without showing me a draft"]

You don't even have to write it by hand. Run the built-in /init command and Claude drafts a starter file from what it sees in your project. Then you just review and trim. Or say it in plain language mid-session: "add this to CLAUDE.md" and Claude updates the file for you.

Learn Claude Code the structured way

CLAUDE.md is one module of many. The free fundamentals track of The Claude AI Course walks you from first prompt to confident daily workflows, no coding background required.

Start the free course

Where CLAUDE.md lives: project vs. global scope

The same kind of file can live in a few places, and the difference is scope:

Project file: ./CLAUDE.md (or ./.claude/CLAUDE.md) inside the project folder. Facts and rules for this project. If you share the folder or repo, teammates get it too.
User/global file: ~/.claude/CLAUDE.md in your personal Claude folder. Your own preferences across all projects, just for you.
Local private file: ./CLAUDE.local.md for per-project notes you don't want to share; add it to .gitignore.

Both project and global files load into every session, so your personal style and the project's facts arrive together. The rule of thumb: personal preferences go global; project facts go in the project file. "I like plain language" belongs to you everywhere. "Invoices live in /Billing" belongs to one project.

Claude Code also walks up the directory tree from wherever you launched, concatenating any CLAUDE.md files it finds, and organizations can add a managed policy file that loads for everyone. Files in subdirectories aren't loaded at launch. They load on demand when Claude works in those folders. The net effect is that instructions closest to your working directory are read last and tend to win when there's overlap. To see exactly which files are in effect right now, run /memory.

How it changes daily use

Once a good CLAUDE.md is in place, the day-to-day feel of Claude Code changes noticeably:

Zero warm-up. You open a session and give the actual task. No "first, some context about this project" paragraph.
Guardrails without nagging. Claude pauses to ask before destructive actions because the file says so. You never told it in chat.
Consistency across sessions. File naming, tone, and conventions stay stable whether it's Monday's session or Friday's.
It survives context cleanup. Long chats fill the context window. /clear starts fresh (the old conversation stays saved and resumable) and /compact summarizes history so you can keep going, and in both cases your CLAUDE.md is still there. The project-root file is re-read and re-injected even after compaction, which is exactly why durable rules belong in the file: an instruction you only typed in chat is the first thing to evaporate.

A related habit: whenever you catch yourself typing the same instruction a second time in chat, promote it to CLAUDE.md on the spot. That one reflex is most of the skill.

CLAUDE.md vs. auto memory

Claude Code can also keep its own notes across sessions, called auto memory: learnings it decides are worth saving (a build command, a recurring preference), stored per project with a concise index that loads at session start. The distinction is ownership: saying "remember that I prefer pnpm" nudges Claude to save it to its own memory, while "add this to CLAUDE.md" puts it in the file you author and control. Both are plain markdown you can audit or edit, and /memory shows you everything that's loaded.

When the file gets big

If your CLAUDE.md grows unwieldy, two patterns keep it lean. Path-scoped rules in a .claude/rules/ folder load only when Claude touches matching files, keeping specialized context out of the way until it's relevant. And the @path/to/file import syntax pulls other files into CLAUDE.md at launch (good for organization), though imported files still consume context, so they don't save tokens the way path-scoped rules do.

A 15-minute way to prove it works

Open Claude Code in a low-stakes practice folder.
Create a CLAUDE.md with at least one preference, one project fact, and one observable rule like "always ask before deleting or overwriting a file."
Start a new session so the file loads fresh, then ask Claude to do a small task that touches the rules: "tidy up the file names in this folder" works well.
Watch it pause and ask before changing anything, without being told in chat. That's the moment CLAUDE.md clicks.
Refine: turn anything Claude got wrong into a more specific line, delete anything unnecessary, and re-run.

Your first draft is never your best one. The strongest CLAUDE.md files are tuned after watching how Claude actually behaves: add specifics where it drifted, cut lines that turned out not to matter.

FAQ

Does CLAUDE.md work automatically, or do I have to load it?

Automatically. Claude Code reads it at the start of every session in that folder: no command, no flag, no reminder needed. That's the whole point: the context is in place before you type your first message. Use /memory if you want to confirm which instruction files are currently loaded.

What's the difference between CLAUDE.md and just telling Claude in chat?

A chat instruction lives only in that one conversation: start a new session (or trim a long one) and it's gone. CLAUDE.md is reloaded from disk every session and persists through compaction, so it's the durable home for anything you want Claude to always know.

Do I need to be a programmer to use CLAUDE.md?

No. It's plain language in a plain-text file. "Tax documents live in the /Taxes folder, organized by year" and "always ask before deleting anything" are perfectly good CLAUDE.md lines. Non-coders managing documents, receipts, or planning folders get just as much value as developers do, something we lean into heavily at Trackline Academy.

Related guides

Build your first CLAUDE.md with guided practice

The free track of The Claude AI Course includes hands-on modules on Claude Code, memory, and context, with tasks you complete on your own machine and check against clear success criteria.

Take the free fundamentals course