Claude Code not following CLAUDE.md: what to check

Did the file you expected load?

Run /context and read the list under Memory files. That list is what Claude Code loaded for this session, so a file that is not on it was never in front of Claude and no rewording will change anything. The same section of Anthropic’s troubleshooting page gives this as the first thing to check.

Run /memory to open those files and edit them in place. It also switches auto memory on or off and lists what auto memory has saved, which matters when a saved preference is arguing with the file you wrote by hand.

A file in a subdirectory is not on that list

A CLAUDE.md in a folder below the one you started Claude Code in loads on demand rather than at launch, so its absence from Memory files is expected. It loads the first time Claude reads, writes or edits another file in that folder, and a Loaded line with its path appears in the terminal when it does. To test a new one, create it from your shell rather than asking Claude to write it, then ask Claude to read a file in that folder.

The notice that names a file it withheld

If the conversation shows an Instruction file not loaded notice, a memory file that exists was kept out of the context. Anthropic prints the reason in the parenthesis right after those words, then the path on its own line below, so the notice reads Instruction file not loaded (a Read deny rule covers it): and then path: .claude/rules/shared.md. The reasons it names include a Read deny rule covering it, the file being read from outside your working directories while blocked reads are on, and the place a link on it leads not being workable. Each has its own fix: narrow the deny rule, move the file or its link target inside the working directories, or check whether the file is a link that leads back to itself and, if it is, point the link at a file that exists or put a regular file in its place. Start a new session after any of them.

Before v2.1.292 the notice put the path at the end of the same line instead of underneath it, so an older session reads differently. When more files are withheld than the notice names, a final line counts the rest.

A rule a comment swallowed

Block-level HTML comments in a CLAUDE.md are stripped before the content reaches Claude. A rule written inside <!-- --> never arrives, though it stays visible when you open the file with the Read tool. Comments inside fenced code blocks are kept, so an example is safe.

Why a loaded file is still only advice

Anthropic states where the file goes: CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself, and Claude reads it and tries to follow it with no guarantee of strict compliance, especially for vague or conflicting instructions.

The memory page makes the same point in its own voice. Claude Code treats its memory files as context, not enforced configuration, and the page sends you to a PreToolUse hook to block an action regardless of what Claude decides.

A model that reads your rule and then chooses otherwise is behaving as documented. That is the whole reason the rest of this page splits into two jobs: make the instruction better, and move anything that must hold every time into something other than prose.

Which file is read last

Four scopes can supply a CLAUDE.md. Anthropic lists them from broadest to most specific, which is also the order they appear in the context.

Nothing here overrides anything else. Claude Code concatenates every file it discovers, ordering the content from the filesystem root down to your working directory, so a project instruction appears after a user instruction and the file closest to where you launched is read last.

Inside one folder, CLAUDE.local.md is appended after CLAUDE.md, so your personal notes are the last thing Claude reads at that level. Read last is not the same as winning. Anthropic says the files it discovers are concatenated rather than overriding each other, and that if two instructions contradict each other Claude may pick one arbitrarily, which is a reason to keep them consistent rather than to rely on the order.

Two kinds of file can be silenced on purpose. claudeMdExcludes skips specific files by path or glob, which is how a monorepo stops picking up another team’s CLAUDE.md, and it cannot exclude a managed file. Excluding project from --setting-sources skips project rules.

Which file family Claude reaches for, a CLAUDE.md or an AGENTS.md, has its own precedence table and the AGENTS.md guide owns it.

The size limits that cut a file short

The published guidance is to target under 200 lines per CLAUDE.md file, because longer files consume more context and reduce adherence. That figure is advice. The mechanical behaviour Claude Code adds around your files is separate from it.

• You see a warning at startup and when you run /status once an instruction file is over the recommended length, and a separate warning at session start when several files that are each within it add up past a combined limit. Each CLAUDE.md, rules file and @path import counts as a separate file.
• A file over 4 MiB is skipped outright.
• A file that loads on demand has a per-file limit and Claude receives only the start of it past that limit: 40,000 characters on a 200K context window, 200,000 on a 1M window on Opus 4.6 and Sonnet 4.6, and 150,000 on later models.

