Claude.md File: What It Is and Why Every Project Needs One

You have explained your project to Claude Code before. The stack, the commands, the one folder it must never touch, the reason that weird retry loop exists. Then you closed the session, opened a new one the next morning, and had to explain all of it again. A CLAUDE.md file is the fix. It is a plain markdown file that Claude Code reads at the start of every session and treats as standing instructions, so the context you would otherwise retype is already loaded before you say a word. This is what it is, where it lives, how it actually loads, and why every serious project should have one.

Key takeaways

• A CLAUDE.md file is a plain markdown file Claude Code reads automatically at the start of each session and folds into its context as standing project instructions.
• It exists because Claude Code has no memory between sessions by default. Without it, every session starts from zero.
• It can live at several levels (project root, home directory, subdirectories) and Claude combines them, with the closer file taking precedence.
• Keep it lean and specific. Everything in it competes for the model's attention, and Anthropic guidance points to well under 200 lines.
• A CLAUDE.md file tells the AI HOW to work in this repo. It is not built to hold your evolving facts and decisions, and neither one stays current unless something keeps it current.

---

What a CLAUDE.md file is

CLAUDE.md is a plain markdown file that Claude Code, Anthropic's command-line coding tool, looks for when it starts a session in a directory. If it finds one, it reads the whole file and loads the contents into context before your first message. Practically, the file becomes part of the standing instructions the model works from for that session, the same way a system prompt does. You write it once in plain text, and it applies to every session going forward until you change it.

The reason this matters is simple: by default, Claude Code does not remember anything between sessions. Close the window, open a new one, and you are talking to a fresh instance that has never seen your project. It does not recall the decisions you made yesterday, the conventions you agreed on, or the mistake you corrected twice last week. CLAUDE.md is the mechanism Anthropic built into the tool to close that gap: the one piece of persistent, session-to-session context you write and control directly.

The mental model that helps: it is the onboarding note you would write for a sharp contractor who is a strong engineer but has never seen your codebase. You do not teach them to code. You tell them the few things specific to your project that would otherwise cost them a day of poking around to discover.

Why every project needs one

"Every project" sounds like a stretch until you count the cost of not having one. Here is what a CLAUDE.md file actually buys you.

• You stop repeating yourself. The build command, the test command, the "we use pnpm not npm" detail: you write each once instead of at the top of every prompt.
• Claude runs the right commands. When the file states the exact test and lint commands, Claude uses them instead of guessing a plausible-but-wrong one. Its ability to verify its own work depends on knowing how you verify yours.
• It stops repeating your mistakes. The highest-value lines in most files are corrections. Every time the AI makes the same wrong move twice, you write the fix once, and it stops.
• Your team shares one brain. A committed CLAUDE.md means every developer's Claude Code follows the same conventions, so new hires inherit the project's tribal knowledge on day one.
• Output gets specific to you. Generic output is the default when the model knows nothing about your situation. Project context is the cheapest lever on making the output fit your actual codebase.

A project with no CLAUDE.md is not neutral. It is one where you pay the explanation tax every session, and where Claude guesses at things you could have simply told it.

Where a CLAUDE.md file lives

Claude Code checks several locations, and they stack rather than compete. The closer file adds detail to the broader one, and when two files conflict, the more specific location wins.

Two details that trip people up. First, the filename is case-sensitive: it must be exactly CLAUDE.md, uppercase name and lowercase extension. Second, in a monorepo Claude reads the file closest to the code it is working on, so a /frontend/CLAUDE.md and a /backend/CLAUDE.md can carry different conventions without stepping on each other. On Windows, ~/.claude resolves to %USERPROFILE%\.claude.

How it actually loads

The loading behavior is worth understanding because a couple of its quirks cause real confusion.

Claude reads CLAUDE.md at the start of a session. That means edits you make to the file during an active session are not picked up automatically. If you change a rule mid-session, start a fresh session for it to take effect. A quick way to confirm the file loaded at all: open a new session and ask Claude what your CLAUDE.md says.

The instructions are guidance, not enforcement. Claude treats the file as strong context, not as a hard gate. If you need to truly block an action no matter what the model decides, that is what a tool-use hook is for, not a line in CLAUDE.md. The file shapes behavior; it does not police it.

The file also competes for context. Everything in it is loaded into the same window Claude uses to do your actual work. A tight file leaves more room for the task; a bloated one both dilutes your important rules and eats the budget the model needs to think. Anthropic's guidance points to keeping each file well under 200 lines, and in practice a 50-to-100-line root file with the details pushed into path-scoped rules works better than one long file.

For larger setups, CLAUDE.md supports imports with an @path/to/file syntax, so you can keep the main file lean and pull in a detailed doc only when it is relevant.

What goes in a CLAUDE.md file

There is no required format. The best files hold the durable, project-specific facts that are not obvious from reading the code:

• What the project is, in two or three lines: purpose and stack.
• Commands that matter: the exact test, dev-server, lint, and build commands.
• Conventions you always follow: "all DB access goes through queries.ts, never raw SQL in handlers."
• Things to avoid: deprecated folders, forbidden dependencies, patterns you have moved off.
• Mistakes Claude keeps making: the corrections that turn a repeated annoyance into a one-time fix.

Keep out secrets, whole pasted docs, generic advice any competent developer knows, and changelog history that belongs in git. The test for any line: would a strong engineer new to this repo need to be told this, and would it save real time? If yes, it belongs.

A minimal starter you can copy

The fastest way to create one is the built-in /init command. Run it in your project and Claude scans your codebase (package files, config, structure) and generates a starter CLAUDE.md with detected commands and conventions. Treat that as a draft, not a finished file, and trim it down.

