Field note

Why Claude ignores your CLAUDE.md

It reads the file at session start and still does the thing you told it not to. That is usually not disobedience. It is one of four specific failures, and three of them are fixable by changing how the rule is written.

1. The rule is a prohibition with no alternative

A bare "never X" names X and supplies nothing to do instead. Anthropic's own prompting guidance puts this first: tell the model what to do instead of what not to do, and its worked example replaces "do not use markdown" with "compose your response in flowing prose paragraphs."

Rewrite every rule as when X, do Y -- a trigger and a concrete target. "Always do Y" is weaker. A bare "do Y" is weaker still, because nothing tells the model when it applies.

2. The positive rule has a scope gap

This is the one that survives the first rewrite and still fails. Take a real pair: never copy entire files between environments, always use the edit tool for targeted changes. Neither rule covers the shell's own copy command, so both are silent the moment it is reached for, and the model falls back to whatever its training makes obvious.

The test, one minute per rule: list the two or three ways the thing could actually be done -- the tool, the shell equivalent, a script that wraps it -- and check that every route lands inside your positive rule's scope. Where one falls outside, the rule you wrote is not the rule that is running.

The fix is to write the rule against the outcome rather than the tool. "For any file movement, state source and destination and wait for confirmation" covers all three routes. "Use the edit tool" covers one.

3. You are relying on a priority label

ABSOLUTE PRIORITY, CRITICAL and OVERRIDE at the top of the file do not create precedence. They are a few tokens of context on one side of a contest against everything else the model was trained and instructed to do.

Write the file as though everything else in the session has standing and your file has none. Every rule then has to earn its outcome by being concrete rather than by being labelled important.

4. The file is no longer reaching the model at all

The failure nobody detects. Long sessions compact, and a constraint stated once is ordinary conversation text to a summariser. A dropped fact announces itself, because the next answer is visibly wrong. A dropped rule does not -- the agent simply stops being constrained and behaves reasonably right up until it does the thing you forbade an hour ago.

Put a canary in the file. Add one harmless, distinctive, positive instruction -- a fixed marker on the last line of every reply, something that cannot be produced by accident. It has no competing pull from training, so it should hold one hundred percent of the time. The only interesting event is when it stops.

When the marker disappears, the model has not disagreed with you. The file has fallen out of context, been truncated, or been summarised away -- and at that moment every other rule in it is suspect too. Start a fresh session or re-assert the file. Do not re-state whichever rule you happened to notice being missed.

Watching a prohibition for this purpose tells you nothing, because prohibitions get violated under ordinary operation. Only a positive canary separates "the model disagreed" from "the file is gone."

The five-minute audit

  1. Search the file for don't, never, avoid, no, stop, refrain. Each hit is a prohibition.
  2. For each one, is there a paired positive rule? If not, delete the line -- it is decoration.
  3. For each pair, run the scope-gap test above and widen the positive until every route lands inside it.
  4. Rewrite survivors as "when X, do Y".
  5. Cut the old prohibition once the positive covers the case. Keeping both is worse than either.
  6. Count the rules before and after. Fewer than half is the normal outcome, not an overcorrection.

One more reason to cut rather than add: the file enters the prompt on every turn, not once per session. An 8,000-token file across a 40-turn session is over 300,000 tokens of overhead before any of your actual work. Anything needed only sometimes belongs in a skill, which loads on demand.

Where this came from

This page is one section of claude-md-rules, one of the Agent Skills in this set. The skills are plain SKILL.md markdown -- no install, no runtime, no dependency. Drop a folder into ~/.claude/skills/ and invoke it by name.

Four of them are free and need no signup: github.com/resilientmindset01-commits/claude-code-skills-free

Written by ResilientMindset. Not affiliated with, endorsed by, or sponsored by Anthropic. Every claim about Claude Code on this page was checked against Anthropic's own documentation on the date shown.