Why Claude Code Understands But Does Not Listen
Why Claude Code Understands But Does Not Listen
You write clear instructions in CLAUDE.md. The agent reads them. You can even ask "what did I tell you about X?" and it recites your instructions perfectly. Then it goes ahead and does the opposite. This is not a comprehension problem - it is a validation problem.
Understanding vs Validating
The model processes your instructions during its initial context loading. It genuinely understands what you want. But between understanding the instruction and producing output, there are dozens of intermediate reasoning steps. By the time it generates the final code or response, the instruction has been diluted by other considerations.
Think of it like a chef who reads the recipe, understands every step, but gets distracted by what looks good in the pantry and improvises anyway.
Common Failure Modes
- You say "never use em dashes" and the model uses regular hyphens for three paragraphs then drops an em dash in the fourth
- You say "use curl, not urllib" and it uses urllib because that is what its training data defaults to
- You say "do not modify file X" and it modifies file X because it seemed like the logical fix
In each case, the agent understood the rule. It just did not check its output against the rule before delivering it.
How to Force Validation
The fix is building validation into the workflow:
Explicit checklist - End your instructions with "before delivering, verify: [list of rules]." This forces a second pass.
Negative examples - Instead of just "do not use em dashes," show what wrong output looks like. Negative examples stick better than positive rules.
Post-processing scripts - Run automated checks on agent output. A simple grep for patterns you banned catches what the agent misses.
Smaller tasks - The more complex the task, the more likely instructions get lost. Break large tasks into steps where each step has fewer rules to track.
The model is not being defiant. It is being statistically normal - generating the most likely output given all its inputs, where your specific instruction is just one input among thousands.
Fazm is an open source macOS AI agent. Open source on GitHub.