The Handoff

The Vibe Guide, Part 3 of 6 — From vibe prototype to engineered product with VS Code + Claude Code

Where Prototypes Go to Die (or Grow Up)

Every vibe-coded project reaches the same fork in the road. The prototype works. People like it. And now you want to add real features, fix real bugs, and support real users — and you discover that "works" and "maintainable" are different words for a reason.

Most vibe-coding tutorials end before this moment. This is the moment we care about most.

The move: carry the Quests-bootstrapped project into VS Code with Claude Code and switch modes — from generation to engineering. Same AI leverage, completely different posture.

Why This Specific Handoff Works

Because Quests outputs a standard project on your filesystem — real files, conventional stack, Git history — there is no export step, no migration, no "download ZIP and pray." You open the folder in VS Code and you're already home. This is the payoff of choosing a local-first, open source bootstrap tool in Part 2: the handoff is a cd, not a project.

Claude Code is the right tool for this phase because it's built for the opposite job from a bootstrapper:

• Quests excels at: greenfield generation, fast iteration on a young codebase, parallel projects.
• Claude Code excels at: understanding an existing codebase deeply, multi-file refactors, disciplined incremental change, running your tests and build tools as part of its loop.

Using a bootstrapper for deep refactoring is like framing a house with a nail gun and then also trying to do the electrical with it. Change tools at the phase boundary.

The Handoff Ritual

Do these in order, before asking for a single new feature.

1. Freeze a baseline

git tag prototype-v1

You want a permanent "this is what the vibe built" marker. It's your rollback point and, honestly, your before/after brag material.

2. Write the CLAUDE.md

This is the single highest-leverage file in the repository. CLAUDE.md is the project memory Claude Code reads every session. Write down what the prototype phase kept in your head:

# Abyss Drift

Browser game: endless underwater descent, tilt-to-steer on mobile (IMU).

## Stack
- Vite + vanilla TS + Canvas. No framework by design — keep it that way.
- Deployed to Cloudflare Pages from `dist/`.

## Conventions
- Game state lives in `src/state.ts`. Do not scatter state into components.
- All device-motion code stays in `src/input/imu.ts`, incl. iOS permission flow.
- 60fps is a hard requirement on mid-tier mobile. Profile before/after perf-touching changes.

## Commands
- `pnpm dev` / `pnpm build` / `pnpm test`

Every rule you write here is a mistake the agent won't make later. This file is also the seed of your autonomous twin's brain in Part 5 — the same conventions that guide Claude Code interactively will guide NanoClaw autonomously.

3. The audit pass

First real Claude Code session — don't ask for changes, ask for understanding:

Read this codebase thoroughly. It was rapidly generated by a coding agent and works well. Produce a written audit: (1) architecture as-built, (2) duplicated or dead code, (3) fragile patterns that will break under feature growth, (4) missing error handling, (5) a prioritized refactor list where each item is independently shippable.

Two things happen: you get an honest map of the vibe debt, and Claude Code builds the context it needs for everything after. Read the audit yourself. Your decades of judgment are for deciding which findings matter — the agent finds everything; you rank what's worth fixing.

4. Refactor in shippable slices

Work the prioritized list one item at a time, each as its own branch/commit, each leaving the game fully playable:

• Extract the tangled game loop into clean systems (input, physics, render, spawn)
• Kill duplication the generation phase inevitably produced
• Add the error handling around the genuinely fragile bits (device APIs, storage)
• Establish a test harness — even a thin one — so future changes have a safety net

The discipline: never let the agent do a "big cleanup" in one shot. Big-bang refactors are where AI-assisted codebases go to die, exactly like human ones. Small slices, verified each time, with the agent running the build and tests itself.

5. Fit and finish

Now — and only now — the polish that separates shipped from shippable:

• Performance pass: profile on a real mid-tier phone, not your dev machine. Ask Claude Code to instrument, measure, and fix specific frame-time offenders.
• Accessibility: reduced-motion support, pause on visibility change, readable contrast, keyboard-complete controls on desktop.
• Progressive enhancement: the IMU fallback chain (motion → touch → keyboard) tested on actual devices.
• Metadata and PWA touches: proper icons, theme color, share cards, installability if it fits.

Each of these is a small, precise Claude Code task. The prototype phase was about breadth; this phase is about depth, one narrow thing at a time.

The Mental Model: Director, Not Typist

Across both tools, your role never changes: you direct, agents execute. But the granularity of direction changes at the handoff:

Experienced engineers sometimes resist vibe tools because they've only seen phase-1 behavior applied to phase-2 problems. The fix isn't less AI. It's phase-appropriate AI.

What You Should Take Away

1. The handoff is a cd, not a migration — that's why the open source local-first bootstrap matters.
2. CLAUDE.md is the highest-leverage file in the repo. Write it before the first change request.
3. Audit before you alter. Make the agent explain the codebase back to you.
4. Refactor in shippable slices, never big bangs.
5. You are the director. The agents got faster; your judgment got more valuable, not less.

The code is now something you'd defend in a review. Time to talk about where it lives.

Next: Part 4 — Deploy Like You've Done It for Decades, an honest compare-and-contrast of hosting options from people who have opinions earned the hard way.