That last limit is the one worth measuring, and it applies only to the files that load on demand: a CLAUDE.md or CLAUDE.local.md in a subdirectory of where you started, the files they import, a subdirectory’s rules, and a path-scoped rule. Past the limit, the part Claude receives ends with a note telling it to read the rest with the Read tool, and until it chooses to, the later instructions are not in its context. Run wc -m path/to/CLAUDE.md on one of those and compare. Before v2.1.309 the limit did not apply to files that load on demand at all.

Two commands that read the file for you

Run /doctor for a setup checkup that diagnoses installation, settings, extension and CLAUDE.md problems and proposes fixes you confirm. Run /doctor prompt-audit to have Claude look for outdated or conflicting instructions, references to files or commands that do not exist, and files that contradict each other. You get a report with proposed edits and nothing changes until you ask for them. The audit needs v2.1.283 or later and covers your CLAUDE.md, CLAUDE.local.md and AGENTS.md plus the rules, skills, commands, subagents and output styles under .claude/ and ~/.claude/.

Three reasons a loaded rule still gets broken

The instruction is vague

Anthropic’s first suggestion is to make the instruction specific enough to check: “Use 2-space indentation” rather than “format code nicely”. Write the rule as the thing you would verify in a diff.

Two files disagree

If two files give different guidance for the same behaviour, Claude may pick one arbitrarily, and the docs say so in those words. The audit above finds them without you reading every file.

Your rule competes with one Claude Code adds

If your CLAUDE.md sets commit or pull request rules, Anthropic names this as a cause and gives the two switches: turn the built-in guidance off with includeGitInstructions, and set the attribution text with attribution.

When the rule has to hold every time

For an instruction that must run at a specific point, such as before every commit or after each file edit, Anthropic’s advice is to write it as a hook. A hook runs a shell command at a fixed lifecycle event and applies regardless of what Claude decides to do.

For a rule about what Claude may not do, the event is PreToolUse, which runs before a tool call executes and can block it. A hook there returns a permission decision of deny and the tool call is denied. When several matching hooks answer, the most restrictive one wins, in the order deny, defer, ask, allow.

Anthropic also offers --append-system-prompt for a rule you want at the system prompt level. It is passed at launch, which the docs say suits scripts and automation better than interactive use, though it works on either; what it does not give you is a guarantee, so a rule that must hold is still a hook.

Two hooks that show you what loaded

The InstructionsLoaded hook fires when a CLAUDE.md or a rules file loads, at session start and on a lazy load during the session. Use it to log which files loaded, when, and why. Each firing carries a load reason, one of session_start, nested_traversal, path_glob_match, include or compact, which is how you tell a path-scoped rule that matched from one that never did.

A SessionStart hook can return hookSpecificOutput.additionalContext, which Claude Code adds to the conversation. It carries no blocking or decision control, so it adds text rather than enforcing anything.

The hooks guide covers the events, the JSON shapes and the matching rules in full.

What @import does and does not buy

An @path/to/file line expands that file into the context alongside the file that names it. Relative paths resolve against the importing file, an import can recurse to a maximum depth of four hops, and a path containing spaces needs a backslash before each space. A path in backticks stays text, and a path in quotes is not imported at all.

What it does not buy is room. Anthropic states that splitting into imports helps organization but does not reduce context, because imported files load together with the CLAUDE.md that imports them. The tool for a smaller context is a path-scoped rule, which loads only when Claude works with matching files.

One open report, #99032, covers an import reaching the wrong surface: in the VS Code extension an import that points outside the project folder loads in the terminal and not in the extension panel, while imports inside the project folder load in both. If a rule lives in a shared file outside the repository and works in the terminal but not in the editor, that report is the shape of it.

What survives /compact

The project-root CLAUDE.md survives compaction. After /compact, Claude re-reads it from disk and re-injects it. A nested CLAUDE.md in a subdirectory, and a rule with paths: frontmatter, load again on demand instead.

