Understand CLAUDE.md files in Claude Code

Link copied

Attach video time

Right after you start Claude Code, you'll see some messaging suggesting that you run /init. That command has Claude create a CLAUDE.md file for your project -- a plain markdown text file that gets loaded at the start of every single conversation to give Claude context specific to your codebase.

Back when Claude Code first came out, it was common to write EVERYTHING into this file, since it provided important context to the underlying model. But as models continue to get better, the need for a large CLAUDE.md has diminished. This isn't to say you shouldn't use one -- just that its importance these days is drastically overstated.

For the most part, Claude Code can infer what your codebase looks like and how it works, especially if you're using a framework with any level of popularity. But a CLAUDE.md file can still provide real value in your agentic programming sessions.

I don't recommend running /init, because it will almost always write far more into this file than you need. Plan on creating and editing it by hand instead. It's just a markdown file at the root of your project, so make one and start typing.

It's context, not configuration

Before we get into best practices, it's worth understanding what this file actually is, because everything else follows from it.

Claude Code delivers your CLAUDE.md as a message at the start of the conversation. It is not a settings file, and Claude Code is not enforcing anything in it. Claude simply reads it, the same way it reads anything else you tell it, and does its best to follow along.

That single fact explains the most counterintuitive thing about these files: longer files get followed less reliably, not more. A rule buried in a wall of text is competing for attention with everything else in the conversation, and it loses. If you need something guaranteed to happen every time -- like a linter running before every commit -- that's a job for a hook, not for CLAUDE.md.

Best practices

This used to be an open question, and it isn't anymore. Keep this file short. A few things to remember:

• Keep it minimal. Aim for well under 200 lines. Stuffing tons of content into this file is the single most common mistake people make, and it's an easy one to make, because every rule you add feels helpful in the moment.

• Be specific enough to verify. "Use 2-space indentation" beats "format code properly." "Run npm test before committing" beats "test your changes." Vague instructions give Claude nothing to act on.

• Use consistent headings and formatting. It's just markdown, but try to use consistent H1/H2 headings, bulleted lists where appropriate, and bold or italics for important callouts. You can also add emphasis with ALL CAPS for IMPORTANT or MUST HAVE designations, and combine that with bold formatting.

• Prune it on a schedule. Build a habit of removing information that's no longer relevant as your codebase changes. A stale rule is worse than no rule, because you'll trust it without checking what's really going on under the hood.

• Watch for contradictions. If two rules conflict, Claude may pick one arbitrarily. That's another argument for a short file -- it's much easier to spot a contradiction in 40 lines than in 400.

• Experiment to see what works. AI-assisted coding is still the wild west, and you won't know what fits your project without trying it. Just experiment within a short file rather than a long one.

Pro tip: Cutting information from this file is just as valuable as adding it. If you inherit a CLAUDE.md that's grown past a couple hundred lines, deleting the parts you don't need is the most useful thing you can do to it.

You'll develop your own preferences around these files, so keep experimenting to see what works best for you and your team.