Why Claude Code ignores your CLAUDE.md

What CLAUDE.md is, and what it is not

Claude Code carries two memory systems across sessions. A CLAUDE.md file holds instructions you write: rules, commands, layout, the things you would otherwise repeat. Auto memory holds notes Claude writes for itself, drawn from your corrections. Both load at the start of every conversation, and both are handed to the model as context.

The first thing to be clear about is where the text arrives. A CLAUDE.md is delivered as a user message after the system prompt, not inside it. Claude reads it and tries to follow it, and Anthropic is direct that there is no guarantee of strict compliance, especially for instructions that are vague or that disagree with each other. A file that reads like a policy document is not treated like one.

The second thing is that nothing in that file is enforced. Instructions shape what Claude does; they do not stop it doing something else. When two files give different guidance for the same behaviour, Claude may pick one arbitrarily, which is why a duplicated rule in two places is worse than a missing one. Anything that has to happen at a fixed moment, or must never happen at all, belongs in a hook or in managed settings rather than in prose.

Where Claude Code looks for it

There are four scopes, and Anthropic lists them in load order from the broadest to the most specific, so a project instruction appears in context after a user instruction. Every file that is found is concatenated into context rather than one replacing another, and across a directory tree the content runs from the filesystem root down to the folder you launched in. Within a single folder, CLAUDE.local.md is appended after CLAUDE.md, so your personal notes are the last thing Claude reads at that level.

Everything in the folder you started in and in every folder above it loads at launch. A file in a subfolder below you does not. Claude Code loads that one the first time Claude reads, writes or edits another file in that subfolder, and viewing a file with a Bash command that counts as a read, such as cat or head on a single file, triggers it too.

Directories you add with --add-dir are a special case. By default their CLAUDE.md files are not loaded at all. Setting CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD brings in CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md and CLAUDE.local.md from those directories, which is the switch to reach for when you keep shared rules in a folder beside the repository.

If you work across several git worktrees of one repository, a gitignored CLAUDE.local.md exists only in the worktree where you made it. The documented way to keep personal instructions across worktrees is to put them in a file under your home directory and import it, which the next section covers.

One detail of how the file is read: block-level HTML comments in a CLAUDE.md are stripped before the content reaches Claude, so you can leave notes for the humans who maintain it without spending context on them. A comment inside a fenced code block is kept.

To confirm what loaded, run /context and read the list under Memory files. A subfolder file will not appear there, because it loads on demand rather than at launch; when it does load, a line naming its path appears in the terminal. This one command settles most of the questions on the rest of this page.

Imports, and the four-hop limit

A CLAUDE.md can pull in other files with @path syntax, and imported files are expanded into context alongside the file that names them. A relative path resolves against that file rather than against your working directory, which is the detail that catches people who launch from a subfolder. Imports can themselves import, to a maximum depth of four hops.

See @README for the project overview and @package.json for the npm commands.

# Additional instructions
- git workflow @docs/git-instructions.md
- API conventions @Design\ Docs/api-conventions.md

Three parsing rules decide whether an import works. A path containing a space needs a backslash before each space, or the path stops at the first space even when it sits on a line of its own. A path wrapped in quotes is not imported at all, with or without the backslashes. And import parsing skips code spans and fenced code blocks, so a path in backticks stays as text.

An import in a project file that resolves outside your working directory is external, and the first time Claude Code meets one it shows a dialog listing the files. If you decline, those imports stay switched off and the dialog does not come back. The dialog exists to protect you from a file another person committed to a shared project, so it is worth reading the list rather than dismissing it.

Symlinks follow the same idea in a different place. A CLAUDE.md or .claude/rules/ link pointing at a network path, such as a UNC share or a path under /net or /Network, is not followed and the linked instructions do not load, because looking up the path could contact the host it names.

One expectation to drop early: imports organize a long file, they do not make it cheaper. Everything imported loads with the file that imports it, so the total context cost is the same. If the goal is to stop paying for instructions that rarely apply, a rule scoped to a path is the tool, not an import.

What belongs in one

