Why Claude Code Ignores CLAUDE.md: Loading, Adherence, and Enforcement

#ai #programming #productivity #claude

When Claude Code appears to ignore CLAUDE.md, rewriting the file is often the wrong first move.

The symptom can come from three different layers:

The instruction never entered the active session.
The instruction loaded, but the model did not follow it in the task.
The instruction describes an outcome that should have been enforced outside the model.

These layers need different fixes.

1. Prove the file loaded

Run /context and inspect the Memory files section. If the intended CLAUDE.md is absent, investigate the working directory, filename, exclusions, nested scope, and active settings sources.

Do not strengthen the wording of a file that is not in context.

2. Check scope and conflicts

A loaded instruction can still be irrelevant to the current path or conflict with user, project, nested, or path-scoped instructions.

Replace vague rules with observable behavior. A useful rule names:

when it applies;
the action to take;
the artifact or command that proves completion; and
the condition that blocks completion.

For example, "follow our API standards" is difficult to verify. "When editing src/api/**, run npm run test:api and report the failing test if it does not pass" is testable.

3. Test behavior instead of recall

Do not ask the model whether it read the file. Correctly repeating a rule proves recall, not compliance.

Run one bounded task where the rule creates a visible difference. Inspect the diff, command output, or generated artifact outside the chat. If the result matters, repeat the task in a fresh session.