C² Method7 min read

Why Claude Code ignores your CLAUDE.md, and how to fix it

CLAUDE.md is context, not configuration. Why rules get dropped as the file grows, and the router pattern that keeps the ones that matter.

Stuart Leo

You wrote the rule. It's right there in CLAUDE.md, in bold. Claude Code walked straight past it anyway.

Most advice at this point is to shout louder — capitals, IMPORTANT, a second copy of the rule further down. That makes the problem worse. The file is not being ignored at random. It is being read the way it was built to be read, and the fix is to build it differently.

Why does Claude Code ignore CLAUDE.md?

Start with what the file actually is. The Claude Code memory docs put it in one line: Claude treats CLAUDE.md and auto memory as context, not enforced configuration. The troubleshooting section is more specific. CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there is no guarantee of strict compliance, especially for vague or conflicting instructions.

That one fact explains most of the failures. A rule in CLAUDE.md is a strong suggestion sitting in the context window beside everything else Claude has read. It competes with your prompt, with the files it opened, with the task in front of it. When it loses, it's for one of three reasons.

Is your CLAUDE.md too long?

This is the most common one. The docs give a number: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.

Every rule you add dilutes the rest. A 40-line file with eight rules gives each one weight. An 800-line file with 120 rules turns each one into a line in a wall, and the one you care about this session is somewhere in the middle.

Splitting the file with @path imports doesn't fix it. The docs are explicit that imports help organise a long file but don't reduce its context cost, because imported files load together with the CLAUDE.md that imports them. Shorter means fewer lines loaded, not fewer lines in one file.

My own monorepo is the honest example. On 2026-10-11 the root CLAUDE.md was 844 lines. I trimmed it to 404 by moving reference detail out, verbatim, into five separate pages. That halved it. It is still twice the docs' target, and I won't pretend otherwise. A router is a direction to keep moving in, not a finish line. I wrote up the earlier version of this in the CLAUDE.md that got too big.

Are your rules buried in prose?

The second reason. A rule written as the fourth sentence of a paragraph about architecture is a rule Claude has to extract before it can follow it. The docs recommend grouping instructions under headings and bullets, and making them specific: "Use 2-space indentation" works better than "format code nicely".

Two checks catch most of this.

Is the rule concrete enough to verify? "Keep files organised" can't be checked. "API handlers live in src/api/handlers/" can.

Does any other file say the opposite? If two instructions contradict each other, the docs say Claude may pick one arbitrarily. This includes your user-level ~/.claude/CLAUDE.md, nested CLAUDE.md files in subdirectories, and .claude/rules/. A rule you wrote in one place and reversed in another is a coin toss.

Which rules need a hook instead of a sentence?

The third reason, and the one no amount of rewriting fixes. Some rules aren't preferences. They are things that must never happen — editing .env, pushing to main, weakening a type-check config to make an error go away. Writing those in CLAUDE.md is asking nicely.

The docs say what to do instead. If an instruction must run at a specific point, write it as a hook. Hooks execute as shell commands at fixed lifecycle events and apply regardless of what Claude decides. A PreToolUse hook that exits with code 2 blocks the tool call, and its stderr becomes the reason Claude sees.

My repo has both kinds, and the difference is instructive. .claude/hooks/pb-gate.sh runs after every Write or Edit on a file under docs/02-working/prompts/active/ and prints a checklist reminder. That one is wired up in .claude/settings.json. .claude/hooks/protect-config.sh would block edits to tsconfig.json, biome.json, vite.config.ts and any .env file with an exit code 2. That one exists but is not enabled, and my CLAUDE.md says so in plain words: config edits are NOT blocked mechanically. The rule still stands.

That sentence is the lesson. A CLAUDE.md that implies a rule is enforced when it isn't is worse than one that admits the rule is only guidance. The agent and the human both need to know which rules have teeth.

How do I turn CLAUDE.md into a router?

The router pattern answers all three problems at once. CLAUDE.md stops being the place where knowledge lives and becomes the place that says where knowledge lives. It routes. It doesn't explain.

Here is the shape of a typical file before:

# Project

## About
[three paragraphs of history and architecture]

## Tech stack
[40 lines of versions and libraries]

## Deployment
[the full runbook, 80 lines]

## Rules
- Never commit .env
- Don't push to main
[...60 more rules, mixed with tips...]

## Database
[schema notes, example queries, 120 lines]

And after:

# Project — router

> This file is a router. Rules needed every turn live here.
> Reference detail lives in docs/. Open the page a pointer names
> before working in that area.

## Invariants — verify before any auth, data or migration change
1. [The rule that must never break, in one line]
2. [The next one]

## Where things are
- Architecture: docs/03-knowledge/architecture/overview.md
- Deployment: docs/04-operations/deployment/checklist.md
- Gotchas — read before touching an area: docs/03-knowledge/gotchas/