So a rule that vanishes after a compaction was given only in the conversation, lives in a nested file that has not reloaded since, or is a path-scoped rule that has not matched a file since. Anything that has to persist belongs in the root file.

What people report, dated

A GitHub search of the claude-code issue tracker for in:title "ignores CLAUDE.md" answered 126 issues on 2026-10-26, and in:title CLAUDE.md answered 49 issues created in the previous 30 days. Both totals move, which is why they carry the date they were read.

Three open reports, each read through the API on 2026-10-26:

• #104296, opened 2026-10-22: the model does not consult a user-level ~/.claude/CLAUDE.md before acting and applies the rules only after the user points at the file, repeating across sessions.
• #98870, opened 2026-10-02: the rules hold for the first stretch of a conversation and stop holding, in the reporter’s account after about ten turns.
• #99704, opened 2026-10-05: a language rule in both the global and the project CLAUDE.md is followed about two thirds of the time on one model and every time on the previous one, in the same session and the same CLI.

Three more have closed. #103036, a desktop next-step box overriding a user’s CLAUDE.md rule, closed on 2026-10-22 as a duplicate of an earlier report. #104537, agents running shell commands instead of the file tools a rule named, was closed by its own reporter on 2026-10-24 with a duplicate label. #103365, a broad report that rules and procedures were not followed, closed on 2026-10-26 carrying a needs-repro label, which is the maintainers asking for a reproduction rather than answering the claim.

One more points at the same mechanism from an unusual angle: #99642 reports a model ignoring both a global CLAUDE.md and a hook-injected harness, which is the section above with the enforcement already in place.

None of these is a rule, and an open report is not documentation of intended behaviour. They are what people are hitting, and they land on the documented causes: the file is advice, the load is conditional, and two instructions can disagree.

One cause that looks like the model ignoring you

There is a cause that none of the checks above will find, because the two things disagree while both are behaving correctly. If you run sessions on more than one coding agent, the same rules end up in several files, and each agent reads its own.

Omniscio has a feature for that. Agent Instructions Sync keeps one canonical file, your CLAUDE.md or your AGENTS.md, and writes a copy of it to whichever of the other files you pick from its list: CLAUDE.md or AGENTS.md, whichever of the two is not the canonical, then GEMINI.md, .cursorrules, .clinerules/base.md, .github/copilot-instructions.md and .windsurfrules. A copy carries the canonical file’s body plus, when the project has a .claude/rules/ directory, every .md file directly inside it, and each copy carries a short banner saying it is machine managed. A copy somebody edited by hand is never overwritten silently, because Omniscio will not write over a body it cannot match to something it wrote itself. Instead it flags the copy, and its conflict dialog offers four ways out: discard edits and restore from the canonical, promote the edited copy to become the new canonical, Stop syncing this mirror, or Stop syncing this hub. The dialog opens from the chip on the copy’s row, or from the inbox card’s action. One case offers a different set: when the copy is still tracked in git, the fix on offer is Stop tracking in git, beside Sync settings and Cancel, because re-syncing a tracked copy is reverted by the next merge.

The feature is off by default, so a project that has never turned it on has one fewer thing to check. When it is on, a copy that still matches what Omniscio last wrote is refreshed as soon as the canonical changes. The case worth knowing is the other one: a copy you or another tool edited is held and flagged rather than corrected, so a rule you added to the canonical can sit in a second agent’s file unchanged until you resolve it.

The library page, Agent Instructions Sync, covers the mirror list, the drift states and the two git modes.

A short checklist, in order

1. Run /context and confirm the file is under Memory files. If it is not there, nothing else on this page applies yet.
2. For a subdirectory file, read a file in that folder and watch for a Loaded line. Measure it with wc -m if it is long.
3. Read the rule back as a diff you could check, and make it specific.
4. Search your CLAUDE.md files, including CLAUDE.local.md, for a second instruction on the same behaviour. Run /doctor prompt-audit if you would rather not search by hand.
5. If the rule sets commit or pull request behaviour, check includeGitInstructions and attribution. If you run Omniscio, that is where its value came from: Default Agent Instructions, on by default, writes attribution as an empty commit and pull request string into the project’s .claude/settings.local.json.
6. If the rule has to hold every time, move it into a PreToolUse hook and stop relying on the text.
7. Add an InstructionsLoaded hook that logs, so the next time this happens you have the load record instead of a guess.

