Why Claude Code Ignores Your CLAUDE.md Rules

Your project's CLAUDE.md says: "After changing src/server/auth/, run pnpm vitest src/server/auth." You reminded Claude once, and it replied, "Got it, I'll follow that." Then it changed the auth module, ran a typecheck, and skipped the focused tests entirely.

The usual reaction is to make the rule louder: bold it, add "MUST," add "never forget this." That rarely helps, because you don't yet know which layer failed. An ignored rule can come from any of these:

• the file never loaded into this session;
• the file loaded, but this change falls outside the rule's scope;
• the rule is too vague for Claude to know when to act or how far to go;
• the requirement needs real enforcement, and a written instruction can't guarantee it.

Each of these needs a different fix, so diagnose before you edit. Start by checking /context to see whether the file loaded. Then compare the change against the rule's trigger and rerun a comparable task. Anything that must be blocked every time goes to permissions or a Hook. "I'll follow it" doesn't answer any of those questions.

01 Separate Guidance from Enforcement

CLAUDE.md gives the model project knowledge and requirements, and its effect depends on loading correctly and being understood. Operations that must be blocked also need permissions, the sandbox, or a Hook.

Choose a mechanism for the requirement:

Take "migration files require human approval." In project instructions, it gives Claude a basis for its decision. If a single missed read could cause an unacceptable write, that sentence isn't enough on its own, and permissions or a Hook need to take part. Think through the consequence of breaking the rule before you decide where it belongs.

The Claude Code best practices draw this line sharply. Instructions in your prompt, CLAUDE.md, or a Skill are read by the model, which then decides what to do: it usually follows them, but there's no guarantee. Hooks, deny rules, and managed settings are applied by Claude Code every time. The guide's advice: if something has to happen every time, make it a hook, a deny rule, or a managed setting; CLAUDE.md is for guidelines, and Claude is allowed to decide a guideline doesn't apply.

02 Confirm the Rule Actually Loaded

/memory locates and edits instruction files, and it may show entries that don't exist yet. It tells you where a file is, not whether its contents reached this session.

To check what actually loaded, use /context. The Claude Code memory documentation recommends running /context all and looking for the file under Memory files.

• If the file is missing, check the startup directory, the file name, and the path.
• If it loaded but behavior differs, check the wording and look for conflicts.

A louder tone can't make up for missing content. A CLAUDE.md in a subdirectory loads only once Claude touches a file in that directory, so a different startup directory means a different set of files.

03 Retest with a Comparable Task

Once loading checks out, try two or three real tasks. Did Claude use the right command, stay in scope, and run the agreed checks? One reassuring reply isn't enough to show the rule holds. When behavior drifts, revise the rule and rerun a comparable task.

If the auth rule loaded and the focused test still didn't run, go back to the change itself. Did it actually meet the rule's condition? Does the record show the command and its result? "I'll follow it" answers neither question.

After adjusting the rule, run another auth task to see the difference. A documentation task won't exercise that rule at all. Ordinary preferences can be checked by watching behavior; actions that must be blocked need controls.

To check whether the rule is written well enough to verify, compare it with the three parts covered in how to write a CLAUDE.md that Claude actually uses: a trigger, an action, and a check.

04 Six Steps for an Ignored Rule

When a rule doesn't work, check in this order:

1. Use /memory to find the target file, then /context to confirm it loaded.
2. Check the startup directory and file scope, and confirm the current task falls within the applicable path.
3. Check that the rule includes a clear action and an observable result.
4. Search global, project, local, subdirectory, and .claude/rules/ files for conflicts.
5. Remove background, tutorials, and mechanical lists that bury important rules.
6. Decide whether the requirement needs permissions, the sandbox, or a Hook for deterministic control.

First work out whether the file didn't load, the scope was wrong, the requirement was vague, or the rule needs a different mechanism. After the fix, run the original task again.

Take step 4 seriously. The docs warn that when two instructions contradict each other, Claude may pick one arbitrarily. A global line saying "run npm test after changes" can easily collide with a project's focused-test requirement.

In the auth example, once loading is confirmed, check whether the change really sat in src/server/auth/, then see whether the global and project files ask for different tests. Fix the relevant source, rerun a similar change, and look at the commands and results. Every step targets a deviation you actually observed.

If the conclusion is "this test has to run no matter what," the requirement has outgrown CLAUDE.md. Use a Hook to run the check at a fixed point; the blocking pattern in block Claude Code from editing .env with a Hook is a good reference.

A good reply in one session doesn't prove anything. A rule takes effect when comparable tasks pass a retest, and actions that must be blocked belong to controls that don't depend on the model's judgment.