How to Hand Off a Vibe-Coded App to Developers: 8 Steps
To hand off a vibe-coded app to developers, give them three things alongside repository access: a written map of what the app is supposed to do, a verified way to run it from a clean clone, and evidence of what currently works versus what is broken. Handoffs fail when a team inherits AI-generated code with no specification, no tests and no bug list, because they have to re-derive intent from code that may never have matched the prompt that produced it. A day spent producing a feature inventory, a run book and a triaged bug list usually saves the receiving team weeks of archaeology.
Why is handing off a vibe-coded app harder than a normal codebase?
A conventionally built project arrives with artifacts the handoff can lean on: tickets, designs, commit messages tied to requirements, and whatever tests the team wrote along the way. A vibe-coded app built in Cursor, Lovable, Bolt, v0 or Replit often arrives with none of that, because the specification lived in a chat window that nobody kept.
Four things make these handoffs distinctive:
- The prompt was the spec, and the prompt is gone. The code is the only surviving record of intent, and it is a lossy one — it tells you what was built, not what was wanted.
- Patterns drift between sessions. Each generation session makes its own local choices about state, data fetching and error handling. An agent will not refactor across sessions unless asked, so you get two or three competing conventions in one repo, plus duplicated utilities.
- The code looks finished because the happy path works. AI-generated code tends to be syntactically clean and demo-ready. The gaps cluster in the places you never clicked: empty states, error states, permission boundaries, concurrent edits, slow networks.
- Platform scaffolding is baked in. Builder platforms add their own glue, seeded demo data and sometimes hosting assumptions. Developers need to know which parts are yours and which parts are the platform's.
None of this means the code is unusable. It means the handoff has to supply the context that the build process never wrote down. Our practical process for QA-ing a vibe-coded app covers the verification half of that in more depth.
How do you hand off a vibe-coded app to developers, step by step?
Work through these in order. Steps 1–3 are documentation, 4–6 are verification, and 7–8 are ownership.
- Freeze the feature set. Stop generating new features the moment you decide to hand off. A moving codebase makes every other artifact stale before it is read.
- Write a feature inventory. One line per screen and per flow: what it does, who is allowed to reach it, and what "working" means in observable terms. "Checkout" is not a spec; "a logged-in user with items in the cart can pay by card and receives a confirmation email" is.
- Make it run from a clean clone. List every environment variable, external service, database migration and seed step. Then have someone who did not build it follow your document on a fresh machine. Whatever they get stuck on is the real documentation gap.
- Audit secrets and access. Check for API keys committed to the repo or pasted into prompts, and rotate anything exposed. Do this before you widen repository access, not after.
- Walk the critical paths and record evidence. Identify the handful of flows the app exists for — signup, login, the core action, payment — and exercise each one deliberately, including the failure branches. Capture a reproducible report for every defect rather than a note that says "cart is weird sometimes".
- Triage into three buckets. Blockers that make the app unsafe or unusable, issues to fix before launch, and backlog. Developers need your judgment on priority, not a flat list.
- Leave a decisions log. A short page of "we chose X because Y" — the auth provider, the database, anything you tried and abandoned. This is the cheapest document to write and the one most often missing.
- Transfer ownership explicitly. Repository, hosting, domain and DNS, database, email sending, payment processor, analytics, and the AI builder account itself. Enumerate them; assume nothing transfers implicitly.
What should the handoff package contain?
| Artifact | Why the receiving team needs it | Good enough looks like |
|---|---|---|
| Feature inventory | Recovers intent the prompts no longer hold | One observable acceptance line per flow |
| Run book | Lets them change code on day one instead of day five | A clean clone runs after following it once, unaided |
| Triaged bug list | Separates known debt from new regressions they cause | Each entry reproducible from the report alone |
| Secrets and access register | Prevents a lockout and closes exposed credentials | Every account named with its current owner |
| Platform and dependency notes | Shows what is yours versus the builder's scaffolding | Export path confirmed to actually work |
| Test baseline | Tells them whether their refactor broke something | Critical paths covered and currently passing |
| Decisions log | Stops them relitigating choices you already made | One page of choices with reasons |
How do you prove the app actually works at the moment of handoff?
A handoff needs two kinds of evidence: reproducible reports for what is broken, and passing checks for what works. Claims without either are the reason handoffs turn into arguments about whether a bug is pre-existing or newly introduced.
For the broken half, the bottleneck is reproducibility. A screenshot pasted into a chat message loses the console errors, the failing network call and the environment the bug happened in, which is how "cannot reproduce" tickets are born. Snap captures a bug by right-clicking it in the browser and attaches the console log, network activity, DOM state and environment to the ticket, so the developer inheriting the app can reproduce it without you in the room.
For the working half, you need coverage of flows you may never have tried yourself. Sims runs AI personas through the app the way different user types would — the cautious new signup, the user with an empty account, the one who abandons mid-flow — which surfaces the empty-state and permission gaps that AI-generated code commonly leaves open. AutoSim then turns the critical paths into self-healing end-to-end tests. That property matters specifically at handoff: the first thing a new team does is rename and restructure things, and a brittle suite that breaks on every rename gets deleted in week two. A suite that survives refactoring is the baseline that tells them whether their cleanup changed behaviour.
Whatever tooling you use, write the critical-path list down and require each path to pass before the handoff meeting. For the broader picture of where automated checking fits, see our complete guide to AI QA.
What should you fix before handoff, and what should developers fix?
Fix what is cheap for you and expensive for them, or what is a live risk. Hand over what needs sustained engineering judgment.
| Issue | Who fixes it | Reasoning |
|---|---|---|
| Exposed or committed secrets | You, before handoff | Live security risk; rotation is quick |
| Broken signup, login or payment | You, before handoff | Nothing else can be assessed around a dead core path |
| Confirming the platform export works | You, before handoff | Discovering lock-in after the contract starts is expensive |
| Critical-path test baseline | You start it, they extend it | A baseline is only useful if it predates their changes |
| Missing error and empty states | Developers | Needs design decisions, not patches |
| Duplicated components, competing patterns | Developers | Consolidation is architectural work — see AI technical debt |
| Accessibility gaps | Developers | Systematic; note known gaps in the inventory |
Who owns quality after the handoff?
The handoff is a moment; quality is a process. The common failure is treating verification as a gate cleared on handoff day, after which the app degrades at the speed the new team ships. Two things prevent that.
First, keep the feature inventory alive. It is now the only written specification the project has, so whoever changes behaviour updates the line that describes it. Second, make the critical-path checks run on every change rather than before releases. The reason vibe-coded apps accumulate bugs is not that AI writes bad code — it is that code gets written faster than anyone verifies it, and a handoff does not change that arithmetic unless the verification becomes continuous.
If you are an agency receiving one of these projects, build the inventory and the bug list yourself during scoping and bill for it. It is the cheapest insurance against inheriting blame for defects you did not create, and the evidence trail shows the client which problems arrived with the code.
Where to start
Pick your three most important user flows, run them end to end today, and file every defect as a report a stranger could reproduce. That exercise produces most of a handoff package, and tells you whether you are handing over a working app with known gaps or an untested demo.
Try Klavity free — capture reproducible bug reports with Snap, run AI personas through your flows with Sims, and leave the new team a self-healing test baseline instead of a verbal promise.
Key takeaways
- Freeze the feature set before you start documenting the handoff.
- Prove the run book by having someone else follow it on a clean machine.
- Rotate every credential committed to the repo or pasted into a prompt.
- File each defect as a report a stranger could reproduce without you.
FAQ
What documents do developers need when inheriting a vibe-coded app?
At minimum: a feature inventory with one observable acceptance line per flow, a run book proven to work from a clean clone, a triaged bug list where each entry is reproducible from the report alone, a secrets and access register, platform and dependency notes, a passing critical-path test baseline, and a one-page decisions log.
Should I fix the bugs before handing the app over to developers?
Fix what is a live risk or cheap for you and expensive for them: exposed credentials, broken signup, login or payment, and confirming the builder platform's export actually works. Hand over work that needs sustained engineering judgment, such as missing error and empty states, duplicated components and accessibility gaps.
Why do vibe-coded handoffs produce so many 'cannot reproduce' tickets?
Because the evidence is usually a screenshot pasted into a chat message, which loses the console errors, the failing network request and the environment the bug occurred in. A bug report that carries console, network, DOM and environment state with it can be reproduced by a developer who was not present when it happened.
Do I need automated tests before a handoff?
You need a baseline on the critical paths, because the first thing a new team does is rename and restructure code, and without a baseline nobody can tell whether their cleanup changed behaviour. Keep it narrow and durable: a brittle suite that breaks on every rename gets deleted within weeks.
Catch bugs the moment a human sees them
Klavity: right-click bug reports, AI personas that review your product, and self-healing tests.
Get started free