claude-code

Why Your CLAUDE.md Isn't Working (And How to Fix It in 10 Minutes)

Your CLAUDE.md file is supposed to make Claude remember your preferences, follow your conventions, and stop asking the same questions every session.

Anna

— 3 min read

The 5 most common mistakes that break Claude Code's memory system

Your CLAUDE.md file is supposed to make Claude remember your preferences, follow your conventions, and stop asking the same questions every session.

But it doesn't work.

Claude keeps asking permission for things you've already approved. It forgets your coding standards. It ignores your project context.

I've debugged hundreds of CLAUDE.md files. Here are the 5 mistakes that break them—and the fixes that work.

Mistake #1: Your CLAUDE.md is Too Long

The symptom: Claude "forgets" instructions partway through a session.

The problem: Token pressure. Claude has limited context. A 5,000-word CLAUDE.md file eats into your working memory. By mid-session, early instructions get compressed or dropped.

The fix: Keep CLAUDE.md under 500 words. Strip it down to:

  • 3-5 critical rules (what Claude should ALWAYS do)
  • 3-5 critical anti-patterns (what Claude should NEVER do)
  • One-liners for your stack preferences

Bad:

# Project Overview
This is a comprehensive e-commerce platform built with React 
and Node.js. The project was started in 2024 and has evolved
through multiple phases of development. Initially we used...
[2000 more words of backstory]

Good:

# Project Rules
- TypeScript strict mode, no `any`
- Tests before implementation
- Commits: conventional commits format
- Never push to main directly

Mistake #2: Instructions Without Consequences

The symptom: Claude acknowledges your rules but breaks them anyway.

The problem: LLMs optimize for helpfulness. Vague instructions get overridden by "being helpful." You need to make consequences explicit.

The fix: Add "why it matters" or "what happens if violated."

Bad:

Use TypeScript for all new files.

Good:

Use TypeScript for all new files. JavaScript files will fail CI.

Even better:

Use TypeScript strict mode. Violations:
- Block PR merge
- Trigger automated review request
- Add 30min to your estimate

The consequence doesn't have to be real—Claude doesn't verify. But explicit stakes trigger stronger compliance.

Mistake #3: No Explicit Autonomy Levels

The symptom: Claude either asks permission for everything (annoying) or does dangerous things without asking (scary).

The problem: Claude doesn't know which actions need human approval. Default behavior varies by task complexity.

The fix: Define explicit autonomy levels.

## Autonomy Levels

### Auto-approve (just do it)
- Create files, edit existing code
- Run tests, linting, formatting
- Git add, commit with message

### Ask first
- Git push, PR creation
- Install new dependencies
- Delete files
- Modify config files (package.json, tsconfig, etc.)

### Never do
- Access production systems
- Modify CI/CD configs
- Delete git history

Now Claude knows the rules. No guessing.

Mistake #4: Missing State Files

The symptom: Every session starts from scratch. No memory of yesterday.

The problem: CLAUDE.md is static. It doesn't change between sessions. Claude can't write to it (safely). So previous decisions vanish.

The fix: Add writable state files.

## State Files

- `TASKS.md` — Current sprint tasks. Claude updates after completion.
- `DECISIONS.md` — Architecture decisions. Claude adds entries.
- `ERRORS.md` — Bugs encountered. Claude logs with root cause.

Now Claude writes to these files. Next session, it reads them. Memory persists.

The key insight: CLAUDE.md is read-only rules. State files are read-write memory.

Mistake #5: One File for Everything

The symptom: Claude applies frontend rules to backend code, or vice versa.

The problem: A single CLAUDE.md at project root applies everywhere. But your monorepo has different rules for different packages.

The fix: Scoped CLAUDE.md files.

/project
├── CLAUDE.md              # Global rules
├── frontend/
│   └── CLAUDE.md          # React conventions
├── backend/
│   └── CLAUDE.md          # Node/API conventions
└── scripts/
    └── CLAUDE.md          # Tooling conventions

Claude reads the nearest CLAUDE.md + parent chain. Child files override parent rules.

Example:

# /frontend/CLAUDE.md
Extends global rules. Additional:
- Use React hooks only (no class components)
- Tailwind for styling (no CSS modules)
- shadcn/ui for components

The 10-Minute Fix

Here's the minimal CLAUDE.md that actually works:

# Project: [name]

## Stack
- [language], [framework], [database]
- [key tools]

## Rules (always)
- [Rule 1 with consequence]
- [Rule 2 with consequence]
- [Rule 3 with consequence]

## Never
- [Anti-pattern 1]
- [Anti-pattern 2]

## Autonomy
- Auto: create/edit code, run tests, git commit
- Ask: push, install deps, delete files
- Never: production access

## State Files
- TASKS.md — current work
- DECISIONS.md — architecture choices

That's it. Under 200 words. No backstory. No philosophy.

Going Further

I run an AI agent 24/7 with a full memory system:

  • AGENTS.md for operational rules
  • MEMORY.md for long-term context
  • Daily files for session logs
  • Heartbeat polling for proactive work

[Full guide here →](https://ai-insider.io/ultimate-agents-md-guide/)

What's the weirdest CLAUDE.md bug you've hit? Reply and I'll diagnose it.

Read more