Anthropic's test for adding a line is whether you would otherwise say it again: Claude makes the same mistake a second time, a code review catches something it should have known, you type the same correction you typed last session, or a new teammate would need the same context to be useful. That list is short on purpose. A file that records everything records nothing in particular.

Write instructions concrete enough to check. "Use 2-space indentation" has an answer; "format code properly" does not. "Run npm test before committing" can be verified; "test your changes" cannot. The same rule covers structure: grouped headers and bullets are easier to follow than dense paragraphs, and two instructions that contradict each other invite Claude to pick one at random.

Anthropic's target is under 200 lines per file, because longer files consume more context and are followed less reliably. Go past the recommended length and Claude Code warns you at startup and when you run /status, and it warns again when several files that are each within the limit add up past a combined one. Each CLAUDE.md, rules file and import counts as its own file.

What does not belong is anything that only matters in one part of the codebase. A multi-step procedure belongs in a skill, which loads when it is invoked or when Claude judges it relevant. A convention that only applies to one directory belongs in a rule with paths frontmatter, which loads when Claude touches a matching file. Both keep the file you read every session short, and the next section covers how the second one works.

When one file is not enough

The .claude/rules/ directory holds instructions split into one topic per file. Every markdown file in it is discovered recursively, so you can group rules into subfolders, and a rule with no paths frontmatter loads at launch with the same priority as .claude/CLAUDE.md. Personal rules in ~/.claude/rules/ apply to every project on the machine and load before the project's own; neither set overrides the other, so a rule and its copy in the other place should say the same thing.

The useful part is the scoping. A rule with a paths field loads only when Claude reads, writes or edits a file matching one of its patterns, and it also loads when Claude views a matching file with a Bash command that counts as a read, such as cat or head on a single file. Until then the instruction stays out of context.

---
paths:
  - "src/api/**/*.ts"
---

# API rules

- Every endpoint validates its input
- Error responses use the shared shape

Three details save an afternoon. paths is the only field Claude Code reads from a rule, and any other field is ignored without an error, so a typo in a second field is invisible. Each pattern is relative to the rule's base directory, which for a project rule is the folder holding its .claude directory and for a user-level rule is your working directory. And a rule directory linked in from outside your working directory behaves like an external import: nothing it holds loads until you approve external imports for the project, and after that only the rules without a paths field do.

A skill is the other half of this. Where a rule describes what is always true, a skill holds a procedure that loads only when you invoke it or when Claude judges it relevant, and the site's guide to Claude Code skills covers how one is built.

CLAUDE.md and AGENTS.md

Since version 2.1.277 Claude Code reads AGENTS.md on its own, but only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in your working directory or any folder above it, which is why a CLAUDE.md you forgot about can make AGENTS.md look broken. Setting Project instructions in /config to claude-md turns that off, and setting it to managed-only drops both files. AGENTS.md in Claude Code covers that file, its format, and how to keep one copy serving every tool.

Why it is not loaded: the wrong location

This is the largest family of reports, and it has one test. Run /context. If your file is not under Memory files, Claude never saw it, and no amount of rewriting the text will change the outcome. If a notice reading Instruction file not loaded appears in the conversation, the file exists and a read restriction withheld it, and the parenthesis names which one: a Read deny rule covers it, or it resolves outside your working directories while reads outside those are blocked, or a link's target could not be worked out.

Five things put a file outside the set that loads. It sits in a subfolder and Claude has not touched a file there yet, which is the on-demand rule working as documented. The directory was added with --add-dir and the extra-directories variable is not set. A claudeMdExcludes pattern in any settings layer names it. The Project instructions setting in /config is set to managed-only, which leaves out your project, local and user files, your rules and every AGENTS.md at launch. Or the file is named something Claude Code does not read, which is the next paragraph.

