CLAUDE.md Deep Dive

CLAUDE.md is a plain text file that Claude reads automatically at the start of every session in a project. It’s how you give Claude persistent instructions without repeating yourself in every prompt.

How Claude loads it

When you run claude in a directory, Claude looks for CLAUDE.md in the current directory and any parent directories up to your home folder. Files closer to the working directory take precedence.

There’s also a global ~/.claude/CLAUDE.md for instructions that apply across all your projects.

Load order (lowest to highest priority):

~/.claude/CLAUDE.md          ← global, always loaded
~/projects/CLAUDE.md         ← repo root
~/projects/src/CLAUDE.md     ← subdirectory, loaded when working inside src/

Structure

A CLAUDE.md is just Markdown. There’s no required schema — Claude reads the whole file and infers meaning from the headings and prose. A consistent structure makes the file easier to maintain.

Recommended sections:

# Project Name — AI Assistance Contract

## What This Project Is
## Tech Stack
## Project Structure
## Commands
## Scope
## Execution Constraints
## Style
## Rules for AI Assistance

See the CLAUDE.md Template for a ready-to-copy version.

What to put in each section

What This Project Is — One paragraph. What the project does, who it’s for, what it’s built with. Claude uses this to anchor every decision it makes.

Tech Stack — Language, runtime, framework, package manager. Claude needs this to write correct commands and imports.

Project Structure — A short directory tree. Without this, Claude scans your project to understand where things live — burning tokens on every request.

Commands — How to run, test, build, and lint. Claude cannot reliably infer these.

Scope — What Claude is allowed to touch. Useful for monorepos or projects where some areas are off-limits.

Execution Constraints — How you want Claude to read files. The most common: “only read files I name explicitly.” This prevents Claude from scanning the whole codebase on every request.

Style — Code conventions, naming patterns, formatting preferences. Claude will follow these without being reminded each time.

Rules for AI Assistance — Project-specific guardrails: don’t add dependencies, don’t modify config files, never invent facts.

What makes a good CLAUDE.md

Be specific about what Claude should NOT do. Positive instructions (“write clean code”) are less useful than negative constraints (“do not add npm dependencies without asking”). Constraints narrow Claude’s default behaviour down to what you actually want.

Keep it short. A 300-line CLAUDE.md gets read in full on every request, consuming tokens and diluting focus. If a section doesn’t change Claude’s behaviour, cut it.

Update it as you learn. When you find yourself repeating the same instruction in prompts, move it into CLAUDE.md. When a section stops being relevant, delete it.

Don’t put task-specific context here. CLAUDE.md is for standing instructions — things that are always true about the project. One-off task context belongs in your prompt.

✗ Vague CLAUDE.md

'Write clean code' and 'be helpful' — instructions Claude already follows by default. They don't change anything.

✓ Specific CLAUDE.md

'Do not add npm dependencies without asking. Never modify astro.config.mjs.' — these actually constrain behavior.

⚡ Why this works: Claude already tries to write clean code. Telling it what NOT to do is what changes behavior. Constraints are the high-signal part of any CLAUDE.md.

Global vs project CLAUDE.md

Use ~/.claude/CLAUDE.md for:

Your preferred response style (“be concise, skip the preamble”)
Universal coding preferences (“prefer functional patterns over classes”)
Your name and experience level, if you want Claude to tailor its explanations

Use a project CLAUDE.md for everything specific to that codebase.