Your Agent Is Ignoring CLAUDE.md. Here's Where It's Reading Instead

Bottom Line

• The agent loads the nearest CLAUDE.md, not the root one. A stray file in a subfolder silently wins.
• Check for nested files first. One find command settles it.
• AGENTS.md and CLAUDE.md can disagree. Symlink one to the other so there is only ever one file.
• Size matters. Past roughly 28-34K characters, rule-following gets unreliable. Router, not manual.
• “See skill X” is not a substitute for load-bearing rules. Keep the must-never-happen ones inline.

Symptom One: It Follows Rules You Never Wrote

This is the strange one. You ask the agent to work in packages/api/ and it starts using a commit convention from a different company, or refuses to run tests, or writes in a house style you have never specified anywhere.

That is not the model hallucinating a policy. It is reading a real file. Just not yours.

Claude Code and Codex load the nearest CLAUDE.md / AGENTS.md relative to where they are working. This is deliberate and useful — a monorepo subproject can carry its own rules. It becomes a trap when a nested file shows up by accident, which happens far more often than people expect:

• You vendored a directory from another repo and its CLAUDE.md came with it.
• A template or scaffolding tool dropped one in.
• You copied a working setup from another project as a starting point and forgot.
• A teammate added one to their subfolder and it is now governing yours.

Find every one of them:

find . -name "CLAUDE.md" -o -name "AGENTS.md" | grep -v node_modules

If that returns more than the files you deliberately wrote, you have your answer. Delete the strays or reconcile them intentionally.

Symptom Two: It Ignores Rules You Did Write

Different problem, same appearance. The root file is the only one, it is correct, and the agent still drifts — usually on the rules near the bottom.

The cause is size. A CLAUDE.md past roughly 28,000 to 34,000 characters stops being reliably always-on. It is not a hard cliff and there is no error; behavior just degrades, and the rules that degrade first are the ones you added most recently, because they are at the end of a long file.

The fix is structural, and the framing that works is: CLAUDE.md is a router and a constitution, not a manual.

What stays inline, no matter what:

• Routing tables — which file or skill owns which kind of work.
• Mandatory pre-reads — “read the ledger before quoting a number.”
• Failure modes that must never happen — the things that cost real money or real data.

What moves out into skills, docs, or reference files:

• Step-by-step procedures.
• Long examples and templates.
• Anything you wrote once for a specific task and never reused.

One caution when you do this: do not replace load-bearing behavior with a pointer only. Reducing a hard rule to “see skill X” makes the rule conditional on the agent choosing to read skill X. If a rule must hold every time, the rule itself belongs in the file; the procedure for satisfying it can live elsewhere.

Symptom Three: Two Files, Two Answers

If you run more than one agent tool, you likely have both CLAUDE.md and AGENTS.md. They started identical. They are not identical now — somebody edited one.

The fix is to remove the possibility of drift rather than trying to keep them in sync:

rm AGENTS.md
ln -s CLAUDE.md AGENTS.md

One file on disk, two names, no divergence. Check it into git as a symlink and it stays that way for everyone.

A Fast Diagnostic

When you suspect the agent is reading something other than what you think, ask it directly at the start of a session:

Before anything else: list every instruction file you loaded for this session, with full paths and approximate size, and quote the first line of each.

If the paths surprise you, you have found the bug in one message. This is faster than reasoning about it, and it also catches the case where a global user-level config is contributing rules you forgot about.

Why This Keeps Happening

Instruction files are the one part of an agent setup with no error surface. A broken import throws. A bad config key usually throws. A wrong instruction file just quietly produces different behavior, and the behavior is plausible enough that you blame the model.

That is worth generalizing: in agent tooling, the components that fail silently are the configuration ones, and configuration is therefore the first place to look when behavior is wrong but nothing is broken.

Related

• Why Claude Code’s Context Fills Up
• Claude Code Works in Your Terminal But Fails in Cron