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. 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: 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. 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.