One file controls how smart Claude Code actually is, and most people set it up completely wrong. Here are five tips to build your CLAUDE.md the right way, including the one almost everyone skips.
Claude Code can read every file in your project, but it doesn’t read them all at once, and it shouldn’t. What it pays attention to first is one file at the root of your project called CLAUDE.md.
Claude loads this file automatically at the start of every session, before you type anything. Get it right and Claude shows up already knowing how your project works. Leave it empty and you spend the first ten minutes of every session re-explaining the same things.
01
Know what it actually is
Your CLAUDE.md is the table of contents for your project. You might have hundreds of files, and this is the index Claude reads first to know where everything lives and how you like things done.
So don’t dump everything in it. Put in your build commands, folder layout, conventions and short pointers to deeper docs. It can live at ./CLAUDE.md or ./.claude/CLAUDE.md, and a personal one at ~/.claude/CLAUDE.md applies to every project you open.
02
Don’t write it from scratch
You don’t have to stare at a blank file. Open your project in Claude Code and run /init. Claude looks through your codebase and writes a starter CLAUDE.md with the build commands, test instructions and conventions it finds. If you already have one, /init suggests improvements instead of overwriting it.
03
Treat the starter as a draft
The /init output is a starting point. Claude guessed at some things, and it can’t know the unwritten rules in your head.
Go through it line by line. Fix anything wrong, delete anything generic, and add what Claude couldn’t discover, like "always run the tests before committing" or "never touch the files in /legacy." Make each rule concrete enough to check: "Run npm test before committing" works far better than "test your changes." Then review it like code as your project changes.
04
Give Claude a map
The highest-value thing you can add is a quick project summary plus a simple folder tree showing where the important stuff lives. Then Claude knows where to look instead of digging around blind, which wastes time and tokens.
Swap in your real folders and commands. Even this much turns Claude from guessing into navigating.
05
Keep it under 200 lines
This is the one almost everyone skips. Because the file loads into every session, a bloated CLAUDE.md backfires. Anthropic’s docs say to target under 200 lines, because longer files eat more context and Claude follows them less reliably.
If a section is getting long, move the detail into a separate doc and leave a one-line pointer. Rules that only matter for part of your code can go in .claude/rules/, scoped to those files, so they load only when Claude works there. One catch: an @path import keeps things tidy but doesn’t save space, since imported files load right along with CLAUDE.md.
The 30-Second Test
Open your CLAUDE.md and ask yourself if a brand-new teammate could read it in two minutes and know how to work in your project. If yes, Claude can too. If it’s empty, or 400 lines of noise, that’s why Claude keeps missing the obvious.
Already have a CLAUDE.md? On recent versions of Claude Code, run /doctor prompt-audit. It checks your instruction files for outdated lines, commands or files that don’t exist, and contradictions, then proposes edits without changing anything until you say so.
Want a full rewrite too? Paste this into Claude Code.
Run /context afterward and check the list under Memory files to confirm Claude actually loaded it. To read more, see Anthropic’s CLAUDE.md docs and their guide to CLAUDE.md files.