Your CLAUDE.md Is Probably Broken — Here's How to Tell (And Fix It)

The most important file in your Claude Code setup is also the easiest to get wrong. Here are the silent failure patterns nobody talks about — and how to diagnose them in 5 minutes.

---

CLAUDE.md is the most important file in your Claude Code setup.

It’s also the file most developers write once, forget about, and then wonder why Claude keeps ignoring their rules.

Here’s the uncomfortable truth:

Claude actively filters what it follows from CLAUDE.md rather than treating everything as a permanent command.

Your file has an instruction budget — and most production files exceed it.

Which means:

Your CLAUDE.md is probably silently broken.

---

Why CLAUDE.md Breaks Silently

Claude Code injects a system reminder above your file:

“This context may or may not be relevant to your tasks.”

This means Claude evaluates which rules to follow per turn.

On top of that, models typically follow ~150–200 instructions before compliance drops.

Claude Code itself uses ~50 of those.

You’re left with roughly 100–150 instruction slots.

If your CLAUDE.md exceeds that, rules are dropped silently.

This is why behavior feels “random.”

It’s not random — it’s budget overflow.

---

The 5 Silent Failure Patterns

Failure 1 — The Kitchen Sink File

# BAD — too many rules
- Use TypeScript strict mode
- Prefer functional components
- Use arrow functions
- Destructure props
- Use const over let
- Avoid any type
- ... (30+ more)

Claude prioritizes early rules and drops later ones.

Fix: Keep the file under 60 lines.

Ask: “Would removing this cause a mistake right now?” If not — cut it.

---

Failure 2 — Rules Without Alternatives

# BAD
- Never use console.log
- Never use var

This creates ambiguity and interrupts flow.

# GOOD
- Never use console.log; use src/utils/logger.ts instead
- Never use var; use const or let when reassignment is required

Rule: Every “never” must include an alternative.

---

Failure 3 — @file Overuse

# BAD
@docs/architecture.md
@src/utils/api-client.ts

This embeds entire files into every session, consuming context.

# GOOD
- See docs/architecture.md for system design
- See src/utils/api-client.ts for API patterns

Reference files — don’t preload them.

---

Failure 4 — Missing Commands Section

Claude wastes tokens guessing commands if you don’t define them.

## Commands
- Build: npm run build
- Test (single): npm run test -- --testPathPattern=
- Test (all): npm run test:ci
- Type check: npm run typecheck
- Lint: npm run lint
- Dev: npm run dev

This improves speed, accuracy, and workflow consistency.

---

Failure 5 — Treating It as Memory

# BAD
## Current Sprint
- Working on payments redesign

This context becomes stale and wastes space.

Fix: Move dynamic state to separate docs.

CLAUDE.md = permanent rules only.

---

What a Production CLAUDE.md Looks Like

# Project: Example

## What this is
A SaaS dashboard for analytics.

## Commands
- Build: npm run build
- Test (single): npm run test -- --testPathPattern=
- Type check: npm run typecheck
- Dev: npm run dev

## Tech stack
- TypeScript (strict)
- React 18 (hooks only)
- Tailwind CSS
- React Query

## Code rules
- Use ES modules only
- Always handle errors explicitly
- Never use console.log; use logger utility
- No implicit any

## Architecture
- Components in src/components/
- API calls via src/queries/
- Utilities in src/utils/

## Known pitfalls
- Avoid default exports
- Always run typecheck after edits

Notice:

• No sprint context
• No file embedding
• No unnecessary rules

---

The 5-Minute Diagnostic

Test 1 — Persistence Test

Add: “Always address me as Chief.”

If it disappears mid-session → your file is too long.

---

Test 2 — Recall Test

Ask: “What are the error handling rules?”

If Claude can’t answer → rules are unclear or buried.

---

Test 3 — Repetition Test

If Claude repeats mistakes:

• Rule is unclear
• Rule lacks alternative
• Rule should be a hook instead

---

Hooks vs Rules

CLAUDE.md rules are advisory (~80% compliance).

Hooks are deterministic (100%).

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npm run lint:fix -- ${file}"
}
]
}
]
}
}

If something must always happen — use a hook.

---

The Context Budget Rule

Keep CLAUDE.md under 60 lines.

Long sessions reduce attention on earlier instructions.

Your rules compete with conversation history.

Structure your system:

• CLAUDE.md → core rules
• Skills → domain knowledge (on-demand)
• Hooks → mandatory actions

---

The Bottom Line

Your CLAUDE.md isn’t broken because Claude is unreliable.

It’s broken because:

• It exceeds instruction budget
• Rules are unclear
• Context is overloaded

Fix the structure — and Claude becomes predictable.

---

Build It Hands-On

Learn how to structure CLAUDE.md, hooks, and agent workflows in production.

Start the Claude Architect track →

---

What’s the one rule Claude keeps ignoring for you?