CLAUDE.md: a plain Markdown file that gives Claude Code instructions about a project. Claude adds the file to its context, then uses it while it reads code, plans work, edits files, and runs commands.
CLAUDE.md is not a model, a database, or a hidden configuration format. It is a document for guidance that should apply across many tasks.
Last reviewed July 18, 2026. Maintained by the Plannotator project.
When does Claude Code load CLAUDE.md?
Claude Code looks for instruction files when a session starts. It also loads more specific files when it begins working in a nested directory.
Claude also reads applicable
CLAUDE.md files in parent directories. This lets a monorepo keep shared instructions at the root and package-specific instructions closer to each package. Anthropic documents the full search order in its Claude Code memory guide.
How often does Claude read the file?
Claude loads the applicable files when a session starts. It does not reread everyCLAUDE.md before every reply.
If you edit the file during a session, Claude picks up the change after the next /compact or when you open /memory. Otherwise, start a new session. After compaction, Claude restores the root instructions. It reloads a nested file when it next reads a file in that directory.
An imported file also consumes context. Imports can reduce duplication, but they do not make the imported text free.
Which CLAUDE.md file wins?
Claude combines the files it finds from broad scope to narrow scope. A file closer to the current work appears later in the combined context, but it does not erase the broader file. Do not rely on conflicting instructions. Keep shared rules at the project root. Put only the differences in nested or local files.Is CLAUDE.md the same as memory?
No. Claude Code uses the word memory for more than one feature, but the files have different owners and jobs.
Treat
CLAUDE.md as standing instructions, not as a diary of past sessions. Auto memory is machine-local. Claude loads the first 200 lines of its MEMORY.md at startup and reads linked topic files when needed. The Claude Code memory guide explains both systems.
Can Claude ignore CLAUDE.md?
Yes. Claude Code addsCLAUDE.md as a user message after its system prompt. The file guides the model, but it does not enforce a rule.
Use hooks or permissions when a check must run every time. Use CLAUDE.md to explain what good work looks like and which commands Claude should use.
How can you check what Claude loaded?
Run/memory in Claude Code. It lists the instruction files loaded for the session and lets you open them. For deeper debugging, the InstructionsLoaded hook can log each loaded instruction file.
What should go in CLAUDE.md?
Include facts Claude cannot safely infer from the repository:- build and test commands;
- rules that differ from common defaults;
- files or directories it must not change;
- checks required before work is complete;
- links to detailed docs Claude should read only when needed.
How is CLAUDE.md different from AGENTS.md?
Claude Code readsCLAUDE.md by default. It does not load AGENTS.md by name.
If your team uses both Claude Code and agents that support AGENTS.md, keep one source of truth. A CLAUDE.md file can import the shared file with @AGENTS.md, or you can use a symbolic link where your tools and operating systems support one. Anthropic describes this setup in its CLAUDE.md context guide.