The CLAUDE.md file

You open a session on a project Claude has seen a dozen times. You type your prompt. Claude reads three files to figure out the stack, one to figure out your test runner, two more to infer your commit style. A minute later it makes an assumption about your directory structure that is wrong — the same wrong assumption it made yesterday. Every session starts from zero. Until you add a CLAUDE.md.

CLAUDE.md is an onboarding script for your codebase

CLAUDE.md is a markdown file at the root of your project that Claude Code reads automatically at the start of every session. Its contents are appended to your prompt, so anything in it is in front of the model from the first tool call. Think of it as onboarding — the thing you would tell a new teammate about your stack, your commands, and how you like code to look.

The time cost of writing one is tiny. The time saved across every future session adds up fast.

A concrete example

Here is a CLAUDE.md for a Next.js project:

# Project

This is a Next.js 15 app using the App Router, Tailwind, and Drizzle ORM.

# Commands

- Dev server: `pnpm dev`
- Run tests: `pnpm test`
- Lint: `pnpm lint`

# Code Style

- Use 2-space indentation
- Prefer named exports
- All API routes go in app/api/
- Use server actions instead of API routes where possible

Nothing clever. Project description, commands, and code style — three sections, a dozen lines. But now when you ask Claude to create a React component, it already knows to style with Tailwind, to use 2-space indentation, to favour named exports, and to reach for server actions before API routes. That work no longer has to be rediscovered on each session.

The hierarchy of memory files

There are two levels of CLAUDE.md, and they exist for different audiences.

Project-level CLAUDE.md lives at the root of your project. Check it into version control. This is what your whole team will read on every session — project-wide conventions, shared commands, architectural decisions.

User-level CLAUDE.md lives in your Claude config directory. It is just for you, and it applies to every project you open. This is where your personal preferences go — how you like comments written, your preferred naming style, anything that follows you across projects and should not be imposed on the team.

The practical rule: team-wide rules go project-level. Personal preferences go user-level. Keep them apart.

Three tips that pay off quickly

Save corrections to memory. If you find yourself correcting Claude the same way twice — "use server actions, not API routes" — explicitly ask Claude to save that rule to CLAUDE.md. Next session, it is already known.

Reference project docs with @. You can link to other files inline with the @ symbol. For example:

## README.md

Please read if you need more info: @README.md

Claude will pull the referenced file into context when it is relevant — without you loading it into every prompt.

Start without one. This is the counterintuitive advice: do not write your CLAUDE.md up front. Start a project without one, and pay attention to the moments where you have to course-correct the model. Those corrections are the signal for what belongs in the file. When you have a clear sense of what Claude needs, run /init to have Claude generate a CLAUDE.md based on your codebase — and refine from there.

Writing CLAUDE.md too early produces a bloated file full of things Claude did not actually need. Writing it from observed friction produces a compact file that solves real problems.

The bigger picture

The difference between a frustrating Claude Code session and a productive one usually comes down to context. CLAUDE.md is the single most effective lever you have for controlling that context. Start small — stack, commands, preferences — and grow the file organically as you discover the gaps.