If you would rather start by hand, here is a deliberately minimal, copyable skeleton. It is short on purpose. Every line either tells Claude how to run the project, a convention it would not know, or a mistake to avoid.

# CLAUDE.md

## Project

Internal billing service. Node + TypeScript, Postgres, deployed on Fly.
Handles subscriptions, invoices, and Stripe webhooks.

## Commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test` (run before every commit)
- Types: `pnpm typecheck`
- Lint: `pnpm lint`

## Conventions

- Money is integer cents, never floats. Use the `Money` type.
- All DB access goes through `src/db/queries.ts`. No raw SQL in handlers.
- New endpoints get a test in `test/api/` in the same PR.

## Avoid

- Do not add retry loops around `stripe.ts`. It is idempotent by design.
- The `legacy/` folder is deprecated. Do not extend it; flag if touched.

You can grow this over time, but a short file Claude actually follows beats a long one it skims. If you want the fuller treatment of structure, sections, and hygiene, that is a topic of its own; here we are focused on what the file is and why you need it.

The part every guide skips: HOW is not the same as WHAT

Here is the distinction that most CLAUDE.md explainers walk right past, and it is the reason even a perfect file leaves a gap.

A CLAUDE.md file tells the AI how to work in a project. Commands, conventions, boundaries. It is procedural, and it is about the codebase, not about you.

Your facts are a different kind of context. Who your users are, what you decided about pricing last week, why a feature exists, the reasoning from a meeting that never made it into a doc, your opinion on a library, the direction you pivoted last month. That knowledge is what makes an AI's output specific to your actual situation rather than generically correct. It does not belong in a per-project setup file, because it is not procedure and it is not scoped to one repo. It follows you across every project and every tool you use.

Both kinds of context share the same failure mode: they go stale by hand. A CLAUDE.md drifts the moment the code changes and you forget to edit the file, and then Claude confidently follows a rule that is no longer true. Your facts drift faster, because your world moves faster than your repo does, and nobody schedules a "go update all my notes" task. The difference is that a CLAUDE.md is small enough to maintain if you are disciplined. Your facts are too many and too fast-moving to keep current by editing files.

A CLAUDE.md tells the AI how. Your current facts are a separate job.

Keeping the WHAT current without babysitting it

This is where a self-maintaining memory earns its place next to a well-kept CLAUDE.md. Instead of you filing edits against your own notes, a tool like Locul builds a second brain from what you already produce (markdown files, PDFs, dictation, Notion, your LinkedIn profile) and keeps it current on your machine. When a fact changes, it marks the old one superseded and the new one active, so the AI works from the current truth. It then serves that context to Claude Code and your other tools over MCP, so the "what" travels across every tool you use, not just Claude Code.

The two pieces complement each other. Your CLAUDE.md handles the procedural HOW for a specific repo. A living memory handles the WHAT: your current facts and decisions, kept fresh without a maintenance ritual. And because most of what we work from is borrowed, you can inject a curated Memory Pack (a bundle of the best facts, opinions, and playbooks for a domain) into that brain, so a skilled operator's thinking shows up in your output the way your project conventions show up in Claude Code. For how CLAUDE.md sits alongside Claude's other forms of memory, the Claude memory guide covers the full picture.

A CLAUDE.md is only as accurate as its last edit. The facts that make your AI sound like you move faster than you can hand-edit.

Frequently asked questions

What is a claude.md file used for?

It gives Claude Code standing, project-specific instructions it reads at the start of every session: what the project is, the commands to run it, the conventions to follow, and the mistakes to avoid. It removes the need to re-explain your project every time you open a new session, and it becomes part of the context Claude works from.

Where does the claude.md file live?

At several levels that stack. The project root (./CLAUDE.md) for team-wide rules you commit to git, your home directory (~/.claude/CLAUDE.md) for personal preferences across every project, and optionally a subdirectory (./packages/x/CLAUDE.md) for rules scoped to one part of a monorepo. When files conflict, the closer, more specific one wins. The filename is case-sensitive and must be exactly CLAUDE.md.

How do I create a claude.md file?

The fastest way is to run /init inside your project. Claude Code scans your codebase and generates a starter file with the commands and conventions it detects. Treat that output as a draft: review it, cut what is generic, and add the project-specific details and corrections it missed. You can also just create the file by hand from a short skeleton.

How long should a claude.md file be?

Shorter than you expect. Everything in the file loads into the same context window Claude uses to do the work, so a long file both dilutes your important rules and eats the budget the model needs. Anthropic guidance points to keeping each file well under 200 lines. A tight 50-to-100-line root file that Claude actually follows beats a 300-line one it skims.

Is a claude.md file the same as Claude's memory?

No. CLAUDE.md is a file you write and maintain that tells Claude how to work in a project. It is procedural and repo-scoped. Claude Code separately has a memory tool it manages itself, and the consumer apps have their own cross-chat memory. Your personal facts, decisions, and evolving context are a different kind of knowledge again, and none of these keep themselves current unless something is built to do that.

Does a claude.md file work with tools other than Claude Code?

The CLAUDE.md file itself is a Claude Code convention. Other tools do not read it. That is a real limitation if you use several AI tools, because the context you put in CLAUDE.md is trapped in one tool. Facts about you and your work are more useful when they travel across every tool, which is why a memory layer served over MCP (which many AI tools can connect to) is a better home for the "what" than a per-tool file.

---

A good CLAUDE.md file is worth keeping tight, because it is the one piece of your AI setup you fully control, and every project genuinely benefits from having one. But your setup is more than a single file, and the facts that make your AI's output specific to you drift faster than you can hand-edit. Locul is a second brain that builds itself from what you already produce and keeps itself current on your machine, then serves that context to Claude Code and your other tools. It is free to start with 500 memories and local AI. See how it works.