CLAUDE.md Not Working? 9 Fixes, Checked Against the Docs

Published 2026-10-24 · 6 min read · by AgentKit Co

You wrote a CLAUDE.md, and Claude Code still does its own thing. The cause is almost always on a short list: the file isn't loading, it loads somewhere you didn't expect, or it loads and is too long, vague or contradictory to follow.

This page goes through that list in order. Everything here was checked against Anthropic's memory docs on 2026-10-24. Claude Code changes fast, so re-check anything you depend on.

One thing to know first: the docs say CLAUDE.md is delivered as a user message after the system prompt, not as part of the system prompt. Claude reads it and tries to follow it, but there is no guarantee of strict compliance. Fixes 1 to 6 make sure it loads; fixes 7 to 9 make it more likely to be followed.

1. Check whether it loaded at all

Run /context in a session and look under Memory files. If your file isn't listed, Claude can't see it, and nothing else on this page matters until it is. /memory lists every CLAUDE.md location and opens the files in your editor.

If you see an Instruction file not loaded notice, the docs have an errors page entry for it.

2. The file is in the wrong place

Only these locations load:

Claude Code loads CLAUDE.md and CLAUDE.local.md from the directory you launched it in and every directory above it. A file in a folder next to your project, or in a folder you only reference, won't load.

If you add a directory with --add-dir, its CLAUDE.md is not loaded by default. Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 to change that.

3. Your subdirectory CLAUDE.md loads later than you think

A CLAUDE.md in a subfolder of your working directory doesn't load at launch, so it won't show under Memory files. It loads the first time Claude reads, writes or edits a file in that subfolder, and you see a Loaded line with its path.

To test one, create it from your shell rather than asking Claude to write it, then ask Claude to read a file in that folder.

The same goes for rules in .claude/rules/ with paths: frontmatter: they load only when Claude touches a matching file. If the YAML in that frontmatter doesn't parse, the rule loads as if it had no paths at all. claude --debug shows the parse error.

4. An AGENTS.md is involved

Claude Code can read AGENTS.md directly (v2.1.277 or later), but by default only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. That cuts both ways:

• Adding a CLAUDE.local.md for your own notes makes Claude stop reading the team's AGENTS.md.
• A stray CLAUDE.md in a parent folder does the same.

The simplest fix is a CLAUDE.md next to your AGENTS.md that imports it:

@AGENTS.md

## Claude Code
- Use plan mode for changes under src/billing/.

You can also set Project instructions to claude-md-and-agents-md in /config to load both. A CLAUDE.md that only says "read AGENTS.md" in words doesn't work reliably: Claude sees AGENTS.md only if it decides to open it. For how the three formats compare, see AGENTS.md vs CLAUDE.md vs Cursor rules.

5. An import silently didn't load

@path imports have a few sharp edges from the docs:

• Imports inside backticks or code blocks are skipped on purpose.
• A path with spaces needs a backslash before each space. A quoted path isn't imported at all.
• Relative paths resolve from the file doing the importing, not from your working directory.
• Imports can nest at most four hops deep.
• An import that points outside the project (like @~/.claude/my-notes.md from a project CLAUDE.md) needs a one-time approval. If you declined that dialog, those imports stay off and the dialog doesn't come back.

6. Something excluded it

In a monorepo, check your settings for claudeMdExcludes. Its glob patterns match absolute paths and merge across user, project, local and managed settings, so a teammate's project setting can exclude a file you expected. If Project instructions is set to managed-only, your project, local and user CLAUDE.md files are left out at launch.

7. It's too long, or the end is cut off

The docs say to aim for under 200 lines per file; longer files use more context and reduce adherence. You get a startup warning (also in /status) when a file is over the recommended length. Splitting into @path imports helps you organize but doesn't save context, because imports load with the file that imports them. Claude Code skips a file over 4 MiB entirely.

Files that load on demand (subdirectory CLAUDE.md files, rules in a subfolder's .claude/rules/, and path-scoped rules) have a per-file character limit. Over it, Claude gets only the start of the file plus a note to read the rest. The limit is 40,000 characters with a 200K context window. Check yours with:

wc -m path/to/CLAUDE.md

Move instructions that matter for one part of the codebase into path-scoped rules, and multi-step procedures into skills.

8. The instruction is vague or contradicts another one

Claude follows instructions it can verify. From the docs:

• "Use 2-space indentation", not "format code properly"
• "Run npm test before committing", not "test your changes"
• "API handlers live in src/api/handlers/", not "keep files organized"

If two files disagree, Claude may pick one arbitrarily, and files are concatenated rather than overriding each other. Look across your user file, project file, nested files and .claude/rules/. Recent versions (v2.1.283 or later) can do this for you: /doctor prompt-audit reports outdated, broken or conflicting instructions and changes nothing until you say so.

Also check whether you're fighting Claude Code's built-in guidance. If your CLAUDE.md sets commit or PR rules, turn off the built-in ones with the includeGitInstructions setting and set attribution yourself.

9. It vanished after /compact

The project-root CLAUDE.md survives compaction: Claude re-reads it from disk. What doesn't survive are instructions you only gave in chat, plus nested CLAUDE.md files and path-scoped rules until they load again. If it matters every session, put it in the file.

When it must happen every time, use a hook

CLAUDE.md is guidance, not enforcement. If something has to run at a fixed point (format after every edit, block writes to .env, run tests before a commit), make it a hook. Hooks are shell commands at lifecycle events and run regardless of what Claude decides. See Claude Code hooks examples for ones you can paste, and settings.json permissions to deny an action outright.

To see exactly which instruction files load and why, the docs suggest an InstructionsLoaded hook that logs each one.

Quick checklist

1. /context: is the file under Memory files?
2. Is it in one of the four loaded locations, at or above your launch folder?
3. Subfolder file or path-scoped rule? Touch a matching file first.
4. Any AGENTS.md, CLAUDE.local.md or parent CLAUDE.md changing what loads?
5. Imports: backticks, spaces, relative paths, declined approval?
6. claudeMdExcludes or managed-only?
7. Under 200 lines, and under the on-demand character limit?
8. Specific, non-conflicting instructions? Try /doctor prompt-audit.
9. Must-happen rules moved into hooks?

If you'd rather start from files that already follow these rules, see CLAUDE.md examples or the Agent Config Kit, which ships drop-in AGENTS.md, CLAUDE.md and .claude/rules templates for 12 stacks. Using Cursor too? Cursor rules not working covers the same problem there.

Keep reading