cachly← All posts
Rules files

Claude Code Ignores CLAUDE.md: What Actually Helps

You wrote the rule. It is in CLAUDE.md. Claude Code does the opposite anyway. I went through what Anthropic's docs say about this, what helps, and what I can and cannot claim for my own tool.

You are not the only one. The issues "CLAUDE.md Mandatory Rules Consistently Ignored Across Multiple Repositories" and "Claude Code frequently violates explicit project and user instructions defined in CLAUDE.md files" describe the same pattern. The rule is present, and it is passed over. I will not guess at a cause for any single report. The docs give a frame for the whole class.

What the docs say CLAUDE.md is

The memory page states that Claude treats CLAUDE.md "as context, not enforced configuration". In the troubleshooting section it says the content is "delivered as a user message after the system prompt, not as part of the system prompt itself". It adds: Claude reads it and tries to follow it, but there is no guarantee of strict compliance, especially for vague or conflicting instructions.

So a CLAUDE.md rule is a strong hint. It is not a lock. That changes what to try.

Check one: does Claude see the file?

Before you rewrite anything, confirm the file is loaded. The docs suggest running /context all and looking at the list under Memory files. /memory opens the files. A CLAUDE.md in a subdirectory does not appear there, because it loads on demand when Claude reads a file in that directory.

Also check for a competing instruction. The docs point out that Claude Code adds its own guidance, for example for commits and pull requests. If your CLAUDE.md sets different commit rules, the docs name two settings, includeGitInstructions and attribution, to turn off the built-in ones.

Check two: length and wording

The docs target under 200 lines per CLAUDE.md and say longer files consume more context and reduce adherence. They also say imports with @path do not help here, since imported files load together with the file that imports them.

On wording, the docs give one example worth copying:

# Works better
Use 2-space indentation.

# Works worse
Format code nicely.

If two instructions contradict each other, the docs say Claude may pick one arbitrarily. This also holds across files: a user-level rule and a project rule can both apply, and neither overrides the other. A run of /doctor prompt-audit looks for outdated or conflicting instructions.

Check three: should it be a rule at all?

Some of what people put in CLAUDE.md is a requirement, not a preference. "Never commit to main." "Run the linter after each edit." The docs say to use a hook for those. Hooks run as shell commands at fixed points and apply regardless of what Claude decides. For blocking an action, the page recommends a PreToolUse hook.

A minimal example in .claude/settings.json. The script runs before every Bash call and can refuse it. Check the hooks guide for the exact input and exit-code format before you copy it:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "node .claude/hooks/no-main-commit.mjs" }
        ]
      }
    ]
  }
}

Rules that only matter in part of the repo can move into .claude/rules with a paths field. Those load when Claude works with matching files.

Check four: did it fall out of the conversation?

The docs also answer "instructions seem lost after /compact". The project-root CLAUDE.md is re-read from disk and re-injected after /compact. What can vanish is an instruction you gave only in chat, a nested CLAUDE.md that has not reloaded, or a path-scoped rule that has not matched a file since. The fix they give: put chat-only instructions into CLAUDE.md.

What is left: knowledge that is not a rule

After those four checks, a gap remains. Some things you want Claude to remember are not rules. They are events. We fixed a webhook bug in March, and the cause was the parsed body. We chose a library, and here is why. These do not fit a 200-line file, and they matter only on some tasks.

One option is a decisions folder, with CLAUDE.md pointing to it. Another is a memory tool that shows an entry when the task matches. I build one, cachly, so here is exactly what it does, from its source.

cachly installs a UserPromptSubmit hook for Claude Code. When you send a prompt, the hook takes the prompt text, sorts the stored lessons against it, and adds the matching ones to that turn. A short prompt such as "ok" or "thanks" injects nothing, because the match needs at least two distinct content words. A PreToolUse hook does a similar lookup with the path of the file Claude is about to edit. If the lookup fails, the hook returns nothing and exits normally, so it cannot block your turn.

A lesson is stored once, after a fix:

learn_from_attempts(
  topic="stripe:webhook-raw-body",
  outcome="success",
  what_worked="Verify the signature on the raw body: await req.text(), not req.json().",
  what_failed="Parsing the body first broke signature verification.",
  severity="major",
  file_paths=["app/api/stripe/webhook/route.ts"]
)

Next time you ask for a webhook handler, that lesson is added to the turn.

The limits

Measure it on your own repo

Do not take my word, or anyone's. Pick one rule that keeps getting skipped. Run the same small task ten times, in fresh sessions, and count the misses. Change one thing: shorten the file, reword the rule, or move it into a hook. Run ten more. Write both counts down. Ten runs prove little, but they show whether the change is worth keeping.

Related reading: AGENTS.md or CLAUDE.md? One Source for Every AI Tool for which tool reads which file, Claude Code Persistent Memory for memory across sessions, and Cachly vs CLAUDE.md for how the two compare.

cachly.dev

For solo developers, teams and whole companies

Explain it once. Every AI knows it.

cachly keeps what you explain to your AI in every session. Claude Code, Cursor, Copilot and Windsurf read your rules, decisions and solved bugs: for you alone, for your whole team and for every team in your company. Servers in Germany, with SSO and a DPA for companies.

Servers in the EU · one command, restart your editor, done · 1 project free

Four ways to install

Claude Code
/plugin marketplace add cachly-dev/cachly-mcp
/plugin install cachly-brain@cachly

Then turn on auto-update once: /plugin → Marketplaces → cachly → Enable auto-update

Any MCP editor
npx @cachly-dev/mcp-server@latest autopilot