You add a rule to CLAUDE.md. Claude Code reads it—ask, and it'll quote it back to you. Then it generates code that breaks the rule anyway.
This is one of the most-reported issues in Claude Code's issue tracker, with users documenting cases where the same rule is violated repeatedly in a single session, or where rules that held in short tasks disappear in longer ones. The cause isn't always the same, which is why "write better CLAUDE.md rules" sometimes fixes the problem and sometimes doesn't.
Six distinct problems produce this symptom. Four of them are fixable. Two of them aren't—at least not by improving CLAUDE.md. Here's how to tell which you're dealing with.
1. The file isn't being loaded
Before examining the instructions themselves, confirm that the file is loaded.
Run /memory in Claude Code. The output lists every active memory file for the current session: the user-level ~/.claude/CLAUDE.md, the project CLAUDE.md, any directory-level CLAUDE.md files, and CLAUDE.local.md. If the file you edited doesn't appear, it's not influencing the session.
Common reasons it doesn't appear:
Wrong launch directory. Claude Code loads a project CLAUDE.md from the directory where it starts. If you start it from a parent directory, it reads that directory's CLAUDE.md—not the one in the subdirectory where your project lives.
Filename case. claude.md and Claude.md aren't loaded. The filename must be exactly CLAUDE.md.
Broken import path. If your CLAUDE.md uses @import to pull in other files, a missing file or incorrect path silently drops that section.
Once /memory confirms the file is loaded and rules are still being ignored, the problem is one of the following.
2. The instructions are too abstract
Anthropic's documentation notes that "more specific and targeted instructions work better." A 2026 preprint analyzing agent rule files across 679 configurations and 5,000+ agent executions (arXiv 2604.11088) found a more specific pattern: abstract positive commands—instructions describing desired qualities—produce weaker behavioral effects than concrete negative constraints that describe what not to do.
The practical difference looks like this:
# Weak — leaves interpretation to the model
Always write clean, maintainable code that follows our architecture.
# Strong — states a condition that either holds or doesn't
Do not import from @/lib/db inside src/components/.
Do not commit console.log statements.
When adding an API endpoint, create a test file in the same directory.
The first instruction requires the model to interpret what "clean" and "maintainable" mean for the current task. That interpretation varies by context. The second states a condition that can be verified.
Audit your CLAUDE.md for instructions that describe qualities rather than conditions. Replace them with specific constraints where possible. Delete them if you can't make them concrete—abstract instructions add noise without adding reliability.
3. The file is too long
A 2026 preprint analyzed 100 production CLAUDE.md and AGENTS.md files from popular open-source repositories (arXiv 2606.15828). Forty-two percent showed "Context Bloat": instructions covering topics irrelevant to the current task, diluting the weight of important rules.
The effect isn't that the model ignores long files. It's that rules buried under noise are less reliably applied than rules in focused, shorter files. A constraint at line 450 of an 800-line file competes for attention against the immediate task—and the task pressure usually wins.
Do a content audit. Count how many lines are actually relevant to code generation versus lines that are documentation, onboarding context, setup instructions, or background explanation. Common additions that don't belong in CLAUDE.md:
- Architecture diagrams and descriptions (useful for humans, not for code generation tasks)
- How to run the development server or test suite
- Changelog and decision logs
- Anything a developer needs but the model doesn't need to generate a correct PR
Split what remains by scope. Claude Code supports directory-level CLAUDE.md files: rules specific to the API layer belong in api/CLAUDE.md, not the root. Personal preferences that shouldn't affect the rest of the team go in CLAUDE.local.md (gitignored). The root file should contain only rules that genuinely apply everywhere.
4. Instructions in different files contradict each other
Claude Code loads CLAUDE.md files from multiple locations: the user level (~/.claude/CLAUDE.md), the project root, and subdirectories. If these files contain conflicting instructions about the same behavior, the model's response to that behavior becomes inconsistent.
The same 2026 preprint found that "Conflicting Instructions" frequently co-occurs with Context Bloat. The typical pattern: a team adds project-specific rules to the root CLAUDE.md while individual developers have user-level files with different style preferences—or old directory-level CLAUDE.md files were left in place after refactors.
A related preprint (arXiv 2606.09090) found that 23% of repositories analyzed contained rules referencing code elements that no longer exist: function names, file paths, or API patterns that were renamed or deleted after the CLAUDE.md was written. A rule pointing to a module that doesn't exist is at best noise and at worst contradicts a rule describing the current structure.
To diagnose: run /memory, read through all active files, and look for instructions about the same behavior that give different answers. Remove stale references and resolve conflicts explicitly.
5. The task prompt is competing with your standing rules
The previous four reasons are problems with the CLAUDE.md file. This one is a property of how Claude Code processes context.
CLAUDE.md content loads as context—not as enforced policy. Anthropic's documentation describes it as "context for Claude," explicitly noting that it is not an "enforced configuration." The model weighs CLAUDE.md content against the task instruction, the existing code, and the most direct path to solving the immediate problem. Nothing in this process guarantees the CLAUDE.md rule wins.
This is why the same rule holds in a short focused session but degrades in a long multi-step task. As the conversation grows, task-specific content fills more of the context; CLAUDE.md rules stay constant; their relative weight falls.
The architecture-level consequence—and what deterministic pre-merge checks can do about it—is covered in our piece on why AI coding agents cause architecture drift.
For rules that must hold without exception regardless of task pressure, two mechanisms don't depend on context weighting. Claude Code's PreToolUse hooks run a script before any tool call—if the hook exits non-zero, the operation is blocked. CI checks that scan generated code run independently of the agent session entirely.
6. You have no way to tell whether the rule was followed
/memory shows what's loaded. Nothing shows whether each rule was applied to the last piece of generated code.
Without a verification step, violations accumulate quietly. You find out about them when a reviewer catches one—or when you notice a pattern weeks later.
Verification options in increasing reliability:
Behavioral testing. After changing CLAUDE.md, prompt Claude Code with a task that should trigger each major rule and check the output. Do this periodically, especially after sessions where the rule seemed to be ignored. It takes a few minutes and catches regressions before they reach code review.
Hooks. PreToolUse and PostToolUse hooks can run a script before or after specific operations. A hook that checks whether a proposed file edit introduces a forbidden import can block the operation before it's applied. This is deterministic—the check either fires or it doesn't—but it requires writing and maintaining the hook script for each constraint you want to enforce this way.
CI checks. Architecture constraints expressed as CI rules run on every pull request regardless of what happened in the agent session. A Tree-sitter query or a grep-based check that flags forbidden imports catches violations even when both the agent and the reviewer missed them. Unbx implements pre-merge architecture checks of this kind: rules that run on the output of the agent rather than relying on the agent's in-session compliance.
Fixable vs. structural
Reasons 1 through 4 are fixable by improving your CLAUDE.md: confirming it loads, writing concrete constraints, trimming noise, and auditing for conflicts. Most unexplained instruction non-compliance falls into one of these four categories.
Reason 5 is structural. A better CLAUDE.md reduces violation frequency but doesn't eliminate it—the model always balances context against task. For constraints that must hold in every commit, hooks or CI checks are the appropriate mechanism, not a more carefully written CLAUDE.md.
Reason 6 is the diagnostic issue that makes the others hard to address. Without verification, you can't tell which reason applies. Start with /memory, add a behavioral test for your most important rules, and treat CLAUDE.md as a working document that gets audited when violations appear—not as a policy you set once and trust.