TL;DR
A messy codebase does not get cleaned in one giant pass - that is how you break things. You map it first so Claude understands what it is touching, then clean in small reviewable passes: dead code, then naming and structure, then duplication. These are the copy-paste prompts for each step, plus the one rule that keeps a cleanup from becoming a disaster.
Why one big cleanup pass fails
The tempting move is 'clean up this whole codebase.' Do not. A single sweeping pass changes too much at once, you cannot review it, and one silent break hides among a thousand edits. Cleanups work when they are small, staged, and reviewable - each pass does one kind of thing so you can actually check it before the next.
Step 1: Map it before you touch it
Claude cleans safely only when it understands the structure. Start every cleanup with a map so it knows what depends on what.
markdownMap this codebase before we change anything. Give me:
1. The top-level structure and what each folder is for.
2. The main entry points and how data flows through them.
3. The riskiest files (most depended-on) - do not touch
these without asking.
Do not edit anything yet. Just build the map.Step 2: Clean in small, single-purpose passes
Run these one at a time, reviewing the diff after each. Do not stack them into one prompt.
- 1Dead code: 'Find code that is never imported or called - unused files, functions, and variables. List them with evidence before removing anything.'
- 2Naming and structure: 'Rename unclear variables and functions to say what they do, and move misplaced files to where they belong. Small diffs only, one area at a time.'
- 3Duplication: 'Find blocks of near-identical code. For each, show me the duplicates and propose one shared version. Do not extract until I approve - three similar lines can beat a premature abstraction.'
Step 3: Lock it in so it stays clean
A clean codebase drifts back to messy without rules. Add the conventions you just enforced to your CLAUDE.md so every future session keeps them.
Common questions
Can I just tell Claude to clean the whole thing at once?
You can, but you should not. A single massive pass is unreviewable and hides breakage. Map first, then clean in small single-purpose passes you can read in one diff.
How do I stop it from breaking things?
Two habits: have Claude map the codebase and flag the most depended-on files before touching them, and run the build and tests after every pass. Small reviewable diffs plus a green check between passes is what keeps a cleanup safe.
Should I let it remove all duplicate code?
Not automatically. Some duplication is fine - three similar lines can be clearer than a forced abstraction. Have Claude show you the duplicates and propose the shared version, then you decide which are worth extracting.
How do I keep it clean afterward?
Write the conventions you enforced into your CLAUDE.md so every future session follows them. See our Ultimate CLAUDE.md File guide.
Want the file that keeps your codebase clean automatically?
Get the other 17 in the starter stack, plus 5,000+ builders - $9/mo, cancel anytime.
Join the Club