## Session start
1. Read the latest session brief in docs/02-working/session-briefs/
2. Read the gotchas for the area you're working in

## Enforced by hooks (see .claude/settings.json)
- [rule]: blocked by .claude/hooks/[name].sh
- [rule]: guidance only, NOT enforced

## Moved sections
| Heading (verbatim) | File |
|---|---|
| Tech stack; versions | docs/05-reference/tech-stack.md |
| Database schema; example queries | docs/03-knowledge/architecture/database.md |

Three parts of that skeleton come straight from my own root CLAUDE.md.

The router line. Near the top of mine, in bold: This file is a router. The sentences after it say that rules an agent needs every turn live in the file, that reference detail lives in the pages listed under Moved sections, and that the agent should open the page a pointer names before working in that area. It tells the agent how to read the rest.

Invariants first. My first real section is a short numbered block of security invariants, headed MUST verify before ANY auth / RLS / edge-function / migration change. Position matters because the top of the file is the part nobody skims past. The rules that would cost the most if dropped go there, and only those.

The Moved sections table. At the bottom of mine is a table mapping each moved heading, word for word, to the page it now lives in. The headings are kept verbatim so a search for an old heading still lands on the table and then on the page. Nothing was deleted — the line in my file says so. An agent that needs the infrastructure topology, the email vendor rules or the tier table follows one pointer and reads one page. The other four pages stay out of its context.

The full walk-through of each section is in how to write an AGENTS.md, with a worked example, and the C² template is at /c2/docs/the-router.

Should I use AGENTS.md or CLAUDE.md?

Either works with Claude Code now, which is new enough to check your version. Per the docs, Claude Code reads AGENTS.md as project instructions when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. Reading it directly needs Claude Code v2.1.277 or later. If both files exist, it reads CLAUDE.md only. To keep one shared file, put @AGENTS.md at the top of a CLAUDE.md and add any Claude-specific lines below it.

The C² starter kit ships its router as AGENTS.md by default — the cross-agent name that Codex, Cursor and most others read — and tells you to use CLAUDE.md for Claude Code or GEMINI.md for Gemini if that's your agent. The name changes nothing about the pattern. Router, invariants, pointers, moved sections. More on writing one in how to write an AGENTS.md agents actually follow, and on where a single rules file stops scaling in C² vs native rule files.

How do I check what Claude Code actually loaded?

Before rewriting anything, confirm the file is being read at all. The docs list three tools.

  • /context all shows the CLAUDE.md files loaded at launch under Memory files. If yours isn't there, Claude can't see it.
  • /memory lists every instruction file location and opens them for editing.
  • /doctor prompt-audit asks Claude to look for outdated instructions, references to files that don't exist, and files that contradict each other, and proposes edits without applying them.

One more behaviour worth knowing. After /compact, the project-root CLAUDE.md is re-read from disk. Nested CLAUDE.md files and path-scoped rules only come back when Claude next touches a matching file. A rule that must survive compaction belongs in the root file.

The file gets read. Make it worth reading

CLAUDE.md isn't ignored because Claude is careless. It's read as context, weighed against everything else in the window, and followed in proportion to how clear and how prominent each rule is.

So keep it short. Put the few rules that must never break at the top. Move everything else to pages it points at. And take anything that truly must never happen out of the file and into a hook.

A router doesn't ask the agent to remember more. It asks it to remember where to look.

Start here: run your first C² session, or read how to write the router file.

Questions people ask

Why is Claude Code not following my CLAUDE.md?
CLAUDE.md is delivered as context, not enforced configuration, so there is no guarantee of strict compliance. The usual causes are a file that has grown too long, rules that are vague or buried in paragraphs, and instructions that contradict each other. Rules that must always hold belong in a hook, not a sentence.
How long should CLAUDE.md be?
Anthropic's docs suggest targeting under 200 lines per CLAUDE.md file, because longer files consume more context and reduce adherence. Imports with @path don't help the count, since imported files load alongside the file that imports them. Move reference detail into docs the file points to.
Does Claude Code read CLAUDE.md after /compact?
Yes, the project-root CLAUDE.md is re-read from disk and re-injected after compaction. Nested CLAUDE.md files in subdirectories and path-scoped rules reload only when Claude next works with a matching file, and instructions given only in conversation are summarised away.
How do I force Claude Code to follow a rule?
Write it as a hook. A PreToolUse hook that exits with code 2 blocks the tool call regardless of what Claude decides, and the hook's stderr is shown as the reason. Keep CLAUDE.md for guidance and use hooks or permission rules for anything that must never happen.
Does Claude Code read AGENTS.md?
Current versions can. By default Claude Code reads AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. If both exist, it reads CLAUDE.md only, unless CLAUDE.md imports AGENTS.md with an @AGENTS.md line.

Part of the C² Method. Start with the method

Put this in your repo

The C² Method is free and open. Point your agent at the kit and get started in minutes.