What is CLAUDE.md and how does it work?

CLAUDE.md is a markdown file that Claude Code automatically reads into context at the start of every session in a directory. It holds project conventions, build commands, and architecture notes that would otherwise need to be repeated in every prompt. Unlike retrieved memory, it's static context loaded in full every session.

Where do I put a CLAUDE.md file?

Project-level memory goes in ./CLAUDE.md at the repo root and gets checked into git for the whole team. User-level memory goes in ~/.claude/CLAUDE.md and applies across every project on your machine. Enterprise policy files, managed by an org admin, take precedence over both.

Can I have multiple CLAUDE.md files in one project?

Yes. Claude Code walks the directory tree and loads a CLAUDE.md from any subdirectory you're actively working in, in addition to the root file. This is useful in monorepos where different parts of the codebase (frontend, backend, packages) have distinct conventions that don't need to load when you're working elsewhere.

How do I quickly add something to CLAUDE.md without leaving my session?

Start a message with # and the text gets appended directly to the relevant memory file. For example, '# always use pnpm, never npm' saves that instruction immediately without opening an editor or breaking your workflow.

What does the /init command do in Claude Code?

/init scans the current codebase — package files, README, folder structure, test setup — and generates a starter CLAUDE.md based on what it finds. It's a fast first draft, not a finished file; review and trim the output before relying on it.

What's the difference between CLAUDE.md, hooks, and subagents?

CLAUDE.md is passive background context the agent reads once per session. Hooks are active enforcement — shell commands that run automatically on events like pre-tool-use and can block actions. Subagents are delegation — separate context windows with their own instructions for isolated sub-tasks. Use memory for 'always do X,' hooks for 'never allow X,' and subagents for 'here's how to approach this whole category of task.'

How do I import other files into CLAUDE.md?

Use @path/to/file.md syntax anywhere in the file. Paths can be project-relative or home-relative (~/), and imports support up to five levels of nesting. This keeps the root file short by pointing to detailed docs instead of duplicating their content.

Claude Code CLAUDE.md: The Complete Memory Guide (2026)

How Claude Code's memory system actually works — CLAUDE.md file hierarchy, imports, /init, /memory, and what belongs in the file vs. what doesn't.

Every Claude Code session starts by reading a file most developers never open again after the first day: CLAUDE.md. It's the single highest-leverage lever for making an agent behave like it actually works on your team — not because it's clever, but because it's the one piece of context that loads automatically, every session, before a single prompt gets typed.

Most teams either skip it entirely or dump everything they can think of into one giant file and wonder why the agent still ignores half of it. Here's how the memory system actually works, where files live, what belongs in them, and where it fits next to hooks and subagents.

What CLAUDE.md Actually Is

CLAUDE.md is a markdown file that Claude Code reads into context automatically at the start of every session in a given directory. It's not a prompt template and it's not a config file in the JSON-schema sense — it's plain instructions, written the same way you'd brief a new engineer on day one: conventions, gotchas, commands, things that aren't obvious from reading the code.

The critical distinction: this is static context loaded once per session, not retrieved memory. It doesn't grow, doesn't get searched, and doesn't decay. If it's in the file, it's in every session's context window from the first message — which means bloat costs you tokens on every single turn, not just when relevant.

The Three Levels — and the Precedence Order

Claude Code looks for memory files at three levels, and all that exist get loaded together, concatenated in this order:

Enterprise policy — managed by an org admin, applies to every user on every project, highest precedence.
Project memory — ./CLAUDE.md at your repo root. Checked into git, shared with the team. This is where conventions, architecture notes, and "how we do things here" live.
User memory — ~/.claude/CLAUDE.md. Personal preferences that apply across every project you touch — your own style rules, tool preferences, shortcuts you always want available regardless of repo.

A legacy CLAUDE.local.md pattern (gitignored, personal-to-project) still works but is deprecated in favor of imports from the project file — cleaner to reference a personal file than maintain a second untracked one.

Nested CLAUDE.md Files

You're not limited to one file per project. Claude Code walks the directory tree and will pick up a CLAUDE.md in a subdirectory when you're working inside it — useful for monorepos where the frontend and backend have genuinely different conventions and stuffing both into one root file just adds noise to every session regardless of which half you're touching.

repo/
  CLAUDE.md          # shared conventions, applies everywhere
  frontend/
    CLAUDE.md        # React/TS specifics, only loaded when working here
  backend/
    CLAUDE.md        # API/DB specifics, only loaded when working here

The Import Syntax

Keep the root file short by importing other files with @path/to/file.md syntax:

See @docs/architecture.md for system design.
See @README for project overview.
Personal shortcuts: @~/.claude/my-project-notes.md

Imports resolve relative paths from the file they're written in and support both project-relative and home-relative (~/) paths, up to five levels of nesting. This is how you keep a lean root file that points to detailed docs instead of duplicating them.

Two Fast Ways to Build One

/init scans your codebase and generates a starter CLAUDE.md from what it finds — package files, existing README, folder structure, test setup. Good starting point, bad final draft. Treat the output as a first pass, not a finished file.

# at the start of any message adds that line directly to the relevant memory file without leaving your session — say "# always use pnpm, never npm" and it's appended immediately. This is the fastest feedback loop for building the file over time: when the agent gets something wrong, correct it with # instead of letting the same mistake repeat next session.

/memory opens the active memory files in your system editor for a direct edit — use this for restructuring or deleting stale entries, not one-line additions.

What Belongs in CLAUDE.md

Build/test/lint commands — the exact commands, not "run the tests." Ambiguity here burns a turn every time.
Code style rules that aren't enforced by a linter — if ESLint already catches it, don't repeat it in prose.
Architecture facts that aren't obvious from file structure — "auth lives in middleware, not routes," "this monorepo uses workspace protocol for internal deps."
Repository etiquette — branch naming, commit message format, whether to squash-merge.
Known gotchas — the thing that broke three times until someone wrote it down.

What Doesn't Belong

Anything a linter or type checker already enforces — redundant and wastes tokens every session.
Long API references or full documentation — import them instead of pasting them, or let the agent read the source when it needs it.
Instructions for one-off tasks — that's a prompt, not memory. Memory is for things true across sessions.
Secrets or credentials — this file gets checked into git for the project-level version. Treat it like any other tracked file.

Memory vs. Hooks vs. Subagents

These three get confused because they all shape agent behavior, but they solve different problems. CLAUDE.md is passive context — background the agent reads once and keeps in mind. Hooks are active enforcement — shell commands that run automatically on specific events (pre-tool-use, post-edit) and can block actions outright. Subagents are delegation — separate context windows with their own instructions for isolated sub-tasks.

Rule of thumb: if you're writing "always do X," that's memory. If you're writing "never let X happen even if instructions get ignored," that's a hook. If you're describing "here's how to approach this entire category of task," that's a subagent's system prompt.

Debugging a Bloated File

Symptoms of a CLAUDE.md that's grown too large: the agent starts ignoring instructions near the bottom, sessions feel slower to get useful output, or the file has drifted so far from current codebase reality that following it produces wrong answers. Audit it the same way you'd audit dead code — if a rule hasn't mattered in the last dozen sessions, cut it or move it into an imported reference file that's only pulled in when relevant.