What to Put in Your CLAUDE.md (and What to Leave Out)

A great CLAUDE.md is not the longest one. It is the one where every line changes what Claude does. The whole skill is knowing what belongs in it — and, just as importantly, what does not.

The sections that earn their place

Start with a one or two line project description and your stack, with version numbers. Claude infers a lot from your code, but it will not guess that you are on Next.js 15 instead of 14, or which ORM you chose.

Then a directory map — not every file, just the top-level layout with a note on what each part holds. After that: the build and test commands, the conventions a formatter does not enforce, and critically, the things not to touch.

# Project: Acme Dashboard