Skip to content

Why Claude Code Ignores Your CLAUDE.md

The common advice, when Claude Code stops following your CLAUDE.md, is to keep the file short and be more specific. That advice is incomplete, and it does not explain why a file the agent followed an hour ago is ignored now. When your rules get dropped, the cause is usually one of three specific things, and the right fix depends on which one you are hitting.

This is a known, recurring problem — reported across issues such as #7777 and #15443 in the Claude Code repository. The sections below name the three causes, give a short test for which is yours, and show the fix working on a real repository.

The three reasons a CLAUDE.md gets ignored

An agent reads CLAUDE.md into its context at the start of a session. Whether it then follows those rules depends on three things that can each break on their own.

  1. The rules are competing for attention. The context window is finite. When it fills with other material — a large file the agent read, a long back-and-forth, a dump of command output — the instructions from CLAUDE.md are still present but crowded, and the signal the agent needs is buried. The output degrades even though the rules are technically there.
  2. Compaction summarized them away. In a long session the agent compacts its context to make room, replacing older content with a summary. A rule that lived only in the original CLAUDE.md text can be lost or softened in that summary, so the agent stops honoring a constraint it followed earlier in the same session.
  3. There are too many rules to follow reliably. Instruction-following degrades as the number of instructions rises — a gradual decline rather than a hard cutoff (see IFScale, on instruction-following at scale). A CLAUDE.md that has grown into a long list of every preference asks the agent to hold more than it reliably can, and the rules near the bottom are the first to slip.

A quick test for which one is yours

  • Did the agent follow the rules at the start of the session and stop later? That points to compaction (cause 2). The trigger is how long the session has run.
  • Is your CLAUDE.md a long list of many rules? That points to instruction overload (cause 3). The trigger is the size of the file.
  • Was the window full of other content — a big file, a long history, pasted output — when it slipped? That points to competition (cause 1). The trigger is what else is in context.

More than one can be true at once, but the dominant trigger tells you which fix to reach for first. The three causes, each with its tell and the lever that addresses it:

flowchart TB
    Q{"CLAUDE.md rules<br/>getting ignored — what's true?"}
    Q -->|"followed at first,<br/>stopped later in the session"| C2["Compaction<br/>trigger: how long the session has run"]
    Q -->|"the file is a long list<br/>of many rules"| C3["Instruction overload<br/>trigger: the size of the file"]
    Q -->|"window full of other content<br/>— big file, history, output"| C1["Competition for attention<br/>trigger: what else is in context"]
    C2 --> F2["Reset the session<br/>and re-state the goal"]
    C3 --> F3["Cut to an index —<br/>fewer, aimed rules"]
    C1 --> F1["Navigational file, load-bearing rules first,<br/>so they aren't crowded out"]

See it on a real repository

The effect is reproducible, and watching it is more convincing than reading about it. The Practice Repo for this course, Triage, ships with no CLAUDE.md on purpose, so you can run the same task under different instruction files and count the difference.

Run one task — "add a confidence score to the classification output" — three times: with no CLAUDE.md, with a short navigational one, and with a sharpened one that names where things live and how to verify. The agent's wasted turns shrink at each step. With no file it scans the tree and opens the wrong files; with a good file it opens the right file directly; with a sharp file it also checks its own work without being told. The full walkthrough, with the exact files and the expected result at each step, is the lab in Module 1.

The fix that holds

The durable fix is not "make it shorter" on its own. It is to make the file small because it is aimed, and to keep the session clean so the rules survive.

  • Write an index rather than a manual. The CLAUDE.md should say where things live and record the few non-obvious rules a newcomer would break, rather than restating the codebase. A short, navigational file leaves more room for the task and asks the agent to hold fewer instructions, which addresses causes 1 and 3 at once.
  • Put the load-bearing rules first. The constraints you most need honored go at the top, where they are least likely to be crowded out or summarized away.
  • Reset a long session. When the agent starts ignoring rules it followed earlier, the trigger is usually compaction; start a fresh session and restate the goal rather than pushing the cluttered one further. That is the direct fix for cause 2.

These are three levers, matched to the three causes. Deciding what belongs in the file, what the agent should fetch on demand, and when to reset is the skill of context engineering, which is the subject of Module 1.