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.
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.
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.
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.
A good CLAUDE.md is short and specific:
Here is a compact example:
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.
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.
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.