DEV Community

Cover image for Your CLAUDE.md is probably broken — 5 silent failure patterns and how to fix them
Aj
Aj

Posted on • Originally published at cloudedventures.com

Your CLAUDE.md is probably broken — 5 silent failure patterns and how to fix them

#claude #ai #productivity #devtools

CLAUDE.md is the most important file in your Claude Code setup. It's also the easiest to get silently wrong.

Here's the uncomfortable truth: Claude actively filters what it follows from your CLAUDE.md — it doesn't treat everything as a permanent command. Most production CLAUDE.md files are broken and developers don't know it.

TL;DR

  • Claude has an instruction budget of ~100–150 slots after its own system prompt
  • Files over 60 lines cause Claude to silently ignore rules mid-session
  • "Never do X" rules without alternatives cause Claude to freeze and ask permission
  • @file embeds burn context on every session — reference instead
  • CLAUDE.md is advisory (80% compliance) — hooks are deterministic (100%)

The budget problem nobody talks about

Claude Code injects a system reminder above your instructions: "This context may or may not be relevant to your tasks." Claude actively decides which rules to follow per turn.

Frontier models follow roughly 150–200 instructions before compliance drops. Claude Code's own system prompt uses ~50 of those slots. That leaves you about 100–150 slots.

If your CLAUDE.md has 60+ rules, Claude is silently ignoring some. You just don't know which ones.

Failure 1 — The kitchen sink file 

# TOO LONG — Claude starts ignoring rules mid-session
- Use TypeScript strict mode
- Prefer functional components  
- Use arrow functions
- Destructure props
- Use const over let
- Avoid any type
- Use interface over type
- Always handle errors
- Use async/await not .then()
- Add JSDoc to public functions
... (30 more rules)
Enter fullscreen mode Exit fullscreen mode

When context fills, Claude weights early rules heavily and discards later ones. The rules you care most about are usually at the bottom.

Fix: Keep it under 60 lines. For each rule ask: "Would removing this cause Claude to make a mistake?" If not, cut it.

Failure 2 — Prohibitions without alternatives 

# BAD — Claude freezes every time
- Never use console.log
- Never use var
- Never commit to main
Enter fullscreen mode Exit fullscreen mode 
# GOOD — Claude has a path forward
- Never use console.log; use src/utils/logger.ts
- Never use var; use const, or let for reassigned variables
- Never commit to main; create feature/description branch
Enter fullscreen mode Exit fullscreen mode

Every "never" needs an "instead, do this." Without it, Claude pauses and asks permission every time it hits the rule, breaking flow.

Failure 3 — @file embeds killing your context 

# BAD — embeds entire files on every session start
@src/utils/api-client.ts
@docs/architecture.md
@docs/design-system.md
Enter fullscreen mode Exit fullscreen mode 
# GOOD — reference, don't embed
- For API patterns, see src/utils/api-client.ts
- For architecture decisions, see docs/architecture.md
- For design system, see docs/design-system.md
Enter fullscreen mode Exit fullscreen mode

@file embeds the full file content into every conversation. A 500-line architecture doc loaded every session burns context before you've typed a word.

Failure 4 — Missing bash commands

The most commonly skipped section. The most valuable one.

## Commands
- Build: npm run build
- Test (single file): npm run test -- --testPathPattern=
- Type check: npm run typecheck
- Lint + fix: npm run lint:fix
- Dev: npm run dev
Enter fullscreen mode Exit fullscreen mode

Three things matter here: the single-test command (Claude should never run your full suite for one file), typecheck (Claude should run this after every change), and your deployment scripts (Claude cannot guess them).

Failure 5 — Sprint context in a permanent file 

# BAD — this gets forgotten when context rotates
## Current Sprint
- Working on payment flow redesign
- UserCard component is being deprecated
- Don't touch legacy auth module this sprint
Enter fullscreen mode Exit fullscreen mode

CLAUDE.md loads every session. Sprint context belongs in dev-docs/current-sprint.md, loaded explicitly when needed.

CLAUDE.md is for permanent project truth. Current state goes in session-specific files.

What a production CLAUDE.md actually looks like 

# Project: [Name]
[One sentence. What it does.]

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

## Stack
- TypeScript strict mode
- React 18 hooks only — no class components
- Tailwind — no custom CSS unless unavoidable
- Zustand for state — see src/stores/

## Rules
- ES modules only — never require()
- Always handle errors explicitly — no silent catches
- Never use console.log; use src/utils/logger.ts instead
- No implicit any, no type assertions without explanatory comment

## Architecture
- API calls only through src/queries/ — never direct fetch in components
- Shared utilities in src/utils/
- Colocate tests with components

## What Claude gets wrong here
- Adds index.ts barrel exports — don't, breaks tree shaking
- Forgets typecheck after changes — always run npm run typecheck
- Uses default exports — always use named exports
Enter fullscreen mode Exit fullscreen mode

Notice: no sprint info, no @file embeds, no prohibitions without alternatives, no style rules that don't affect correctness.

The 5-minute diagnostic

The Tinkleberry test
Add one line: Always address me as "Chief." Have a 10+ message session on a real task. If Claude stops using "Chief" mid-session, your file is too long and rules are being lost.

The direct question test
Ask Claude: "What are the rules in CLAUDE.md about error handling?" If Claude can't recite them accurately, they're too buried, too ambiguous, or too many.

The repeated mistake test
If Claude makes the same mistake twice despite a rule against it, that rule needs one of:

  • Shorter and clearer wording
  • An "instead, do this" alternative
  • To be a hook instead of a rule

CLAUDE.md vs hooks — the most important distinction

CLAUDE.md is advisory — Claude follows it ~80% of the time.
Hooks are deterministic — 100% every time.

// .claude/settings.json — things that MUST happen
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint:fix"
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

If something must happen without exception — formatting, linting, security checks — make it a hook. CLAUDE.md is for guidance. Hooks are for guarantees.

The three-layer system 

CLAUDE.md  → permanent project rules    (always loads, max 60 lines)
Skills     → domain knowledge           (loads on demand, no session cost)
Hooks      → non-negotiable actions     (deterministic, not advisory)
Enter fullscreen mode Exit fullscreen mode

Most developers only use CLAUDE.md. The developers getting the best results from Claude Code use all three.

For hands-on labs building production CLAUDE.md hierarchies, slash command registries, and CI/CD integration with Claude Code — Cloud Edventures CCA-001 track, 22 labs, real AWS sandboxes.

Search: Cloud Edventures CCA-001

What does Claude keep ignoring in your CLAUDE.md? Drop a comment — I'll diagnose which failure pattern it is.

Top comments (0)