Claude Code ignoring CLAUDE.md? Check what it loaded

When Claude Code ignores a rule you wrote, there are two very different causes. Either the rule never reached Claude at all, or it arrived and lost out to something else. The first is common, silent and quick to fix, so check it first: run /context and look at the Memory files list. If your file isn't there, Claude can't follow it.

We set up a small project and asked Claude Code (version 2.1.312) what its instructions said. Three of the five rules we wrote never arrived. Here is what we did, what went missing and why, and what to do when the rule did arrive and still gets ignored.

The test#

The project had a CLAUDE.md at the root, a second file it imported, an AGENTS.md, and a CLAUDE.md in an api/ subfolder. Each one gave Claude a different word:

CLAUDE.md          "The codeword is KIWI."  plus two imports:
                     @notes/style.md        "The color word is TEAL."
                     @"notes/quoted.md"     "The animal word is OTTER."
AGENTS.md          "The secret word is MANGO."
api/CLAUDE.md      "The api word is CEDAR."

Then we asked, with no tools allowed: "list every word your project instructions give you."

Running /context showed the same thing: under Memory files it listed CLAUDE.md and notes/style.md, and nothing else.

Why three rules went missing#

A quoted import is not an import#

@path/to/file.md inside a CLAUDE.md pulls that file in. Wrap the path in quotes and it is ignored, with no warning. For a path with spaces, put a backslash before each space instead: @Design\ Docs/api.md. Without the backslashes, the path ends at the first space.

Imports resolve relative to the file that contains them, not the folder you started Claude in, and they can nest up to four levels deep.

AGENTS.md is skipped when there is a CLAUDE.md#

Claude Code reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in your working folder or any folder above it (your personal ~/.claude/CLAUDE.md doesn't count). As soon as you add a CLAUDE.md, an AGENTS.md next to it goes quiet.

This catches teams that use Codex too, since Codex reads AGENTS.md. The fix is one line at the top of CLAUDE.md:

@AGENTS.md

Now both agents read the same rules, and you keep them in one place. (We cover this setup in Claude Code and Codex in the same repo.) You can also turn on reading both files in /config, under Project instructions.

A subfolder's CLAUDE.md loads when Claude works there#

CLAUDE.md files in the folders above where you started Claude load at launch. Files in subfolders load on demand: the first time Claude reads a file in that folder. When we asked Claude to read api/x.ts first, it then knew CEDAR. When it loads, a Loaded line with the path shows in the terminal.

So a rule in api/CLAUDE.md like "never change the public routes" doesn't apply until Claude touches a file in api/. Put rules that must hold before then in the root file.

When the rule arrived and still gets ignored#

If /context lists the file, Claude has read it. It treats CLAUDE.md as strong guidance, not as code that runs, so these are the usual reasons it drifts:

• The rule is vague. "Format code nicely" gives Claude nothing to check. "Use 2-space indentation" does.
• Two rules disagree. A root file says one thing, a subfolder file or an import says another, and Claude picks one. Read them side by side.
• The file is too long. Anthropic suggests under 200 lines per CLAUDE.md. Every extra line competes with the ones that matter. Imports don't help with length, since imported files load in full.
• It was said, not written. A rule you typed in the chat isn't in any file, and it fades as the session grows. We covered what survives a long session in Claude Code forgets rules after compaction.
• Claude Code has its own guidance on the same thing. Rules about commit messages or pull requests compete with built-in ones. The includeGitInstructions setting turns the built-in git guidance off.

When it must happen every time, make it a hook#

If a rule must never be broken (run the tests before finishing, never edit .env, format after every edit), don't leave it to judgment. A hook runs a command at a fixed point whatever Claude decides. For tests, see make Claude Code run the tests before it says done.

Checklist#

1. Run /context and find your file under Memory files. /memory lists the files and opens them for editing.
2. No quotes around @ imports; backslash before spaces.
3. Have both CLAUDE.md and AGENTS.md? Put @AGENTS.md in CLAUDE.md.
4. Rules that must hold from the first prompt go in the root file, not a subfolder.
5. Keep each file under 200 lines, specific, with no contradictions.
6. Anything that must happen every time becomes a hook.

Where Joxo fits#

Rules matter more when several people's agents work on one project: everyone's agent should follow the same ones. Joxo keeps a shared list of the team's rules and gives each agent the right one at the moment it applies, so a correction you make once reaches your teammates' agents too. Setup is one line pasted into your agent.

Frequently asked questions#

How do I check if Claude Code loaded my CLAUDE.md?#

Run /context in the session and look under Memory files. Every CLAUDE.md, CLAUDE.local.md and imported file loaded at launch is listed there with its size. A subfolder's CLAUDE.md appears only after Claude reads a file in that folder.

Does Claude Code read AGENTS.md?#

Yes, but by default only when there is no CLAUDE.md or CLAUDE.local.md in your folder or above it. To use both, put the line @AGENTS.md in your CLAUDE.md.

Why is my CLAUDE.md import not working?#

The most common causes are quotes around the path, which stop the import, and spaces in the path without a backslash before each one. Paths are relative to the file that contains the import.