What to put in a CLAUDE.md file so Claude Code understands your project

You open a new Claude Code session, ask for a small change, and watch it reach for the wrong package manager again. Or it runs the full test suite when a single test file would do, or it edits a generated file that gets overwritten on the next build. You corrected all of this yesterday. Today it is gone, because every session starts with a fresh context window. The CLAUDE.md file is the one place where those corrections survive, and most of the problems people have with it come from putting the wrong things in, putting it in the wrong place, or letting it grow until nothing in it stands out.

This guide covers what the file is actually for, where Claude Code looks for it, what to write and what to leave out, and how to check that it is doing its job.

What a CLAUDE.md file actually is

A CLAUDE.md file is plain markdown that Claude Code reads at the start of every session. Nothing about it is special syntax. It is a set of notes that gets placed into the context window before your first message, so the agent starts each session already knowing the things you would otherwise have to type again.

Two details change how you should write it. First, the official documentation is explicit that the content is context, not configuration:

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions. Source: code.claude.com

That means the file works best for guidance, not for guarantees. If something must happen every single time, such as a formatter running after each edit or a block on writing to a particular folder, a hook is the right tool. Hooks run as shell commands at fixed points and do not depend on the model deciding to comply.

Second, Claude Code now has a separate mechanism called auto memory. Claude writes those notes itself, based on corrections you give during a session, and stores them per repository under ~/.claude/projects/<project>/memory/. The index file there, MEMORY.md, is loaded up to its first 200 lines or 25KB. The split is simple: CLAUDE.md is what you write deliberately and usually share with the team, while auto memory is what the agent picks up on its own. If you ask Claude to "remember" something, it goes to auto memory. If you want it in CLAUDE.md, say so, or edit the file yourself.

The documentation also gives a useful test for when something belongs in the file. Add an entry when the agent makes the same mistake a second time, when a code review catches something the agent should have known, when you type the same correction you typed last session, or when a new teammate would need the same context to be productive. If none of those apply, the line probably does not need to be there.

Where Claude Code looks for the file

The file can live in several places, and they stack rather than override each other. This is where most confusion starts, because a rule you wrote months ago in your home folder can quietly shape a project you are working on today.

Location	Scope	Typical content	Shared with
~/.claude/CLAUDE.md	Every project on your machine	Personal habits, preferred tools	Only you
./CLAUDE.md or ./.claude/CLAUDE.md	One project	Build commands, conventions, layout	The team, via git
./CLAUDE.local.md	One project, personal	Sandbox URLs, local test data	Only you (add to .gitignore)
/Library/Application Support/ClaudeCode/CLAUDE.md	Whole organization on macOS	Security and compliance rules	Everyone the admin targets

Claude Code walks up from the directory where you launched it and loads every CLAUDE.md and CLAUDE.local.md it finds along the way. All of them are concatenated, ordered from the top of the file system down to your working directory, so the file closest to where you started is read last. Files inside subdirectories below you are not loaded at launch. They are pulled in when the agent reads files in those subdirectories.

Two practical consequences follow. If you launch Claude Code from a parent folder that holds several projects, you may be loading instructions meant for a different repository. And if a monorepo has a CLAUDE.md in each package, the one for a given package only appears once the agent touches that package's files.

If your repository was already set up for other coding agents with an AGENTS.md file, recent versions of Claude Code can read it directly, but only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above. Adding a CLAUDE.local.md to such a project stops the AGENTS.md from loading for you. The simplest way to keep one source of truth is a short CLAUDE.md that imports the other file with @AGENTS.md.

What to put in it

The official guidance boils down to facts the agent should hold in every session: build commands, conventions, project layout, and "always do X" rules. In practice, the entries that earn their place fall into a few groups.

Commands the agent cannot guess. If the test command is npm test, the agent will find it. If running a single test needs a specific flag, an environment variable, or a local database, write that down. The same goes for the lint command that the CI uses, the command that regenerates types, and anything that must run before a commit.

Where things live, when it is not obvious. Skip the full directory tree. The agent can list folders itself. Write the things that would surprise a newcomer: generated files that must never be edited by hand, the folder that looks like dead code but is still in use, the place where environment settings are read from.

Conventions that differ from the default. If your team uses two-space indentation, single quotes, and a specific error format, say so in concrete terms. The documentation's own examples are good models: "Use 2-space indentation" rather than "Format code properly", "Run npm test before committing" rather than "Test your changes", and "API handlers live in src/api/handlers/" rather than "Keep files organized".

