Writing the Best CLAUDE.md: A Complete Guide for Claude Code

CLAUDE.md is a markdown file that Claude Code loads automatically at the beginning of every conversation. It gives Claude standing instructions on your tech stack, how to run tests, which conventions matter, and what not to touch. Without it, every session starts from zero. This complete guide covers how to build a CLAUDE.md that earns every line.

What Is a CLAUDE.md File?

CLAUDE.md is a markdown file that Claude Code reads at the start of every session. It sits at your project root and gives Claude standing instructions on all kinds of relevant facts: the tech stack you use, how you run tests, which conventions matter, and what not to touch.

Without it, every session starts from zero. You explain the same context, correct the same assumptions, and watch Claude make the same mistakes it made yesterday. CLAUDE.md fixes that by encoding your project knowledge once.

Claude actively filters content it considers irrelevant to the current task. A bloated file won't just waste space; it competes with your actual rules.

File Locations and Precedence

CLAUDE.md files can live in four places, listed from broadest to most specific:

More specific files take precedence over broader ones. If your project CLAUDE.md says "use tabs" and your user-level file says "use spaces," the project file wins.

For personal preferences that shouldn't end up in version control, create a CLAUDE.local.md and add it to .gitignore. Editor quirks, preferred commit styles, or temporary overrides go here.

What to Include in Your CLAUDE.md

A CLAUDE.md breaks down into three layers: (1) What the project is, (2) Why it works the way it does, (3) How Claude should operate within it.

High-Signal Project Overview

Open with a one or two-line project description and your tech stack with version numbers. Claude can infer a lot from reading your code, but it won't guess that you're on Next.js 15 instead of 14, or that you chose Drizzle over Prisma.

Include a directory structure map. Not every file, just the top-level layout with brief descriptions:

Put common commands in code blocks. Build, test, lint, and dev server startup. A command inside a code fence is something Claude will run verbatim.

Purpose and Constraints

Your architectural decisions need to be in the file because Claude will make its own if you don't. If you chose SQLite over Postgres for a reason, say so. If your API layer follows a specific pattern, explain the reasoning.

Rationale does real work here. "Never force push" is a flat instruction that Claude might ignore under pressure. "Never force push. This rewrites shared history and is unrecoverable for collaborators," gives Claude enough context to generalize. It won't just avoid git push --force. It'll hesitate before git reset --hard on a shared branch too.

Working Instructions for Claude

This covers conventions Claude can't pick up from reading your code. If you use Conventional Commits (feat:, fix:, docs:), say so. If branches follow a naming pattern like initials/description, write it down.

Quirks and traps belong here too. Every codebase has them: the migration script that must run before builds, the env variable that needs a specific value before tests pass, the module that breaks if imported out of order. Claude is a new team member every session, and these are the things a new hire trips over on day one.

What you can skip: anything Claude already knows from the language itself. You don't need to tell it to use async/await in modern JavaScript or to prefer pathlib in Python 3. If a convention is the language default, writing it down is noise that crowds out the instructions that actually matter.

How to Write a CLAUDE.md File

Getting the content right is the easier half. The harder part is writing instructions Claude will actually follow, and knowing what to cut.

Writing Effective Instructions

Specificity beats intent every time. "Format code properly" tells Claude nothing. "Use 2-space indentation, no semicolons, single quotes" tells it exactly what to do and gives it something verifiable.

Apply this test to every line: "Would removing this cause Claude to make mistakes?" If the answer is no, the line goes. The official recommendation is under 200 lines per file, and some experienced teams run with fewer than 60. That's not minimalism for its own sake: a shorter file means more of it gets read.

Keep heading levels to three at most. Use section names agents recognize from README conventions: Commands, Structure, Conventions, Testing. Getting creative with section names introduces friction because Claude has seen millions of READMEs and has strong expectations about what lives where.

When a rule keeps getting ignored despite being in the file, don't add more words around it. Prefix it with IMPORTANT: or YOU MUST. But use this sparingly, because emphasis scales poorly. If every rule is marked important, the emphasis becomes invisible.

What to Leave Out

Building the File from Scratch

Run /init in your project root to get a generated starting point. Read every line, cut what's obvious, and add what's missing from how your team actually works. Starting from /init output is faster than from a blank file, but auto-generated content should never ship without review.

If you prefer writing from scratch, start with five sections: (1) Project overview, (2) Directory map, (3) Commands, (4) Conventions, (5) Quirks. You can always grow the file later, and starting minimal means every line you add comes from a real mistake rather than speculation.

Scaling CLAUDE.md Files for Teams

A single-developer file can stay lean indefinitely. Once a team gets involved, the file needs a different kind of structure.

Version Control and Shared Ownership

Your project-level CLAUDE.md belongs in git. It's shared documentation that gets better as teammates contribute rules from their own mistakes. Treat changes to it the same way you treat code PRs: review them, question whether each new line earns its place.

When conventions pile up beyond what fits in a single file, move them into .claude/rules/. Each Markdown file covers one topic with descriptive filenames: testing.md, api-design.md, database-migrations.md. Claude discovers these files recursively and loads them with the same priority as the main CLAUDE.md.

Path-scoped rules make this even more targeted. Add YAML frontmatter, and the rule only loads when Claude works with matching files. Your frontend conventions won't burn instruction budget during backend work, and vice versa.

Progressive Disclosure and Modularization

Scaling a CLAUDE.md typically triggers the urge to centralize: one big file with everything. That's the wrong direction. Splitting a monorepo's CLAUDE.md into service-level files can reduce total word count by 80% while improving how well Claude follows the rules.

The principle: point, don't embed. Instead of @path/to/big-doc.md (which loads the entire file into every session), write "For migration procedures, see docs/migrations.md." Claude reads it when it needs the information.

Subdirectory CLAUDE.md files complete this pattern. A frontend/CLAUDE.md with React conventions loads only when Claude touches files in that directory. Backend rules stay out of the way during frontend work.

Maintaining Your CLAUDE.md File

Scaling structure is mostly a solved problem once you know the primitives. But projects change, and conventions evolve. Rules that made sense six months ago become noise that crowds out the ones that matter now.

Keeping the File Current

Anti-Patterns to Avoid

Conclusion

CLAUDE.md is probably the most load-bearing file in a Claude Code project. It shapes every session before a single prompt is typed, and a well-maintained one compounds across weeks of work.

If you don't have one yet, run /init, read what comes out, and cut every line that wouldn't prevent a real mistake. If you have one, open it now and apply the same test. If your CLAUDE.md has to be enormous to explain your project, that's a signal that the project's tooling is too complex, not that you need a bigger file.

The right next step: audit your repo and draft a baseline today. Start with five sections, keep it under 60 lines, and let real mistakes drive every addition from there.