How to hand a vibe-coded app to a developer

Why it matters

The first days of any engagement on an existing app go on finding things out. Where is the code? Which Supabase project is live? What is this key for, and is it still in use? Why does this table exist? With a vibe-coded app this takes longer than usual, because nobody wrote anything down. The decisions are spread across hundreds of prompts.

Every hour a developer spends on detective work is an hour you pay for that fixes nothing. A good handover pack cuts that to an afternoon. It also protects you: if everything is in your name, you can change developer, pause or stop at any point without losing access to your own product.

This checklist is what I ask for at the start of every rescue. You don't need all of it. The first two groups matter most.

If you only have an hour, do three things. Make sure the code is in a repository you own. Invite the developer to each service instead of sending passwords. And write a list of what is broken, in the order you want it fixed. Everything else can be filled in during the first few days, as long as those three are in place.

The checklist

If the code is in someone else's GitHub account, ask them to transfer it. GitHub's docs say issues, pull requests, history and stars move with it, and old links and git remotes redirect to the new location. For a transfer to a personal account, the recipient has to accept within a day or the request expires.

The README doesn't need to be long. It needs to get someone from a fresh laptop to the app running locally, and tell them where everything lives. This is enough:

# Project name
 
One paragraph: what the product does and who it is for.
 
## Run it locally
1. Node.js version: see .nvmrc
2. npm install
3. Copy .env.example to .env.local and fill it in from the password manager
4. npm run dev, then open http://localhost:3000
 
## Where things live
- Production hosting: Vercel project "project-name", team "your-company"
- Database: Supabase project "project-name" (production) and "project-name-dev"
- Payments: Stripe account "Your Company Ltd", webhook at /api/stripe/webhook
- Email: Resend, domain verified for mail.example.com
 
## Test accounts
In the password manager, under "Project test accounts".

Adjust the names to your stack. The point is that nobody has to ask.

Services make the invite route easy. GitHub lets you add a collaborator from the repository's settings. Supabase and Vercel both let you transfer a project between organisations or teams if it currently lives in someone else's. Supabase's docs note you need to be an owner of the source organisation, and Vercel's say a transfer keeps the project online.

Stripe has a Developer role meant for people setting up an integration. It is powerful: Stripe's docs say it can create secret keys and refund payments. Give it for the length of the work, then downgrade or remove it.

An .env.example file is the single most useful thing in a handover. It looks like this:

# .env.example: every variable the app needs. Copy to .env.local and fill in.
# Public (sent to the browser). Safe only with Row Level Security on every table.
NEXT_PUBLIC_SUPABASE_URL=          # Supabase dashboard, project settings
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
 
# Server only. Never prefix these with NEXT_PUBLIC_.
SUPABASE_SECRET_KEY=               # bypasses Row Level Security
STRIPE_SECRET_KEY=                 # Stripe dashboard, API keys
STRIPE_WEBHOOK_SECRET=             # from the webhook endpoint, starts whsec_
RESEND_API_KEY=                    # transactional email

In Next.js, the docs explain that any variable prefixed NEXT_PUBLIC_ is inlined into the JavaScript sent to the browser. Supabase's docs say its secret key bypasses every Row Level Security policy and must never be in a browser or source control. Between them, those two facts account for a lot of the leaked keys I find.

To check whether a live key was ever committed, search the history, not only the current files:

# Lists commits, on any branch, that added or removed the string
git log --all --oneline -S "sk_live_"

If anything turns up, rotate the key in the service's dashboard. Deleting it from the code does not remove it from the history.

Check your backup plan before anyone changes the database. Supabase's docs list daily backups on paid plans (7 days on Pro, 14 on Team) and recommend that Free plan projects export their data regularly themselves.

Common misses

These are the gaps I see most often, roughly in order:

• The domain is in the old developer's name. It works until it needs renewing or changing. Domain transfers are not instant, so start early.
• Two Supabase projects, and nobody is sure which is live. Check the URL in the production environment variables, and label the other one clearly or delete it.
• Keys shared in a chat. Assume anything sent by email, message or prompt is no longer secret, and rotate it.
• The builder and the repository drift apart. Someone fixes a bug in the repository, someone else prompts a change in the builder, and one overwrites the other. Pick one source of truth.
• No list of what is fake. A developer can lose hours debugging a payment flow that was never wired up.
• No backup. The first schema change on a database without a backup is the riskiest moment of the whole project.
• Prompt history treated as documentation. The reasons behind the app are buried in the builder's chat. Nobody can search it usefully, and it often contradicts itself. Pull the decisions that still matter into the README, in plain sentences.
• Access never removed. Old freelancers, agencies and test accounts keep their access long after the work ends. Review every service's member list when you hand over, and again when the work finishes.

What to ask for back

A handover runs both ways. When the work ends, the developer should leave the app easier to hand over than they found it. Ask for these before you sign off:

• An updated README and .env.example, matching the code as it is now.
• Every database change as a migration file in the repository, not only applied by hand in the dashboard.
• A short written summary of what changed, what was not fixed and why, and what they would do next.
• Any new service they signed up for, moved into your name.
• Their access removed, or a written agreement for ongoing support.

That last summary matters more than it sounds. It is the starting point for whoever works on the app after them, including you.

Next step

If you are still deciding whether to fix the app or start again, read when to refactor vs rebuild a vibe-coded app first. The answer changes what the developer needs from you. The vibe-code rescue checklist is what they will check once they have access, and what a rescue costs in the UK covers the budget side.

For the wider picture of what tends to break, see my guide to fixing a vibe-coded app. If you would like me to be the developer, start with the free health check. A Rescue Sprint begins with this handover and ends with the fixes in your repository, in your accounts.