The pitfalls that already cost you time. This is the most valuable part and the one most often missing. A line like "Do not run the migration script against the shared database, use the local Docker instance" saves more than a page of style rules.

What to leave out. Anything the agent can read from the code: dependency lists, architecture overviews copied from the README, descriptions of every folder. Long procedures that only matter now and then belong in a skill, which loads only when it is needed. Personal preferences belong in your user-level file or in CLAUDE.local.md, not in the file the whole team shares.

A short example of the shape that tends to work:

## Commands
- Dev server: npm run dev (port 3047)
- Single test: npx jest path/to/file.test.ts
- Before commit: npm run lint && npm run typecheck

## Rules
- Never edit files under src/generated/. Run npm run codegen instead.
- Database changes go through a migration in db/migrations/.
- Use the local Postgres in Docker, not a system install.

Keeping it small enough to be read

Every line in CLAUDE.md is loaded into the context window at the start of every session, and it competes for attention with your actual request. The documentation sets a concrete target: keep each file under 200 lines, because longer files use more context and reduce how reliably instructions are followed. Claude Code will load a file up to 4 MiB, but that is a technical ceiling, not a recommendation.

When a file grows, there are three ways to cut it down, and they do different things.

Path-scoped rules. Files in .claude/rules/ can start with a paths: field in YAML frontmatter, listing glob patterns such as src/api/**/*.ts. Those rules load only when the agent reads a matching file. This is the only one of the three that actually reduces what is loaded in a typical session.

Imports. A line like @docs/testing.md pulls another file into context. It keeps the main file readable, but imported files still load at launch, so it does not save context. Imports can nest up to four levels deep, and a path written inside backticks is left as plain text rather than imported.

Skills. Multi-step procedures, such as a release checklist, fit better as a skill that loads only when invoked or when the agent decides it is relevant.

Consistency matters as much as size. If one file says to use one package manager and a nested file says another, the agent may pick either. Reviewing the stack of files every few weeks, and deleting rules that no longer apply, does more than adding new ones. Block-level HTML comments are stripped before the content reaches the model, so notes to human maintainers can stay in the file without costing context.

Checking that it loaded and is being followed

When the agent ignores an instruction, the cause is usually one of four things: the file did not load, a different file contradicts it, the instruction is too vague, or it was never a good fit for this mechanism.

Start with /context inside a session. It lists the memory files that were loaded under Memory files. If your CLAUDE.md is not in that list, the agent cannot see it, and the fix is about location, not wording. Check which directory you launched from. The /memory command shows every CLAUDE.md location across user and project scope, including ones that do not exist yet, and lets you open any of them in your editor.

If the file loaded but an instruction is still ignored, look for a contradiction in another file, then make the rule more specific. "Keep functions small" gives the model nothing to check. "Split any function over 40 lines" does.

Instructions given only in conversation can disappear after /compact. The project root CLAUDE.md is re-read from disk after compaction, so a rule that keeps getting lost should move into the file. Nested files and path-scoped rules come back when the agent reads a file they apply to again.

For a first draft, /init analyzes the codebase and writes a starting CLAUDE.md with the build and test commands it can find. If the file already exists, it suggests changes rather than overwriting. Treat the output as a draft: it tends to describe what the code already shows, which is exactly the part worth trimming.

Where the file meets the rest of your workflow

A CLAUDE.md file describes a project, and the agent reads it from the folder where the session starts. That ties the file to how you open projects in the first place. If you move between a file browser, a terminal window, and an editor to get to the right directory before launching the agent, it is easy to start from the parent folder by mistake and load the wrong set of instructions, or none at all.

The same applies to the files the instructions point at. A good CLAUDE.md names folders: where generated code lives, where migrations go, which directory holds the fixtures. Being able to see those folders next to the terminal session, rather than switching windows to confirm a path, makes it quicker to notice when a rule refers to a folder that has since moved. A file manager with a built-in terminal keeps the folder and the session in the same place. The features overview shows how that layout works, and the comparison with other file managers lays out which tools offer an integrated terminal at all.

What to change first

Open your project's CLAUDE.md, delete anything the agent could learn by reading the code, and add the one pitfall that cost you the most time last week. Then run /context in a new session to confirm the file actually loads. If you want the folder, the terminal, and the agent in one window while you do this, Atriens is built for that.