Common CLAUDE.md Mistakes & Anti-Patterns

Most CLAUDE.md problems fall into a small number of recurring patterns. Recognizing them is the fastest way to audit an existing file — or avoid writing a weak one in the first place.

Bloat: Documenting Everything Instead of What Matters

The single most common failure mode. A file that tries to be comprehensive ends up diluting its genuinely high-value content (real gotchas, precise commands) among a much larger volume of generic or inferable filler.

<!-- Bloated -->
We believe in writing high-quality, maintainable code. Our team values
collaboration, clear communication, and continuous improvement. Please write
tests for new features and ensure your code is well-documented. We use modern
JavaScript practices and follow industry-standard conventions...

<!-- Fixed: delete it entirely, or replace with something actually specific -->
(nothing — this paragraph contained zero actionable, project-specific information)

The fix is aggressive editing, not more organization — see What to Include in CLAUDE.md for a concrete filter to apply to every line.

Staleness: Documenting How Things Used to Work

A CLAUDE.md that isn’t updated alongside the code it describes doesn’t just become useless — it becomes actively misleading, which is worse than having no documentation at all.

<!-- Written 8 months ago, never updated -->
We use Moment.js for date handling throughout the codebase.

<!-- Reality: the codebase migrated to date-fns 6 months ago -->

An agent trusting the stale instruction will reach for a dependency that’s no longer part of the project’s conventions, and may not even still be installed. Treat CLAUDE.md with the same update discipline as a README — a PR that changes a documented convention should update the file in the same commit.

Genericness: Advice True of Any Codebase

<!-- Generic -->
- Write clean, readable code
- Follow SOLID principles
- Handle errors gracefully

<!-- Specific to this project -->
- Handlers in `api/routes/` must call `validateRequest()` before touching
  `req.body` — several past incidents traced back to unvalidated payloads
  reaching business logic

If a piece of advice would be equally true pasted into any other project’s CLAUDE.md unchanged, it’s not adding project-specific value and is a candidate for deletion.

Contradiction: Conflicting Instructions Across Files or Sections

<!-- Root CLAUDE.md -->
Use single quotes for strings.

Use double quotes for strings in this package.

Remember that subdirectory files layer additively on top of the root file rather than overriding it (see How Claude Code Discovers & Loads CLAUDE.md Files) — a genuine exception for one subtree needs to be phrased as an explicit override (“unlike the rest of the codebase, this package uses double quotes because it matches an external API contract”), not left as a silent, unexplained contradiction.

Treating It as Set-and-Forget

<!-- Written once at project kickoff, never touched again -->

The most useful CLAUDE.md files are living documents, refined based on real friction observed in actual sessions — a misunderstanding the agent had, an assumption it made incorrectly, a command it had to rediscover. Each of these is a concrete signal for what to add or clarify, and a file that never incorporates that feedback stops improving.

Over-Restricting With Blanket Prohibitions

<!-- Overly broad -->
Never modify any file in the `utils/` directory.

<!-- Better: specific and reasoned -->
`utils/legacy-parser.ts` is deprecated and scheduled for removal — avoid
extending it. Other files in `utils/` are actively maintained and fine to
modify normally.

A blanket prohibition covering an entire directory, when only one file within it is actually sensitive, blocks legitimate work unnecessarily and eventually gets ignored or worked around — a narrowly-scoped, reasoned restriction is both more accurate and more likely to be respected.

Common Mistakes (Meta)

Writing this exact article’s advice into your CLAUDE.md as a generic reminder (“avoid bloat, avoid staleness”) — that’s itself an instance of the genericness anti-pattern; the useful output of reading this isn’t a paragraph to paste in, it’s a habit of auditing your specific file’s actual content against these patterns.

Fixing one instance of an anti-pattern and assuming the whole file is clean. These patterns tend to recur — a file bloated in one section is often bloated throughout; a full read-through audit catches more than fixing the first example you notice.

Auditing CLAUDE.md once and considering it done. Bloat and staleness both accumulate gradually as a project evolves — periodic re-review (quarterly, or whenever it starts feeling long) catches drift before it compounds.

Frequently Asked Questions

How do I know if my CLAUDE.md has become bloated? A rough signal: if you can’t summarize what’s in it from memory, or if adding a new section feels easier than finding out whether it’s already covered somewhere in the existing file, it’s likely grown past the point of being genuinely scannable.

Should stale sections be deleted or updated? Update if the underlying fact is still relevant but changed (e.g., the tooling migrated); delete if the fact is no longer relevant at all — either way, don’t leave it as-is once you know it’s wrong.

Is there a way to systematically review CLAUDE.md for these issues? Asking Claude Code itself to review the file against a checklist like this one is a reasonable periodic exercise — treating the file’s own maintenance as a task worth doing deliberately, not just something that happens incidentally.

Summary

Bloat, staleness, genericness, unexplained contradiction, neglect, and over-broad restrictions are the recurring failure modes behind most weak CLAUDE.md files — and all six are fixable with the same underlying discipline: keep it specific to this project, keep it current, and keep editing it as real friction surfaces rather than treating it as a document written once and never revisited.