Claude Code repeatedly fails to follow project-level CLAUDE.md instructions

Problem

Claude Code reads CLAUDE.md project instructions but does not reliably check them before acting. This results in repeated violations of explicitly documented rules, even when the rules are simple, prominent, and written as direct behavioral gates.

Failure patterns observed

1. Treating questions as requests — User asks "so I have to edit it in JavaScript rather than in fields?" (a question). Claude immediately reverts the code change without being asked. CLAUDE.md rule: "Read the Prompt Literally — do not reinterpret what they said into a different solution."

1. Skipping pre-push checks — CLAUDE.md requires running check-dataflow.py before pushing workflow JSON changes. Claude pushes without running the check, even when the rule is in the top section of the file.

1. Incomplete downstream verification — After modifying a workflow node, Claude checks 3 downstream nodes and declares it done. The workflow has 40+ nodes. User has to ask "did you do ALL the downstream checks?"

1. Skipping the change safety gate — CLAUDE.md has a 4-step checklist (check state, map dependencies, research syntax, tell user) that applies to EVERY change. Claude skips steps when it feels confident, which is exactly when the checklist matters most.

What has been tried

• Simplified CLAUDE.md from 750 lines to ~120 lines (well under the recommended 200-line limit)
• Moved reference material to files so CLAUDE.md contains only behavioral rules
• Written rules as trigger-action gates (IF trigger THEN mandatory action)
• Included specific past failure examples directly in CLAUDE.md
• Added "Confidence does not exempt you from the checklist" explicitly

None of these interventions have reliably changed behavior. Claude acknowledges violations when caught but repeats them in the next action.

Core issue

The problem is not that Claude cannot read or understand the rules. When asked, Claude can recite them accurately. The problem is that Claude does not check the rules before acting. It acts first, then when the user points out the violation, it acknowledges and apologizes — but the damage is already done.

This is particularly problematic for rules that exist precisely because the default behavior is wrong (e.g., "do not treat a question as a request to change code"). The rule exists to override the default, but the default fires before the rule is checked.

Environment

• Claude Code CLI
• CLAUDE.md with ~120 lines of behavioral rules
• directory with 11 reference files
• Model: Claude Opus 4.6