CLAUDE.md Anti-Patterns — Mistakes That Make Your AI Assistant Worse
A catalog of the most common CLAUDE.md mistakes: files that are too long, too vague, contradictory, outdated, or that duplicate code. Each anti-pattern includes a bad example, why it fails, and how to fix it.
Quick Reference
- →Anti-pattern: The Novel — CLAUDE.md files over 1000 lines that waste context on every message
- →Anti-pattern: The Fortune Cookie — vague platitudes like 'write clean code' that provide no actionable guidance
- →Anti-pattern: The Contradiction — conflicting instructions that confuse Claude into inconsistent behavior
- →Anti-pattern: The Time Capsule — outdated instructions that reference deprecated tools or old patterns
- →Anti-pattern: The Parrot — duplicating what your linter, formatter, or tsconfig already enforces
- →Anti-pattern: The Wishful Thinker — instructions for ideal practices nobody actually follows
In this article
- 1.Why CLAUDE.md Anti-Patterns Matter
- 2.Anti-Pattern 1: The Novel
- 3.Anti-Pattern 2: The Fortune Cookie
- 4.Anti-Pattern 3: The Contradiction
- 5.Anti-Pattern 4: The Time Capsule
- 6.Anti-Pattern 5: The Parrot
- 7.Anti-Pattern 6: The Wishful Thinker
- 8.Anti-Pattern Detection Checklist
- 9.Before and After Summary
- ★Best Practices
- ✓Key Takeaways
Why CLAUDE.md Anti-Patterns Matter
A bad CLAUDE.md is worse than no CLAUDE.md at all. Without one, Claude Code uses sensible defaults and follows code patterns it finds in your repo. With a bad one, Claude Code follows your broken instructions faithfully — producing worse output than it would have on its own.
Claude Code trusts your CLAUDE.md completely. It will not push back on contradictory instructions or question outdated advice. It will simply do what you told it to do, even when that makes the output worse.
The following anti-patterns are drawn from real CLAUDE.md files I have encountered. Each one seemed reasonable to the person who wrote it but actively degraded Claude Code's output quality.
Anti-Pattern 1: The Novel
A CLAUDE.md file that has grown to hundreds or thousands of lines, covering every possible scenario. It wastes context tokens on every single message and buries important instructions in noise.
The fix: keep CLAUDE.md under 200-300 lines. Move domain-specific sections into .claude/rules/ files with appropriate glob patterns. Move rarely-referenced documentation behind @import directives. Only the universally relevant core should live in the main CLAUDE.md file.
Anti-Pattern 3: The Contradiction
CLAUDE.md files that contain conflicting instructions, often written by different team members at different times. Claude will follow whichever instruction it encounters last — or worse, try to satisfy both, producing confused output.
The fix: treat CLAUDE.md as a single-source-of-truth document with one owner or a clear review process. When adding new rules, check for conflicts with existing ones. When conventions change, update or remove the old rules — do not just add new ones.
Anti-Pattern 4: The Time Capsule
A CLAUDE.md written once and never updated. It references deprecated libraries, old directory structures, or practices the team abandoned months ago. Claude follows these stale instructions faithfully, producing code that does not match the current codebase.
The fix: update CLAUDE.md in the same PR that makes the change. If you migrate from Jest to Vitest, update CLAUDE.md in the migration PR. Set a calendar reminder to audit CLAUDE.md quarterly. Add a last-reviewed date at the top of the file.
Anti-Pattern 5: The Parrot
A CLAUDE.md that repeats rules already enforced by your tooling — ESLint, Prettier, TypeScript strict mode, or your CI pipeline. These duplicate instructions waste context tokens and can go out of sync with the actual config.
The fix: only include rules in CLAUDE.md that are NOT enforced by tooling. Claude Code already reads your project's config files. It knows about your Prettier settings. Focus CLAUDE.md on the things tools cannot enforce: architectural decisions, naming conventions for domain concepts, workflow patterns, and project-specific constraints.
Anti-Pattern 6: The Wishful Thinker
A CLAUDE.md that describes practices the team aspires to but does not actually follow. Claude will generate code following these aspirational rules, creating inconsistencies with the existing codebase.
The fix: CLAUDE.md should describe how the project actually works today, not how you wish it worked. If you are migrating toward a pattern, note both the current state and the target state explicitly.
Anti-Pattern Detection Checklist
Run through this checklist quarterly to catch anti-patterns before they degrade your AI assistant's output.
- ▸Line count check: is CLAUDE.md over 300 lines? If yes, extract to .claude/rules/ and @import
- ▸Specificity check: for each rule, can you give a concrete example of code that violates it? If not, the rule is too vague
- ▸Contradiction check: read every rule and check if any two rules give opposite advice for the same situation
- ▸Freshness check: does every technology and library mentioned still match what the project actually uses?
- ▸Duplication check: does CLAUDE.md repeat rules that your linter, formatter, or tsconfig already enforce?
- ▸Reality check: does CLAUDE.md describe how the project actually works, or how you wish it worked?
- ▸Token budget check: use /status to see how much context CLAUDE.md consumes — is it worth it?
Add a recurring calendar event to review CLAUDE.md. The best time is after major dependency upgrades or architectural changes. A 15-minute quarterly review prevents months of degraded AI output.
Before and After Summary
| Anti-Pattern | Symptom | Fix |
|---|---|---|
| The Novel | CLAUDE.md > 300 lines, slow responses | Split into .claude/rules/ and @import |
| The Fortune Cookie | Vague rules, generic output | Replace with specific, testable rules |
| The Contradiction | Inconsistent Claude behavior | Single owner, review process, remove conflicts |
| The Time Capsule | Code references deprecated tools | Update CLAUDE.md in the same PR as changes |
| The Parrot | Duplicates linter/formatter rules | Only include rules tooling cannot enforce |
| The Wishful Thinker | Code inconsistent with existing codebase | Describe current reality, note migration areas explicitly |
Best Practices
Do
- ✓Keep CLAUDE.md under 300 lines — extract domain rules into .claude/rules/
- ✓Write specific, testable rules with concrete examples
- ✓Update CLAUDE.md in the same PR that changes conventions
- ✓Schedule quarterly CLAUDE.md reviews to catch staleness
- ✓Describe how the project actually works today, not aspirational goals
- ✓Use a review process for CLAUDE.md changes just like code changes
Don’t
- ✗Don't write vague instructions like 'write clean code' — Claude already does that
- ✗Don't let CLAUDE.md accumulate conflicting instructions from different authors
- ✗Don't duplicate rules that your linter, formatter, or tsconfig already enforces
- ✗Don't write once and forget — stale CLAUDE.md is worse than no CLAUDE.md
- ✗Don't describe aspirational practices the team does not actually follow
- ✗Don't ignore the context cost — every line of CLAUDE.md is paid for on every message
Key Takeaways
- ✓A bad CLAUDE.md is worse than no CLAUDE.md — it actively degrades Claude's output
- ✓The most common mistake is length: keep CLAUDE.md lean and extract domain rules into .claude/rules/
- ✓Vague instructions waste tokens — every rule should be specific enough to test against concrete code
- ✓Contradictions and stale instructions are silent quality killers — schedule regular audits
- ✓Do not duplicate what your tooling already enforces — focus on rules above the linter level
- ✓Describe reality, not aspirations — Claude will faithfully follow outdated or aspirational instructions to the detriment of your codebase
Video on this topic
CLAUDE.md Anti-Patterns in 60 Seconds
tiktok