What Is CLAUDE.md? A Practical Guide to Configuring Claude Code

If you use Claude Code, there is one file that quietly shapes every session: CLAUDE.md. Most developers either do not have one or have one that works against them. Here is what it actually is, in plain terms.

The file Claude reads every session

CLAUDE.md is a markdown file that Claude Code reads at the start of every conversation. Think of it as your project's constitution — the source of truth for how your specific repository works. Because Claude reads it every time, you stop re-explaining your stack, your conventions, and your commands on every task.

Why it exists

Without a CLAUDE.md, every session starts cold. Claude can read your code, but it cannot infer the things that live outside the code: that you are on Next.js 15 and not 14, that a directory is generated and must never be edited, that your team has a particular commit style. You end up explaining these again and again, slightly differently each time, so the output drifts. CLAUDE.md captures that knowledge once, somewhere Claude always sees it.

Where it lives, and how to start

Put CLAUDE.md in the root of your project. You do not have to write it from a blank page — the /init command analyses your codebase and generates a starter, detecting your build tools, test framework, and existing patterns:

$ claude
> /init

Treat the result as a foundation, not a finished product. The real value comes from refining it as you learn what Claude gets wrong without guidance.

What belongs in it

A good CLAUDE.md is short and specific:

• A one-line stack description, with versions — Claude will not guess Next.js 15 over 14
• A directory map — the top-level layout and what each part holds
• The build and test commands
• The conventions a newcomer could not infer from the code
• A "do not touch" section — generated files, migrations, protected paths

Here is a compact example:

# Project: Acme Dashboard
Next.js 15 (App Router), TypeScript, Drizzle ORM, Vitest.

## Structure
src/app/        # routes and pages
db/migrations/  # generated - never hand-edit

## Commands
Build:  npm run build
Test:   npm run test

## Do not touch
db/migrations/ is generated. Never edit by hand.

Why it is the highest-leverage file

Because CLAUDE.md loads on every single session, its quality compounds. A precise file pays off thousands of times over a project's life — every task starts from a correct understanding. A bloated one taxes every interaction. Few files in your repo have this much leverage, which is why it is worth getting right before anything else.

The bottom line

CLAUDE.md is a small, durable investment: write your project's real context once, keep it lean, and every session starts from a correct picture. It is also the foundation the rest of Claude Code's configuration — commands, hooks, subagents, skills — builds on.

Free starter: The format, a complete annotated example, and the one-line test are all on a free cheat sheet: CLAUDE.md Quick-Start Cheat Sheet

Go deeper: The full guide covers the entire configuration stack — hooks, subagents, commands, skills and plugins — with real-world walkthroughs and a 30-day plan: CLAUDE.md: The Complete Claude Code Configuration Guide

What does your CLAUDE.md look like right now — lean and sharp, or a bit of a dumping ground? Curious to hear in the comments.