ebelephant.broker
All answers

Claude Code, Codex and Cursor

Why does Claude Code ignore my CLAUDE.md instructions?

Alexandru Lupascu, CTO & Co-founder · Updated

Claude Code usually "ignores" CLAUDE.md for one of four reasons: the file did not load, it is too long, its instructions are vague or contradict each other, or the rule needs enforcement that CLAUDE.md cannot give. According to Anthropic's Claude Code memory docs, CLAUDE.md is delivered as a user message after the system prompt, and Claude treats it "as context, not enforced configuration". It shapes behavior but does not force it. Anthropic recommends keeping each CLAUDE.md under 200 lines, because longer files consume more context and reduce adherence.

How do you check whether your CLAUDE.md loaded?

Run /context and look under Memory files: if your CLAUDE.md is not listed there, Claude Code cannot see it. Then work through Anthropic's troubleshooting steps:

  1. Check the location. Project instructions load from ./CLAUDE.md or ./.claude/CLAUDE.md, personal ones from ~/.claude/CLAUDE.md, and private project notes from ./CLAUDE.local.md.
  2. Files in your working directory and the directories above it load at launch. A CLAUDE.md in a subdirectory loads only after Claude reads, writes or edits a file in that subdirectory.
  3. If the repository also has an AGENTS.md, Claude Code reads it by default only when no CLAUDE.md or CLAUDE.local.md exists in or above the working directory. See CLAUDE.md vs AGENTS.md.
  4. Add an InstructionsLoaded hook to log which instruction files loaded, when and why.

Why does a long or vague CLAUDE.md get ignored?

A CLAUDE.md that loaded is still followed less reliably when it is long, vague or inconsistent. Anthropic's Claude Code best practices page explains that every line of CLAUDE.md "takes a little of Claude's attention on every task, whether it's relevant or not", so the file should hold only what Claude "couldn't work out from the code itself". The memory docs add three fixes. Write rules concrete enough to verify, such as "Use 2-space indentation" instead of "Format code properly". Remove contradictions, because when two instructions disagree "Claude may pick one arbitrarily". Check whether your rule competes with Claude Code's own guidance: if CLAUDE.md sets commit rules, turn off the built-in ones with the includeGitInstructions setting. Running /doctor prompt-audit reports outdated or conflicting instructions across your CLAUDE.md, rules and skills files.

What should you use when a rule must always be followed?

Use a hook or a managed setting when an instruction has to hold every time. Anthropic's Claude Code docs describe hooks as shell commands that run at fixed lifecycle events and "apply regardless of what Claude decides to do"; a PreToolUse hook can block a tool call before it runs. Settings such as permissions.deny are enforced by the Claude Code client, not by the model. One more cause looks like ignoring but is not: an instruction you gave only in chat is summarized away when the conversation compacts, while the project-root CLAUDE.md is re-read from disk after /compact. See what Claude Code forgets when it compacts. For scripts and automation, the --append-system-prompt flag places instructions at the system prompt level.

Where does a runtime like elephant.broker fit?

CLAUDE.md is the right tool for one repository with stable conventions: it is plain text, versioned in git and read by every session. It gets harder when the right instruction depends on the task, when procedures span many repositories and agents, or when a security reviewer asks which instructions the agent actually saw. elephant.broker, a pluggable runtime for AI agents, addresses that case: on every turn it places versioned procedures for the task at hand where the model pays attention, and its tamper-evident audit log records every read, placement and write-back. elephant.broker connects to Claude Code through an MCP server, native plugins or a REST API, with your model and harness unchanged. For one developer with a short, specific CLAUDE.md, the built-in file is enough.

Sources

Product details come from each vendor's public documentation as viewed on 2026-10-28 and may have changed. Product names are trademarks of their respective owners; elephant.broker is not affiliated with them.