Claude Lessons / Guides

CLAUDE.md Best Practices: Rules That Actually Get Followed

Claude Lessons team · Updated August 2, 2026

Most CLAUDE.md guides are the same list: keep it short, describe your stack, add some do's and don'ts. That advice isn't wrong, but it skips the part that actually decides whether the file works — a written rule and an enforced rule are different things, and CLAUDE.md alone can only give you the first one. This guide covers what to put in the file, what to leave out, and where to stop writing prose and start writing a hook instead.

What CLAUDE.md actually does

CLAUDE.md is a memory file Claude Code reads at the start of every session in a project. It's the fastest way to give an agent context it would otherwise have to rediscover — or guess at — from scratch each time: your stack, your conventions, where things live, and what not to touch. Done well, it turns every session into one where the agent already knows the house style. Done badly, it's either too thin to help or so long that the important parts get buried, which in practice acts the same as not having it. See our beginner's guide for where CLAUDE.md fits into a first Claude Code session.

Keep it short — and why that's not just tidiness

Every line in CLAUDE.md is read on every session, whether or not it's relevant to the task at hand. That makes length a real cost, not a style preference: a 400-line file spends context budget on every single turn, and a genuinely long file tends to get skim-read by the agent the same way an overlong onboarding doc gets skim-read by a new hire — the specific rule you cared about most gets lost between forty others.

A reasonable target is under 200 lines, with anything over ~250 treated as a sign the file needs to be split (into nested CLAUDE.md files, see below) or trimmed to what actually changes agent behavior on a typical task, not everything that's true about the project.

What to put in it

• Stack and structure, briefly. Language, framework, package manager, where source vs. tests vs. config live — one or two lines each, not a tour.
• Commands that matter. How to run tests, lint, build, and start dev — the exact commands, since "run the tests" without a command wastes a turn on Claude Code guessing.
• House conventions the agent can't infer from the code alone. Naming patterns, where new files of a given type go, which patterns are deprecated even though old examples still exist in the codebase.
• Explicit no-touch zones. Generated files, vendored code, anything with a reason not to edit that isn't obvious from looking at it.
• Pointers, not restatements. "Schema lives in db/schema.sql, migrations in db/migrations/" beats describing the schema in prose — the agent can read the actual file.

What to leave out

Anything the agent can discover by reading the code doesn't need to be in CLAUDE.md — restating it just adds length without adding information, and it goes stale the moment the code changes while the file doesn't. Skip project history, marketing description, and full architecture write-ups; link to a docs file if one exists instead of duplicating it. Skip rules with no teeth, too — a rule nobody enforces and nobody checks tends to erode into something the agent (and the team) quietly stops following.

The enforcement problem

Here's the gap most CLAUDE.md advice skips: a rule written in CLAUDE.md is a request, not a guarantee. In a short, focused session the agent usually follows it. In a long session, after a lot of back-and-forth, earlier context — including CLAUDE.md's own rules — competes with everything that's happened since, and compliance gets less reliable. That's not a bug you can prompt your way out of; it's a property of how context works.

The fix is to give every rule you actually can't afford to skip an enforcement layer that isn't just prose: a hook that blocks a commit if tests fail, a linter rule that fails CI regardless of what the agent decided, a pre-edit hook that refuses to touch a protected path. Reserve CLAUDE.md prose for preferences and context where a miss is annoying, not dangerous — a hook for the rules where a miss is expensive.

Comments: notes for humans, free of charge

Standard HTML-style comments in a CLAUDE.md file (<!-- like this -->) are a good place to leave context for teammates — why a rule exists, a link to the discussion that produced it — without it reading as an instruction to the agent. It's a small trick, but it means a CLAUDE.md file can double as light team documentation without inflating what actually gets processed each session.

Nested CLAUDE.md files for monorepos

Claude Code picks up CLAUDE.md files at multiple directory levels and layers the more specific ones on top of the root file. That's genuinely useful when different parts of a project really do have different conventions — a root file for shared rules, a package-level file for that package's exceptions. It's not a fix for a single small project's file being too long; splitting one project's rules across five nested files just spreads the same length problem into smaller pieces the agent still has to read.

A worked example

A trimmed, realistic CLAUDE.md for a small web app might read like this — short enough to actually get read in full, every session:

Nothing here restates code the agent can read directly, and nothing is a rule with no enforcement — the generated-files rule, if it matters, gets a hook that blocks the edit rather than relying on the note alone.

Common mistakes

• Writing it once and never revisiting it. A CLAUDE.md that describes a stack or convention you migrated away from six months ago actively misleads the agent — treat it like code, not a one-time setup step.
• Copying a generic template wholesale. Sections that don't apply to your project just add length for nothing; keep only what actually changes behavior on your codebase.
• Using it for rules that need to be guaranteed. If a miss is expensive, it needs a hook or a CI check, not just a sentence — see the enforcement section above.
• Burying the important rule in the middle of a long list. Put the two or three rules that matter most near the top; don't make them compete with fifteen minor style notes for attention.

FAQ

How long should a CLAUDE.md file be?

Aim for well under 200 lines. Every line in CLAUDE.md gets read on every session, so it consumes context budget whether or not it's relevant to the current task. Files that sprawl past 200-250 lines tend to get skim-read by the agent the same way they'd get skim-read by a new hire handed a 10-page onboarding doc — the important parts get lost in the noise.

What's the difference between a rule in CLAUDE.md and a rule enforced by a hook?

A CLAUDE.md rule is a written instruction the agent reads and tries to follow — reliable most of the time, but not guaranteed, especially in a long session where earlier context has faded. A hook is a script that runs automatically at a specific point (before a commit, after a file edit) and can actually block an action, not just request one. Anything you truly cannot afford to skip — running tests before commit, blocking edits to a protected file — belongs in a hook, not just a sentence in CLAUDE.md.

Should CLAUDE.md include the whole project's architecture?

No. CLAUDE.md should point at where information lives, not restate it. Instead of describing your database schema in prose, link to the schema file. Instead of listing every API route, note where routes are defined and the convention for adding one. The agent can read the actual files when it needs the detail; CLAUDE.md's job is to save it the trouble of guessing where to look and what house style to follow.

Can I use CLAUDE.md comments to leave notes for humans without wasting context?

Yes. Standard HTML-style comments (<!-- like this -->) in a CLAUDE.md file are a reasonable place to leave notes for teammates — reasoning for a rule, a TODO, a link to a discussion — without it reading as an instruction to the agent. Keep them short; the goal is a file that's easy for both humans and the agent to scan, not a place to store design docs.

Do nested CLAUDE.md files in subdirectories actually get used?

Claude Code supports CLAUDE.md files at multiple levels of a project, and it will pick up the ones relevant to the files it's working with, layering more specific rules on top of the root file. This is useful for monorepos or projects with genuinely different conventions per package — a root CLAUDE.md for shared rules, and a package-level one for that package's exceptions. It only helps if the split is real; splitting one small project's rules across five files just re-creates the length problem in smaller pieces.