Seven CLAUDE.md Mistakes That Quietly Degrade Claude Code Output

That doubt is exactly where bad configurations live. No errors, no warnings, just vaguely generic and slightly wrong code, session after session. A fuzzy or bloated file doesn't merely fail to help. It eats tokens and crowds out the actual task. So before you change a single line, get an honest read on what's in there, then fix the problems below one at a time.

Mistake 1: a vague stack description

A line like We use React and a database. tells Claude next to nothing. It'll guess at the Next.js router, grab a state library more or less at random, and write tests in a framework you don't use. The result compiles and still doesn't fit your codebase.

Spell it out instead:

Framework: Next.js 15, app router only
State: TanStack Query v5 for server state, Zustand for client state
Testing: Vitest + React Testing Library
Package manager: pnpm

Exact versions and conventions are what turn generic output into code that looks like it belongs in your repo. Name them.

Mistake 2: no constraints, no "never do this"

This is the most common silent failure. People describe the project and never draw a hard line. Without limits, Claude runs npm in a pnpm project, edits generated files, and refactors code you never mentioned. Those aren't hallucinations. They're sensible guesses made because no rule said otherwise.

Add a constraints block:

Constraints:
- Never install new dependencies without asking first
- Never edit files under /generated or /prisma/migrations
- Always use pnpm, never npm or yarn
- Do not refactor code outside the scope of the current task

Rules about what not to do give you more than descriptions do, because they stop expensive mistakes before they happen.

Mistake 3: ignoring agents and subagents

Most CLAUDE.md files are written as if one model works alone, with no guidance for specialist subagents running next to the main session. If you use subagents for testing, docs or deployment, say so in the file: list every agent, the area each is responsible for, and the situations where the main agent should pass work along.

Agents & delegation:
- test-agent: runs Vitest, owns /tests — do not write tests in the main session
- docs-agent: handles JSDoc and README updates only
- main agent: feature code, routing, API handlers

If you're still designing the delegation model, it helps to understand how skills, subagents, slash commands and MCP differ before you settle on a layout.

Mistake 4: a bloated file that eats your context budget

More isn't better. A 2,000-line CLAUDE.md stuffed with full style guides, API docs and changelogs loads all of it into every session, relevant or not. That squeezes out the real task, and since attention gets worse with noisy context, you end up with a model that technically read your rules and still doesn't apply them reliably.

Trim to the essentials. Point at files or skills for the details rather than pasting them in. A rule that concerns one package belongs in a scoped file, not in the root. Count the file's tokens before and after trimming so you know the cut did something.

Mistake 5: instructions Claude can't act on

Take Write clean, maintainable, high-quality code. Claude already believes it's doing that, so fuzzy adjectives steer nothing. Replace them with rules you could check:

- Functions must be under 40 lines
- No default exports
- Colocate test files next to source files
- No inline styles — use CSS modules

Operational rules give the model a measurable target. Aspirational phrases give it none.

Mistake 6: stale rules that contradict the code

CLAUDE.md rot is real. Say the file still says "use Redux" six months after the team moved to Zustand. That rule doesn't sit there harmlessly. It sets your config against your actual code, and Claude flips between trusting one and the other.

Review the file whenever dependencies change significantly, and make that review a line on your PR checklist. Keep it in Git so you can see when each rule last changed. A stale CLAUDE.md is often worse than none at all.

Mistake 7: one giant flat file

In a monorepo, a single unstructured CLAUDE.md leads Claude to apply frontend rules to backend code and the reverse. When everything is one undifferentiated block, there's no way to scope context.

Put global rules in a root CLAUDE.md and add scoped files per package or service. Inside the root file, use clear section headers:

# Project Overview
# Stack & Versions
# Constraints
# Agents & Delegation
# Per-Package Notes

Structure tells Claude which rules apply where.

A quick audit and a checklist

Stop guessing and score the file against four things: specificity, constraints, structure and size. Comparing against a well-formed template also helps, since it shows what a good file looks like in practice.

Run through these questions:

• Does it name exact framework versions and libraries?
• Is there a constraints block with hard "never do this" rules?
• Does it list which agents exist and what each owns?
• Is it under 200 lines, with detail pushed out to skills or linked files?
• Are all instructions operational rather than aspirational?
• Has anyone reviewed it for stale rules in the last 30 days?
• Is it split by headers, or by scoped per-package files if you run a monorepo?

Answer no to more than two of those and your CLAUDE.md is probably costing you more than it saves.