What is CLAUDE.md? Complete guide for Claude Code

CLAUDE.md is a markdown file at the root of your project that Claude Code reads automatically on every session. It's loaded into the model's context as "memory" — a persistent piece of project knowledge that doesn't have to be re-explained each turn.

How Claude finds it

When you launch Claude Code in a directory, it walks up from the current working directory looking for CLAUDE.md files. Every one it finds is loaded into context. There are three layers:

1. Project-level CLAUDE.md — at the repo root. The primary file for project conventions.
2. Directory-level CLAUDE.md — in subdirectories. Loaded when Claude is working in that subdirectory. Useful in monorepos where each package has its own conventions.
3. User-level CLAUDE.md — at ~/.claude/CLAUDE.md. Personal preferences that follow you across all projects (and aren't committed to anyone's repo).

If multiple files exist, Claude merges them — most-specific wins on overlap, but the convention is to write each file scoped to its level of specificity so they compose rather than conflict.

What to put in it

Think "what would I tell a new contributor on day one" — and then write the version a model needs:

• Stack and versions — Claude often defaults to slightly outdated patterns (Pages Router instead of App Router, Vue 2 syntax instead of Vue 3). Pin the versions explicitly.
• Folder structure — where things go and why.
• Conventions — exports, naming, imports, formatting.
• Patterns to follow / avoid — with concrete examples.
• Tooling — the exact commands to run dev / build / test / lint.
• Behavioral rules for the AI — "ask before installing dependencies," "run the linter before declaring a task complete," "never modify migrations after they're committed."

What format should it be in?

Plain markdown. No frontmatter (Claude doesn't read it). Use ## H2 section headers for top-level sections; Claude treats them as logical chunks.

A reasonable skeleton:

# Project Name

## Project context
One paragraph: what is this, what's it for.

## Stack
Bulleted list of versions and choices.

## Conventions
- Export style
- Naming
- Imports
- Formatting

## Patterns to follow
With examples.

## Patterns to avoid
With examples.

## Testing
Test framework, where tests live, what to test.

## Tooling
Exact commands.

## AI behavioral rules
Meta-rules.

How long can it be?

Claude tolerates a long CLAUDE.md — practical limits are 500–800 lines before it starts to feel heavy. The model reads it on every turn, so it counts toward your context budget. For most projects, 250–400 lines hits the sweet spot.

If your CLAUDE.md is growing past 600 lines, consider splitting into directory-level files. A monorepo might have a thin root CLAUDE.md with shared conventions and per-package CLAUDE.md files with package-specific details.

Will it slow down responses?

It counts toward context but not toward latency in any noticeable way. Claude reads it once per session, not per token. If your responses feel slow, it's almost always the conversation history, not the rules file.

Should I commit it to git?

Yes. CLAUDE.md is project documentation — it benefits every contributor using Claude Code. Commit it, review changes to it like any other doc, and update it whenever a convention changes.

The exception is ~/.claude/CLAUDE.md — that's user-scoped, machine-local, and stays out of every repo.

Where to start

Pick a stack from the library, copy it as Claude (CLAUDE.md), and edit. Or run the generator and pick "Claude Code" as the output format. Either way takes about two minutes.