CONCEPT Persistent memory that survives the fresh context window
Every Claude Code session starts with a fresh context window — Claude remembers nothing from your last conversation. CLAUDE.md is the mechanism that carries knowledge across that boundary: a plain-Markdown file you write with the standing instructions Claude should hold in every session — build commands, coding conventions, project layout, "always do X" rules. You write it; Claude reads it automatically at the start of each session.
The key word is auto-loaded. You don't attach it, reference it, or paste it in. When a session launches, Claude Code discovers the relevant CLAUDE.md files and injects their full contents into the context window before your first message. That's why it's called memory — it's the durable layer beneath each ephemeral conversation.
CONCEPT Context, not enforcement — and how it loads
This is the single most tested distinction in the cluster. CLAUDE.md shapes behavior; it
does not enforce it. If you need a rule that runs no matter what Claude decides — block a
command, run a linter before every commit — that belongs in a hook (a PreToolUse
hook executes as a shell command regardless of the model's choices), not in CLAUDE.md.
| Property | CLAUDE.md |
|---|---|
| Who writes it | You (and your team) |
| What it holds | Instructions, conventions, workflows, architecture |
| When it loads | Automatically, at the start of every session |
| How much loads | The full file, regardless of length (shorter = better adherence) |
| Delivered as | A user message after the system prompt |
| Enforced? | No — it is context. Use hooks for hard enforcement |
DIAGRAM Fresh window → CLAUDE.md bridges the gap
(fresh context window)"] --> D{"Discover CLAUDE.md
up the dir tree"} D -->|"found"| L["🟢 Inject full contents
as a user message"] D -->|"none"| E["No memory loaded"] L --> C["Claude reads it as context
(not enforced config)"] C --> U["Your first prompt runs
with project memory present"] C -.->|"need a hard rule?"| H["🟠 Use a PreToolUse hook
— enforced regardless"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class L ok; class H gate; class E bad;
CODE A minimal project CLAUDE.md
Plain Markdown at your repo root. Create it by hand, or run /init to have Claude analyze the
codebase and generate a starting file.
# CLAUDE.md — loaded automatically at the start of every session ## Build & test - Install deps with `npm ci` - Run `npm test` before committing - Use 2-space indentation (never tabs) ## Project layout - API handlers live in `src/api/handlers/` - Shared types live in `src/types/` <!-- Maintainer note: HTML comments are stripped before injection, so they cost zero context tokens. -->
/init to auto-generate a starter CLAUDE.md. If one already exists,
/init suggests improvements rather than overwriting it.TRADE-OFFS CLAUDE.md vs. a hook for a rule
✅ CLAUDE.md (context)
- Flexible, natural-language guidance
- Zero-config: just write Markdown
- Great for conventions, layout, "prefer X"
- Loaded every session automatically
⚠️ Hook (enforcement)
- Runs as a shell command at a fixed event
- Applies regardless of what Claude decides
- Needed when a rule must run (block/lint/gate)
- More setup; not natural language
EXAM TRAPS
--append-system-prompt.PreToolUse).MEMORY.md,
not CLAUDE.md.PRACTICE
Q1 · When exactly is a project's CLAUDE.md loaded into context?
Automatically at the start of every session, before your first prompt. Ancestor files (cwd and above) load in full at launch; nested subdirectory files load on demand when Claude reads files there.
Q2 · You need "run the linter before every commit" to always happen. CLAUDE.md or a hook?
A hook. CLAUDE.md is context and adherence isn't guaranteed. A hook runs as a shell command at a fixed lifecycle event regardless of what Claude decides.
Q3 · Where does CLAUDE.md sit relative to the system prompt, and why does it matter?
It's injected as a user message after the system prompt. Because it's context rather than system-level instruction, Claude may not comply strictly — especially with vague or conflicting rules.