Your agent ignores CLAUDE.md

Why the rules get ignored

A CLAUDE.md rule is not a switch the model must obey. It is text competing for attention against everything else in the context: your latest message, the file it is editing, the thousand tokens of code it just read. As the context fills, the standing instructions sit further from the current work and their influence decays. The rule was never disabled. It was outvoted.

This gets worse the longer a session runs, and users have documented exactly that: the same rule ignored again and again, with violations escalating as the conversation grows. Each turn adds context that dilutes the instruction, and the pull to just finish the current step is immediate while the rule is abstract and far away.

So the rule being present and even acknowledged is no guarantee it is followed. Acknowledgement is cheap; the model can restate a rule and still take the higher-probability action that breaks it a moment later.

The manual fix (free, and complete)

Two things make CLAUDE.md rules stick harder without any product: make them few and sharp, and make the agent re-read them out loud before it acts. Long rule files get diluted fast, so cut yours to the handful that matter and phrase each as a testable line, not a paragraph of preference.

## Rules (keep this list short; long files get ignored)

- Edit files in place. Never regenerate a whole file to change part of it.
- Ask before adding a dependency, a new pattern, or a new top-level folder.
- Before you write code, restate the rule that applies and confirm the plan.
- If you are about to break a rule because the task seems to need it, STOP and
  ask me first. Do not decide on your own that the rule does not apply here.

## Self-check (run this before every code edit)
- Which rule above applies to what I am about to do?
- Am I about to violate it? If unsure, ask.

1. Cut the file down. Keep only the handful of rules that matter. Long instruction files get diluted as context fills.
2. Make each rule testable. Phrase rules as checkable lines, not paragraphs of preference, so a violation is obvious.
3. Force a restate-before-acting step. Have the agent name the applicable rule and confirm the plan before writing code.
4. Add an explicit stop. Tell the agent to stop and ask when it thinks a rule should not apply, rather than deciding alone.

The kit's starter CLAUDE.md is exactly this shape: short, testable, and paired with hooks that check the rules at action time instead of trusting recall.

The durable fix (the kit)

The ceiling on written rules is that nothing checks them. The durable fix moves the important rules out of prose and into hooks that run on the agent's own events, so the rule is evaluated at the exact moment the agent tries to act. When the agent goes to regenerate a whole file or skip the plan step, the hook fires and blocks it, instead of trusting the model to remember an instruction that is now buried under a thousand tokens of code.

That is the difference the kit sells: hooks enforce what markdown only suggests. The rules themselves travel to Codex, Cursor, and Antigravity through AGENTS.md, so the ask-first behavior is cross-tool, while the enforcing engine runs in Claude Code only. One install, one-time price, and your agent stops treating its own instructions as optional.

The real numbers

In our first clean-room suite, five scripted tasks with the same model in both arms, the vanilla agent asked a clarifying question first on only two of five tasks, while the kit-configured agent asked on all five. Following the ask-first rule is the single clearest behavioral gap in the data, and it is exactly the rule that gets ignored when it lives only in markdown.

The honest caveat: enforcement is not free. The hook context that makes rules stick added about a 25 percent average cost premium across the suite, and on already-clear tasks that overhead buys you nothing. You are paying for reliability on the tasks where a missed rule is expensive, not for a free lunch.

It is in Anthropic's own tracker

Ignored instructions are one of the most reported behaviors in the Claude Code tracker, including the one page here that is still open.

• #2901closed2025-07-03The most-upvoted report of the pattern: Claude Code creates deprecated legacy methods instead of editing in place, over-engineers, and ignores single-source-of-truth rules that are written plainly in CLAUDE.md. Closed as not planned with 20+ thumbs-up still on it.
• #33603open2026-03-12Still open. Hard rules in CLAUDE.md and MEMORY.md are consistently ignored, and the violations escalate with each session. The report documents four consecutive violations of rules the agent had already read.
• #40541closed2026-03-29CLAUDE.md scope and context-boundary rules ignored after being corrected five or more times in a single conversation. The reporter's summary: the agent prioritizes completing the task quickly over checking constraints before it acts.

The through-line across these reports is that a rule being present, and even acknowledged, does not make it followed. That is precisely the gap a hook closes.