C² Method8 min read
How to rescue a vibe-coded app without rewriting it
Stop adding features, map what's there, give the agent a router and a contextbase, pin the behaviour with tests, then fix it one small brief at a time.
To fix a vibe-coded app without rewriting it, stop adding features, have an agent map what is actually there, and give it a router file and a docs/ contextbase to read before it works. Then pin the behaviour you want to keep with tests, fix one problem at a time from a short written brief, and write down every trap you find. That's the whole playbook. The rest of this article is how to do each step.
I've written separately about the time I vibe-coded a feature into a corner. That piece is the story of getting stuck. This one is the rescue procedure, built from the habits I run every day on my own repos.
Why vibe-coded apps go wrong
Vibe coding is building from a feeling rather than a specification. You talk, the agent builds, you steer by what looks right. For a throwaway prototype that's fine.
It fails quietly when you keep the result. In my referral-feature corner, every change looked reasonable on its own. Six changes in, discount stacking conflicted with an older refund rule and referral credit could exceed the order total. Nothing was obviously broken. That's the pattern: the drift is invisible step to step, and you only see it once you're deep in it.
So a vibe-coded app is really a brownfield codebase that happens to be young. The greenfield vs brownfield problem applies in full. The reasons behind the code were never written down, because there were no reasons, only prompts. The agent can read every line and still not know what the app is supposed to do.
Should you rewrite a vibe-coded app?
Not the whole thing, as a default. A rewrite throws out the behaviour that works along with the mess. And if the rewrite is driven the same way, by an agent steered by feel, you get a cleaner-looking version of the same drift.
There is one case where I do rebuild. When a single feature is small and incoherent, deleting it and rebuilding it from a brief is cheaper than untangling it. That's what climbed me out of the referral corner. I deleted the feature, wrote four acceptance criteria, and the agent built it once, cleanly. The rebuild took less time than the vibe-coded version had taken to debug.
Rebuild a feature from a brief when it's small and incoherent. Rescue the app around it.
Step 1: Stop adding features
The first move is the one nobody wants to make. Freeze new work. Every feature you add on top of an unmapped app adds to what you'll need to understand later.
Then list what's broken before you fix any of it. I run a standing rule in my main repo for exactly this, under the heading "Don't walk past broken things". A small fix, an hour or two, gets proposed and done now. Anything larger gets written down as a brief or a line in a maintenance backlog, so it's captured before it slips out of the conversation. Triage first, then fix.
One more habit from my maintenance runs: before fixing an item, check it is still an issue against the current code. On a codebase that's been changing fast, a good share of the list fixed itself or moved.
Step 2: Map the app before you touch it
Don't ask the agent to fix anything yet. Ask it for a map. The main parts, how they connect, the entry points, where the data goes, which flows touch money or email or sign-in.
Mapping first does two jobs. It gives you a frame for everything that follows. And it shows you the agent's understanding before that understanding gets baked into fifty changes, so you can correct a wrong mental model early. I covered this in more depth in documenting an inherited codebase with an agent: map first, go deep only where you're working, and verify what the agent claims against the code and the running app.
If you use Claude Code, /init gets you a first draft. Per the Claude Code memory docs, it analyses the codebase and writes a starting CLAUDE.md with build commands, test instructions and the conventions it discovers. Treat that as a draft to correct, not a finished map.
Step 3: Write a router and a contextbase
The map is only useful if the agent reads it next session. That's what a router file and a contextbase are for.
The router is one short file at the root, CLAUDE.md for Claude Code or AGENTS.md for most other agents. It holds the overview, the handful of rules that apply every time, and pointers to where detail lives. It routes. It doesn't hold everything.
Keep it short. The Claude Code docs say to target under 200 lines per CLAUDE.md, because longer files consume more context and reduce adherence. I learned that the hard way when my own CLAUDE.md hit 600 lines and the agent started missing rules that were in plain text. My main monorepo's router has since grown back to about 400 lines, and it now says near the top that it is a router, and ends with a "Moved sections" table pointing at five reference files. Nothing was deleted when detail moved out. It just went somewhere the agent reads on demand.
The contextbase is a docs/ folder of plain markdown in git, next to the code. For a rescue, three parts matter most:
| Folder | What goes in it during a rescue |
|---|---|
docs/01-planning/ | What the app is supposed to do, written down for the first time |
docs/02-working/ | The briefs for each fix, and a session brief at the end of every session |
docs/03-knowledge/gotchas/ | Every trap you find, one short file each |
You don't fill this in one go. You create the folders, write the map into the planning folder, and let it grow around the work. The contextbase explainer covers the full shape.
Step 4: Pin the behaviour with tests
This is the step that makes every later fix safe. Before the agent changes anything that matters, write tests that pin what the app does today in the flows you can't afford to break.
The point is behaviour, not structure. When I handed an agent a refactor that pulled booking logic out of a route handler, I first spent about twenty minutes writing tests for what had to survive: bookings refused at capacity, the refund window enforced, the confirmation email sent once. Partway through, the agent moved the capacity check to the wrong side of a conditional and that test went red. It diagnosed and fixed it inside its own loop. The regression lived for about ninety seconds and never left the branch. That's the test that saved the refactor.
Two practical notes for a vibe-coded app:
- If there's no test runner, setting one up is the first fix. Without a way to run tests, the agent has nothing to check itself against, and you're back to hoping. I go into why in test-driven development with AI agents.
- Pin what it does, then decide what it should do. If a test reveals a behaviour that's wrong, that's a finding. Write it down as an issue and fix it in its own brief. Don't quietly change behaviour while you're adding the safety net.
Step 5: Fix one thing per brief
Now you fix. One problem per brief, small enough to finish and verify in a session.
A brief here is short: what this change does, what it explicitly does not do, and acceptance criteria you can run. These are the four from the referral rebuild, unchanged:
- A referral gives the referrer a fixed credit, once, on the referee's first paid order.
- Credit never exceeds the order total.
- Referral credit does NOT stack with promotional discounts.
- Test suite covers all three rules and passes.
Each line is checkable. The agent builds against them, runs the tests, and reports the green run. If you want the longer version, see acceptance criteria your agent can check.
Two rules keep this from sliding back into vibe coding. First, if the agent has been stuck on one bug for 30 minutes, the answer is not another attempt. My main repo states it as "Maximum debug time: 30 minutes per issue". Stop, start a fresh session, restate the problem, or escalate. More on that in the 30-minute debug limit. Second, end every session with a session brief: what changed, why, what's verified, what's next. My main repo's 2026 folder holds more than 1,100 of them, and a SessionStart hook lists the recent ones at the top of every new session. The hooks docs confirm that plain-text output from a SessionStart hook is added as context Claude can see.
Step 6: Write down every trap you find
A rescue turns up traps: the odd-looking line that turns out to be load-bearing, the setting that only works one way, the bug that took an hour to understand. Each one gets a gotcha file in docs/03-knowledge/gotchas/. What it looked like, why it happened, what to do instead. My main repo has 217 of them now.
The best gotchas become checks. My clearest example: a database constraint added for one feature silently broke the writes of an older feature. Nobody could start a Leadership Assessment in my own product for 100 days. The page loaded, reads worked, and the table simply stopped growing. It was the third incident of that kind. So the gotcha became a pattern doc with a one-line diagnostic, "a near-empty table plus a recent constraint migration means the writer is failing, not idle", and then a script, npm run check:write-paths, that cross-checks every insert against the columns the database requires. A trap I'd paid for three times now costs a command.
This is also how you handle the legacy-code problem inside a young app. In an older codebase I worked in, the agent kept "fixing" a timezone workaround and a redundant-looking input check, and each fix was a regression. Once those were written down as notes next to the code, the same agent left them alone. That story is in the legacy codebase the agent couldn't read.
The rescue at a glance
| Step | What you write | Done when |
|---|---|---|
| 1. Freeze | A list of what's broken, triaged | No new features until the list is captured |
| 2. Map | The agent's map, corrected by you | You agree with how it says the app works |
| 3. Router + contextbase | A short CLAUDE.md or AGENTS.md, and docs/ | A fresh session can find the map without you |
| 4. Pin behaviour | Tests for the flows you can't break | They pass on the app as it is today |
| 5. Small briefs | One brief per fix, with runnable criteria | Tests green, session brief written |
| 6. Gotchas | One file per trap, and checks where you can | The next session doesn't hit it cold |
What changes once it's rescued
You can go back to building features, but the loop is different. Each feature starts from a brief, runs against the tests, ends with a session brief, and leaves its gotchas behind. You'll still vibe-code spikes and throwaways. I do. The line is that the moment something is meant to be kept, it gets a brief with criteria I can run.
A vibe-coded app isn't beyond saving. It's a codebase whose reasons were never written down. Write them down, pin the behaviour, and fix it a brief at a time.
Start here: read the story of vibe-coding into a corner, document a codebase with an agent, or set up C² in your repo.
Questions people ask
- How do you fix a vibe-coded app?
- Stop adding features first. Then have an agent map the app, write a short router file and a docs folder the agent reads before it works, pin the behaviour you want to keep with tests, and fix one problem at a time from a small written brief with criteria you can run. Record every trap you find so it is only paid for once.
- Should I rewrite a vibe-coded app from scratch?
- Usually not the whole app. A rewrite throws away the behaviour that already works along with the mess, and an agent rewriting from the same vague prompts tends to rebuild the same mess. Rewriting one small, incoherent feature from a proper brief can be the right call. I've done exactly that, and it was faster than debugging it.
- Can an AI agent clean up its own vibe-coded mess?
- Yes, if you change what it is working from. The mess came from steering by feel with no written target. Give the agent a map, a router file, tests that pin the behaviour, and a brief with acceptance criteria, and the same agent does careful work. Without those it keeps producing plausible changes that drift.
- What tests should I write first on a vibe-coded app?
- Tests that pin the behaviour you must keep, not the structure you plan to change. Pick the flows that would hurt if they broke, such as sign-up, payment, refunds or anything that sends email, and write a test for what they do today. Those tests are the safety net for every fix that follows.
- How long does it take to rescue a vibe-coded app?
- There's no honest single number. The approach is designed so you don't need one: you stop the bleeding in the first session by freezing features and writing the map, then every fix after that is a small, verified unit. The app gets safer with each brief, rather than all at once at the end of a big project.
Part of the C² Method. Start with the method
Put this in your repo
The C² Method is free and open. Point your agent at the kit and get started in minutes.