How we tested this

Every statement about Claude Code here was read from Anthropic’s own documentation in its Markdown form on 2026-10-26, and the version on the date line is what claude --version answered on this machine the same day: 2.1.310.

Every issue was read one at a time through the GitHub API rather than from a summary, and the two search totals the same way. Each count carries the date it was read because it moves.

Every statement about Omniscio was read from its library page and checked against the application’s source, and the ledger beside this page records the line each one rests on.

Nothing here was reproduced end to end. A model that declines a rule is not something a flag produces on request, so the mechanisms are Anthropic’s own account and the reports are the reporters’ own words, each cited where it is used.

Sources

• How Claude remembers your project, for what a CLAUDE.md is, where it lives, the load order, the 200-line guidance, the size limits, the imports, the excludes, what survives compaction, and the troubleshooting section this page is built on. Read 2026-10-26.
• Claude Code error reference, for the Instruction file not loaded notice and the three reasons it names. Read 2026-10-26.
• Hooks reference and the hooks guide, for the InstructionsLoaded event, its load reasons, and the PreToolUse deny decision. Read 2026-10-26.
• Commands, for what /context, /memory and /doctor do. Read 2026-10-26.
• Settings reference, for includeGitInstructions, attribution and the blocked-reads setting behind the notice. Read 2026-10-26.
• The claude-code issue tracker, read through the GitHub API on 2026-10-26: #104296, #98870, #99704, #99032, #103036, #103365, #104537, #99642.
• Agent Instructions Sync, Omniscio’s own library page, for the mirror list, the banner and the conflict dialog. Read 2026-10-26.

Common questions

Why does Claude Code ignore my CLAUDE.md?

Claude Code delivers your CLAUDE.md as a user message after the system prompt rather than as part of the system prompt, and Anthropic says Claude reads it and tries to follow it with no guarantee of strict compliance, especially for vague or conflicting instructions. Under that sit two mechanical causes worth ruling out first: the file was never loaded into the session, which /context under Memory files proves, or the rule is competing with another instruction.

How do I see which CLAUDE.md files Claude Code loaded?

Run /context and read the list under Memory files. A file that is not on that list was not in front of Claude. A subdirectory file will not be there, because it loads on demand once Claude reads or edits a file in that folder, and it prints a Loaded line with its path when it does. Run /memory to open and edit the files themselves.

What does the Instruction file not loaded notice mean?

A memory file exists but was withheld. The notice puts the reason in the parenthesis right after its own words, with the path on the line below: Instruction file not loaded (a Read deny rule covers it): then path: .claude/rules/shared.md. The reasons there include a Read deny rule covering the file, the file being read from outside your working directories while blocked reads are on, and the place a link on it leads not being workable. Narrow the rule, move the file inside the working directories, or, for a link that leads back to itself, point it at a file that exists or put a regular file in its place. Then start a new session.

How long should a CLAUDE.md be for Claude to follow it?

Anthropic’s guidance is to target under 200 lines per file, because longer files consume more context and reduce adherence. That figure is advice rather than a switch: the warning the docs describe fires once a file is over the recommended length, which they state separately from the 200-line target. A file over 4 MiB is skipped outright.

Can I make a CLAUDE.md rule mandatory?

Not by wording it more firmly. Anthropic describes CLAUDE.md as context rather than enforced configuration and points at a PreToolUse hook for anything that must be blocked whatever Claude decides. A PreToolUse hook runs before a tool call executes and can block it.

Does @import make my CLAUDE.md smaller in context?

No. Anthropic says splitting a file into @path imports helps organization but does not reduce context, because imported files load with the CLAUDE.md that imports them. Imports can recurse to a maximum depth of four hops. What reduces context is a path-scoped rule, which loads only when Claude works with matching files.