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

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:

1. The instruction never entered the active session.
2. The instruction loaded, but the model did not follow it in the task.
3. 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.

4. Move critical boundaries out of prose

If a failure must never occur, CLAUDE.md should explain the boundary but should not be its only control.

Use the mechanism that can reject the bad outcome:

• permissions or a sandbox for access boundaries;
• PreToolUse hooks for command checks;
• formatters and linters for deterministic style;
• tests for behavior;
• CI for release gates; and
• human approval for irreversible external actions.

The practical rule is simple: use instructions for orientation and use tooling for enforcement.

The complete six-step diagnostic, current Anthropic sources, compaction checks, and a local decision tool are available in the original TGWise guide:

https://tgwise.com/guides/claude-code-ignoring-claude-md/

Disclosure: I maintain TGWise Agent Lab.