CLAUDE.md Fundamentals

Your CLAUDE.md file is the single highest-leverage thing you can set up in Claude Code. It loads at the start of every session and shapes every response. Most people either skip it entirely or fill it with vague nonsense that does nothing. Both are a waste.

What It Actually Is

CLAUDE.md is a plain markdown file that gives Claude Code persistent instructions. A briefing document. Every time you start a new session, Claude Code reads it before you say anything. Your preferences, project rules, coding standards, all loaded automatically.

There are two memory systems in Claude Code. CLAUDE.md files are the ones you write and maintain. Auto memory is what Claude writes on its own based on conversations. Both matter, but CLAUDE.md is the one you control.

The thing that trips people up: CLAUDE.md is context, not enforced configuration. It's not a settings file or a config. It's instructions that Claude reads and follows, and the phrasing directly affects how reliably it listens.

Vague instructions get vague compliance. Specific instructions get specific compliance. No exceptions.

File Locations and Loading Order

Four scopes. Each one different.

When you start a session, Claude Code walks up the directory tree from your working directory, checking each level for CLAUDE.md and CLAUDE.local.md files. Subdirectory files load on demand when Claude touches files in those directories.

This layering is genuinely powerful. Your user-level file sets personal preferences ("always use TypeScript", "prefer functional style"). Your project-level file sets team conventions. Your local file holds stuff that is just for you on this specific project. They compose cleanly.

Writing One That Works

The /init command is the fastest way to start. Run it and Claude Code analyzes your codebase, generating a starting CLAUDE.md with build commands, test instructions, and detected conventions. If one already exists, it suggests improvements instead.

Try it: Open a project directory and run /init. Look at what it generates. Then rip out the generic stuff and add your actual opinions.

A solid project CLAUDE.md looks like this:

# Project Instructions
 
## Stack
- Next.js 15 with App Router and TypeScript
- Tailwind CSS v4 with @theme inline config
- PostgreSQL with Drizzle ORM
 
## Build and Test
- Build: npm run build (must pass with zero errors before committing)
- Test: npm run test
- Lint: npm run lint
 
## Coding Standards
- Server components by default. Only use "use client" when needed.
- Use 2-space indentation
- Prefer early returns over nested conditionals
- Name booleans with is/has/should prefix
 
## Git
- Conventional commits (feat:, fix:, chore:)
- Never push directly to main
- Run tests before committing

Short sections. Bullet points. Specific, actionable instructions. "Use 2-space indentation" beats "format code properly" by a mile. "Run npm test before committing" beats "test your changes" every time. Boring rules that leave zero room for interpretation are what you want.

Importing Other Files with @path

CLAUDE.md files can pull in content from other files:

See @README.md for project overview.
See @package.json for available npm commands.
 
# Git Workflow
Follow the process described in @docs/git-workflow.md

Paths resolve relative to the file containing the import. This keeps your CLAUDE.md lean while giving Claude Code access to detailed docs when needed. There's a max depth of 5 hops, so don't go wild chaining imports through imports through imports.

Try it: Add @README.md to your CLAUDE.md and start a new session. Ask Claude Code to summarize your project. It will use the imported README content automatically.

Size Matters

Target under 200 lines per CLAUDE.md file. This isn't arbitrary. Longer files eat more context window and actually reduce how well Claude follows your instructions. More rules doesn't mean better behavior. If you need more detail, use @path imports.

One thing worth knowing: CLAUDE.md survives compaction. When you run /compact to free up context space, Claude Code re-reads your CLAUDE.md from disk and re-injects it. Your instructions persist no matter how long the session runs. That's a big deal, and it's why CLAUDE.md beats just telling Claude what to do in each message.

So why bother with CLAUDE.md when you can just say things in chat? Because you'd be repeating yourself constantly. CLAUDE.md applies to every response in every session without you lifting a finger. It's checked into source control so your whole team gets the same standards. And you stop burning brain cycles restating the same preferences. Your messages get to focus on what you actually want done, not on reminding Claude how you like things.