Clean Up Your Vibe-Coded Codebase Without Breaking It
This is why your vibe-coded codebase keeps struggling once you add more and more features. You don't have a proper file structure Claude Code can enforce.
You vibe coded something real. It works. People use it. And now you open the repository and there’s a 2,000 line file called app.tsx doing everything, a utils file that’s actually the whole backend, and a folder structure that is just... not one.
It runs, so it’s tempting to leave it alone. Here’s why the mess is costing you something even while everything works.
Why A Messy Repo Costs You More Than It Looks
Your Agent Has to Read the File to Change It. When everything lives in one 2,000 line file, every edit means the agent loads all 2,000 lines into context to touch ten of them. That burns tokens, and worse, it makes the agent worse at the work. It’s holding a pile of unrelated code in its head while trying to make one small change. Break that file into focused pieces and the agent only pulls in the part that’s relevant. The edits get sharper and you stop paying for context you don’t need.
You Have to Find Things Later. Six months from now, or the day you bring in another person, “where’s the code that handles checkout” should be a five second answer. In a flat mess it’s a scroll and a prayer. Structure is you being kind to the version of you that has to find this later.
Duplicated Logic is a Quiet Tax. Vibe coding loves to paste the same function into four places. The day you need to change it, you change it four times, and you’ll miss one. Pull shared logic into a single home and the fix happens once. That’s the whole point of DRY, don’t repeat yourself.
It’s What Lets You Keep Building. Small, focused modules snap together. Adding a feature becomes writing a new module and wiring it in. When every change means surgery on a file that already does ten jobs, you slow down fast. Clean structure is what keeps feature number eleven as cheap as feature number two.
Why “Just Reorganize This” Goes Wrong
So you do the obvious thing. You tell the AI: “reorganize this whole codebase, clean up the structure, break up the big files.” That is the exact move that breaks your app.
When you ask an AI to organize and improve at the same time, it does both. While it’s moving a function into a new file, it also “fixes” the function. It renames a variable for clarity. It tightens a loop. It deletes a block it decided was dead. Each one feels like a small upgrade. Together they change what your app does.
On a normal codebase you’d catch this because there are tests. On a vibe-coded codebase there usually aren’t any. So nothing fails loudly. The app just behaves slightly differently in some flow you didn’t think to click, and you find out a week later when a user emails you. Yikes!
There’s a sneakier failure too. The AI starts pulling pieces out of the big file and into new locations, but it does it halfway. Some imports point to the new location. Some still point to the old one. Now you have a half-migrated repo that’s worse than where you started, and untangling it by hand is its own afternoon. Another YIKES!
A better one-shot prompt won’t save you here. The move is to stop treating this as one task with Claude.
Cleanup Is A Refactor
Reorganizing your code is a refactoring job. The whole definition of a refactor is that behaviour stays identical. Same inputs, same outputs, same screens, same bugs even. You are only changing where the code lives and how it’s split up. Nothing about what it does.
That one rule is the entire spine of this. Every phase below exists to protect it. Once you internalize “the app must behave exactly the same when I’m done,” the workflow writes itself.
The order is the real trick. Most people jump straight to reorganizing. The first move is making the app verifiable, so you can actually prove you didn’t break anything.
Before you start, paste this at the top of your Claude Code session. It sets the rules that hold for every phase that follows.
We're cleaning up the structure of this codebase. The goal is organization only.
Behavior must stay identical.
Hard rules for this whole session:
- Do not change any logic, behavior, or output. This is a move-and-rename job,
not an improvement job.
- If you spot a bug, dead code, or something worth improving, write it to NOTES.md
and keep going. Do not fix it inline.
- Work one phase at a time. Stop and wait for me to confirm before the next phase.
- Commit after every phase with a clear message so I can revert a single step.
- When you move code, the moved code stays identical. Only update the imports and
paths that point to it.
Phase 0: Build The Safety Net First
Do this before you touch a single file.
Get to a clean git state. Commit or stash whatever’s in progress so your working tree is empty. Now every step you take is one git revert away from safety. This sounds basic but it’s the thing that saves you.
Confirm the app actually runs right now. Start it. Click the three or four flows that matter most. This is your “known good” baseline. If you don’t know it works before you start, you’ll never know what the AI refactor broke.
If you want the strong version, have the AI write a few smoke tests for those critical paths before any reorganizing happens. Not full coverage. Just enough to prove the login works and the data still saves. Most people skip this step. It’s the single highest leverage thing in the whole process, because it turns “I think it still works” into “the tests say it still works.”
Before we reorganize anything, write a few simple smoke tests for the critical
paths: [list your key flows, e.g. login, create order, save settings]. They only
need to prove these flows still work end to end. Do not refactor or change any
app code to do it.Phase 1: Map Before You Move
This is where Claude Code’s plan mode does real work. Plan mode is a read-only permission mode. You toggle into it with Shift+Tab, and the footer at the bottom of the terminal tells you you’re in it. While it’s on, Claude can read every file, search the codebase, trace what imports what, and write you a plan, but it physically cannot edit files or run commands that change state until you approve. The thinking and the doing are separated by a wall.