The name has to be one of the documented ones: CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, a markdown file under .claude/rules/, or AGENTS.md and .claude/AGENTS.md, which load when no CLAUDE.md file applies. A markdown file under .claude/ is not instructions because it is there. We measured this ourselves on 2026-09-01 against CLI 2.1.170: a session reported CLAUDE.md, .claude/CLAUDE.md and .claude/rules/*.md in its context, and did not report the other file we had put in .claude/. Anthropic's own location list says the same thing.

When the answer is not obvious, stop guessing and log it. The InstructionsLoaded hook reports which CLAUDE.md and rules files load, when they load, and why, which is the only account that covers path-scoped rules and files loaded late in a subfolder.

Why it gets cut short: too long to hold

A file that does load can still arrive incomplete, and the symptom is oddly specific: the top of your instructions is followed and the end is not. Files that load on demand, meaning a subfolder CLAUDE.md, a file it imports, and any rule loaded for a path, have their own per-file limit. Past it Claude receives only the start of the file, ending in a note telling it to read the rest with the Read tool, and until Claude chooses to do that, the later instructions are not there.

The limit depends on the context window. At 200K it is 40,000 characters; at 1M it is 200,000 characters on Claude Opus 4.6 and Claude Sonnet 4.6, and 150,000 on later models. Before version 2.1.309 the limit was not applied to files that load on demand at all, and 2.1.309 on October 22, 2026 both applied it and stopped the repeated compaction that very large nested files had been causing.

The check is one command per file. On Bash or Zsh, wc -m path/to/CLAUDE.md prints the character count, and comparing it with the number above tells you whether you have this problem. If you do, the fix is not to trim a little: move a section into its own rule, which then counts against the limit on its own.

A file that loads at launch behaves differently. It arrives whole, up to 4 MiB, and above that it does not arrive at all. So a very large root CLAUDE.md fails by vanishing rather than by being halved, which is why it is worth knowing both limits before you conclude the model is ignoring a particular paragraph.

Why it goes stale or contradicts itself

Instructions age badly in a way that reads like disobedience. A rule that names a command the project renamed, or a file that moved two releases ago, is still followed as written, and the failure looks like the model ignoring you. Anthropic's own audit finds exactly that class of problem: instructions written for older models, references to files or commands that no longer exist, and files that contradict each other. Run /doctor prompt-audit and you get a report with proposed edits, and nothing in your files changes until you ask for it to be applied. The command needs Claude Code 2.1.283 or later.

Contradictions are the other half. A user rule and a project rule that disagree, or a nested CLAUDE.md that repeats a root instruction in different words, give Claude two answers to one question, and there is no precedence rule that settles it: in both documented cases the outcome is that Claude may follow either. The cure is mechanical, which is to say each rule in one place only.

Compaction is the third version of this symptom. After /compact, a project-root CLAUDE.md is re-read from disk and re-injected, so it comes back. Nested files and path-scoped rules load again on demand, so they may not return until Claude touches a matching file. An instruction that disappeared after a compaction was either given only in conversation, or lived in a nested file that has not reloaded yet. The guide to the Claude Code context window covers what survives and what does not.

Why it is overridden: something else wins

Nothing in the loading order is a veto, so the thing above your file is rarely another CLAUDE.md. It is usually the organization's managed file, which loads first and which claudeMdExcludes cannot remove, or an instruction Claude Code adds on its own, such as the built-in commit and pull-request guidance. Anthropic's answer for the second case is the includeGitInstructions setting, which switches the built-in text off so yours is the only one in play.

Two settings do remove files outright, and both are easy to forget because they live somewhere else. claudeMdExcludes takes absolute-path glob patterns and merges across every settings layer, so an exclusion written months ago in a project file can still be biting. And the Project instructions setting in /config has a managed-only value that drops your project, local and user files, your rules and every AGENTS.md at launch. If someone turned that on to test a managed policy, this is the symptom.

The last answer is the uncomfortable one. If what you wrote is a rule rather than a preference, CLAUDE.md is the wrong mechanism, and rewriting it more firmly will not change the result. The documented routes are a hook for something that must happen at a fixed point, managed settings such as permissions.deny for something that must be blocked, and --append-system-prompt for text you want at the system-prompt level, which suits scripts more than a conversation.

Auto memory, the other half of the name

When people search for Claude Code memory they usually mean auto memory, and it is a different animal from the file you write. Claude keeps it under ~/.claude/projects/your-project/memory/, where the project name comes from the git repository, so every worktree and subfolder of one repository shares a single memory folder. The folder holds an index called MEMORY.md and one topic file per memory.

Only the index loads at the start of a conversation, and only its first 200 lines or its first 25KB, whichever comes first. Everything past that is not loaded, and the topic files are not loaded either; Claude reads them with its usual file tools when it decides it needs one. That split is deliberate, and it is why the index is meant to be one line per memory.

Each note carries a type. A user note records your role and working preferences, a feedback note records a correction you gave and an approach you confirmed, a project note records work and decisions that the code and git history do not show, and a reference note points at somewhere outside the project. Claude skips what it can work out from the codebase, and it skips what a CLAUDE.md already says, which is the practical reason not to duplicate your instructions into memory.

Auto memory is on by default in local sessions. The toggle lives in /memory and writes autoMemoryEnabled to your user settings. One limit is worth knowing: the toggle can turn it off in a background session or in a session another Claude Code session started, but it cannot turn it back on there, and it says so rather than pretending.

What people have reported

Searching Anthropic's own issue tracker for issues with CLAUDE.md in the title on October 25, 2026 returns 960 issues. A few are worth reading before you spend an evening on a file that will not behave, because each names a cost you would otherwise meet alone. Every report below is named by the person who filed it, with the day they filed it, its state when we read it, and a link to the issue.

Read the second and third rows together, because they describe the same trigger twice. A subfolder file loads when Claude reads a file there with its own tools, and Anthropic's documentation says a Bash read counts too. The reports say that in practice the Bash form did not fire the trigger, and that auto mode pushes Claude toward exactly the Bash form. Release 2.1.293 on October 7, 2026 fixed the Bash half: the changelog records that path-scoped rules and nested CLAUDE.md files now load when Claude views a file with a single-file cat, head, tail, sed -n or grep command in the Bash tool. Both reports are still open, so take them as the account of the builds that filed them and not of the build you are running, and settle it in your own session with /context.

Where Omniscio fits

Omniscio does not rewrite your instructions for you, and it has no private version of them to get out of step. What it does have is a door to the files themselves. In any project, the System Instructions group inside the Auto Context panel lists the project's CLAUDE.md, Omniscio's own project memory hub at .claude/memory/MEMORY.md, the global ~/.claude/CLAUDE.md, and the memory index Claude Code keeps for that folder. That hub is Omniscio's convention rather than one of Claude Code's files, and Claude Code loads it only if a CLAUDE.md imports it, which is the same rule the wrong-location section applies to every other filename. Clicking one of these rows opens the file; the memory index row is there to read, not to edit. The library page covers the group and why its rows are exempt from bulk selection.

The other feature worth knowing about is Agent Instructions Sync, which points the other way. You keep one canonical file, CLAUDE.md by default, and it mirrors that file into the filenames other agents read: AGENTS.md, GEMINI.md, .cursorrules, .clinerules/base.md, .github/copilot-instructions.md and .windsurfrules. It is off by default, it stamps what it writes so an edit of yours is detected rather than overwritten, and switching it off deletes nothing, which matters if you try it and change your mind. The library page covers the drift dialog.

Omniscio's own Default Agent Instructions are a separate mechanism again. Those presets reach every engine through the system-prompt bundle rather than through the CLAUDE.md you write, so your file stays yours and the presets do not appear in it.

Where Omniscio sits is at the sessions. It is a desktop app for running Claude Code and other agent harnesses side by side, built around one calm inbox rather than a wall of terminals, where agents alert you only when a decision needs you. Any model, any harness — Claude Code, Codex, OpenCode, Devin, Pi, and Hermes all supported.

Two facts worth having before you assume a default. The per-session spend cap covers sessions on a metered model key or on Omniscio credits, and a session on a Claude Pro or Max plan is never spend-capped. And the free plan is a real plan rather than a trial, covering 8 projects and 10 agents running at once, with Pro at $20/month or $192/year. The features page and the pricing page carry the detail.