Ask Claude to Review and Improve Your CLAUDE.md for Gaps and Contradictions
A stale CLAUDE.md is worse than no CLAUDE.md — it teaches Claude the wrong patterns. Every few weeks, ask Claude to audit your project instructions against the actual code and flag what's out of date.
Read CLAUDE.md and compare every rule against the current codebase.
Flag any rules that contradict what the code actually does,
commands that no longer exist, and important patterns that aren't documented.
Claude checks each instruction against reality. If CLAUDE.md says "use Jest for testing" but your project now uses Vitest, that's a contradiction it catches. If you have a complex deployment script that's not documented, that's a gap it surfaces.
Common issues Claude finds:
# Outdated commands
CLAUDE.md says "npm run test" but package.json uses "pnpm test:unit"
# Missing conventions
The codebase uses a consistent error handling pattern in every controller
but CLAUDE.md doesn't document it — Claude might not follow it consistently
# Contradictory rules
CLAUDE.md says "use camelCase" in one section and a linter config
enforces snake_case — the conflict confuses Claude
# Stale architecture notes
CLAUDE.md describes a service layer that was refactored into repositories
two months ago
For a thorough review:
Audit CLAUDE.md against the codebase and suggest improvements:
1. Remove rules that contradict the current code
2. Add missing conventions you can infer from the codebase
3. Update any commands or file paths that have changed
4. Flag any rules that are too vague to be useful
Show me the proposed changes before applying them.
You can also ask Claude to generate a fresh CLAUDE.md section from scratch:
Look at how error handling is done across all controllers and services.
Write a "Error Handling" section for CLAUDE.md that documents the
actual pattern so future sessions follow it consistently.
CLAUDE.md is most valuable when it matches reality — review it regularly so Claude learns from what your code actually does, not what it used to do.
via Claude Code
Log in to leave a comment.
When Claude writes error messages, button labels, validation text, or onboarding flows, it defaults to generic developer-speak. Add a "Users" section to your CLAUDE.md describing who your actual users are — their technical level, industry jargon, and what they care about — so Claude writes copy that makes sense to THEM, not to developers.
Use the --agent flag with custom markdown files in .claude/agents/ to launch purpose-built Claude sessions with restricted tools and scoped system prompts.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.