Today we'll take a look at one of the most useful files in any Claude Code project: CLAUDE.md.

A CLAUDE.md file gives Claude Code instructions about our project that stick around between sessions. Claude Code loads it into context at the start of every session, so we stop repeating the same preferences over and over.

Let's dive in.

Setting It Up

The fastest way to get one is to let Claude Code write a first draft for us:

> /init

Claude looks at our codebase and writes a CLAUDE.md with the build commands, test instructions, and conventions it finds. If one already exists, /init suggests improvements instead of overwriting it.

We can also start from scratch:

# Discovery One
Use TypeScript for all new files
Use bun, not node
Run tests with `bun test`
The database is SQLite via better-sqlite3

From then on, every session in this directory starts out knowing all of that. Neat!

Where It Can Live

There are a few places a CLAUDE.md can go, each with a different scope:

# User: our preferences for every project
~/.claude/CLAUDE.md

# Project: checked into git, shared with the team
./CLAUDE.md          # or ./.claude/CLAUDE.md

# Local: personal notes for this project only
./CLAUDE.local.md    # add it to .gitignore

These don't override each other. Claude Code concatenates all of them into context, broadest first: user, then project, then local. Instructions closer to where we launched get read last.

Parent And Child Directories

Claude Code also walks up the directory tree. If we start it in apps/hal/, it loads apps/hal/CLAUDE.md and also apps/CLAUDE.md and the repo root's CLAUDE.md.

monorepo/
  CLAUDE.md            # loaded at launch
  apps/
    hal/
      CLAUDE.md        # loaded at launch (we started here)
  packages/
    ui/
      CLAUDE.md        # loaded later, on demand

Files in subdirectories below where we started load on demand, the first time Claude reads or edits something in that folder. That keeps a big monorepo from dumping every team's notes into context at once.

What To Put In It

The best CLAUDE.md files are short and full of facts Claude can't easily figure out on its own:

• Commands: how to build, test, lint, and deploy
• Conventions: naming, patterns to follow or avoid
• Layout: where things live, how modules connect
• Gotchas: the things that bit us last week

## Commands
bun dev    # dev server on :3000
bun test   # unit tests
bun lint   # eslint

## Rules
Prefer unknown over any
Never edit files in generated/
Migrations go in db/migrations, one per change

Imports

A CLAUDE.md can pull in other files with @path:

See @README.md for the project overview.
Our API conventions are in @docs/api.md.

# Personal prefs, shared across worktrees
@~/.claude/samantha-prefs.md

Imported files can import other files, up to four hops deep. Relative paths resolve from the file doing the importing, not from wherever we launched Claude Code.

Watch Out

The docs suggest aiming for under around ~200 lines per CLAUDE.md. Longer files cost context and Claude follows them less reliably. Imports help organize a long file, but they don't shrink it, since imported files load right along with it.

If something only matters for one part of the codebase, a path-scoped rule in .claude/rules/ is a better home. Those only load when Claude works with matching files.

To check what loaded, we can run /context and look under Memory files.

More info about CLAUDE.md can be found at the Claude Code docs.