Why Claude Code Ignores Your CLAUDE.md (And How to Fix It)

#ai #devtools #productivity #claudecode

If you've ever noticed Claude Code ignoring rules you carefully wrote in
your CLAUDE.md, you're not imagining it.

I spent hours adding instructions to my config file, only to watch Claude
keep doing the exact things I told it not to. After digging into how
Claude Code actually processes CLAUDE.md, I found four specific reasons
this happens.

1. Your file is too long

Claude Code starts selectively ignoring content after around 80 lines.

This isn't a bug — it's a fundamental limitation of how LLMs process
instructions. Frontier models can reliably follow approximately 150
instructions. Once you exceed that, the model starts making judgment
calls about what to pay attention to.

Most CLAUDE.md files I've seen are 100-200+ lines. Mine was 140 lines.
I had no idea this was a problem.

Fix: Keep your CLAUDE.md under 80 lines. Every line should answer
the question: "Would removing this cause Claude to make mistakes?"
If not, cut it.

2. You have contradicting instructions

This one is subtle. If your file says "use tabs for indentation" in one
section and "use 2-space indentation" in another, Claude can't follow
both — so it often ignores both.

These contradictions are hard to spot manually, especially in longer files
that have been edited over time by multiple people.

Fix: Audit your file for conflicting rules. Pay special attention to
code style, testing requirements, and workflow instructions.

3. You're wasting tokens on personality lines

Lines like these are extremely common:

You are a senior software engineer.
Be concise, helpful, and professional.
Think step by step carefully.
Always write clean, high-quality code.

These do almost nothing. Claude Code already has strong system-level
instructions baked in. Personality lines waste tokens without changing
behavior — and worse, they push your actual important instructions
further down the file.

Fix: Delete every line that doesn't give Claude specific, actionable
information about your project.

4. You're using @file references wrong

Writing @docs/architecture.md in your CLAUDE.md embeds that entire
file into every single session. This bloats your context window
immediately and leaves less room for actual work.

Fix: Instead of embedding files, tell Claude when to read them:

For architecture questions, see docs/architecture.md
For API integration issues, see docs/stripe-guide.md

How bad is your CLAUDE.md?

I scored mine after learning all this: 34/100. Grade F.

I had 4 errors and 11 warnings in a file I thought was fine.

After fixing everything: 91/100. Grade A. Claude's behavior
noticeably changed — it stopped ignoring my testing requirements and
started following my workflow instructions consistently.

I built a CLI tool to automate this analysis:

pip install agentlint-dev
agentlint score CLAUDE.md

Output:

Score: 34/100  Grade: F — Critical Issues

  Length & Density   0/25
  Specificity       19/25
  Structure         10/25
  Completeness       5/25

It catches contradictions, token waste, duplicate rules, missing
commands, @file abuse, and more. Works with CLAUDE.md, AGENTS.md,
and Cursor rules.

→ agentlint.carrd.co

The minimal CLAUDE.md template

If you want to start fresh, here's the structure that scores highest:

# Project
[2-3 sentences: what this project does]

# Stack  
[language, framework, key libraries]

# Commands
- Test: npm test
- Build: npm run build
- Lint: npm run lint

# Rules
- [specific rule 1]
- [specific rule 2]

# Never
- [thing Claude should never do]

# Verify
After changes, run tests and confirm they pass before marking done.