Ship your first vibe code project!
The eight steps from a rough idea to a URL you can send someone, walked one step at a time, with the prompts to copy.
Here is the whole path from a rough idea to a URL you can send someone. Read the map first, then walk it one step at a time.
The map
Nine steps in three phases. The middle phase is a loop you will run many times, and that loop is where almost all the hours go.
Phase 1, set up
Phase 2, the loop
Phase 3, ship
Time split, roughly. Phase 1 is an afternoon. Phase 3 is an hour. Everything else you spend goes into phase 2, which is why the building step gets the most detail.
Brainstorm until you have a CLAUDE.md
Open a normal Claude chat, not the coding tool. Your opening message sets the shape of the whole session, so use it to hand over the driving seat. You are here to be interrogated, and the idea can still be messy when you arrive.
I am starting a vibe coding project and this conversation is where I plan it. Here is the idea in the shape it is in right now: [describe it, messy is fine] Who I think it is for: [a line or two] What it has to do on day one: [a line or two] I will talk through my thinking as we go. Your job is to ask me clarifying questions, one topic at a time, until you are confident you could write a CLAUDE.md that I can use to initialise this project in Claude Code. Cover the users, the scope of v1, the data, and the stack. Push back when my answers are vague. Do not write any code. When you are confident you have enough, tell me and we will write the files then. If I say park it, add the question to a running list and move on.
Then talk. Answer in whatever detail you have, and say park it for anything you cannot answer yet. Expect twenty to forty minutes of back and forth. A conversation that ends in five means you agreed with everything and learned nothing.
You are aiming for four answers you can give without hedging. What it is in one sentence. Who it is for. The three screens or fewer that make v1. What you store and where.
When it says it has enough, ask for the files
CLAUDE.md is the standing brief the coding agent reads at the start of every session, so it carries the decisions you do not want to re-explain. Ask for PARKED.md alongside it, holding every question you dodged. Take the extras only when they earn their place: PRD.md for scope and user stories, SCHEMA.md for the data model, DESIGN.md for look and feel rules, ROADMAP.md for everything after v1.
Read the brief before you accept it. If a line describes a product you did not ask for, fix it here, where it costs one message.
Move on when you could hand those files to a stranger and they would know what to build.
Set up your machine and connect your tools
What lives on your computer
You will spend the whole project in two windows, so install them before you need them.
- Visual Studio Code. Free, and it is where you see the folder, open files, and type your keys in later. You are not writing code in it, you are looking at what got built.
- A terminal. Terminal on Mac, Command Prompt or PowerShell on Windows. Claude Code runs here. VS Code has one built in under the View menu, which saves you juggling windows.
- Git and Node. Your project needs these underneath. Install Claude Code first and ask it what else is missing, then follow what it tells you.
What you connect
Connect GitHub and one host, Vercel or Netlify, on every project without thinking about it. Then add whatever this particular project depends on: Supabase if it stores anything per user, Resend if it sends email, Stripe if it takes money. If a service is not in v1 scope, leave it out.
Do this before the first line of code. Connected up front, Claude can create the repo, spin up the database and read its own build logs. Connected later, you spend the week copying things between browser tabs.
Tell me which tools and connectors you can currently see from this session. List my GitHub repos and my projects on Vercel or Netlify so I know the connections are live. Then tell me what else this project will need that I have not connected yet.
Move on when Claude can list your repos and projects without you pasting anything in.
Drop the files in a folder and initialise
Make a new empty folder somewhere you will find it again. Put CLAUDE.md and the other markdown files inside. Open that folder in VS Code, open the terminal, start Claude Code, and give it one instruction.
Go through all the files in this folder. Ask me clarifying questions until you understand the project properly. When you have enough information, initialise it.
Then answer honestly. The questions you cannot answer yet are the important part: say park it, we will revisit this later and move on. Claude Code will raise things the planning chat never thought of, so tell it to append those to the PARKED.md you already have. That file is what brings the questions back to you instead of letting them quietly disappear.
Do not invent an answer to look decisive. A guess here becomes an architecture you have to unpick in two weeks.
Watch what it does. You should end up with a running project, a folder of files you can see in VS Code, git initialised, and a first commit. Ask what each top level folder is for. Two minutes now saves you being lost in your own project on day four.
Move on when the project exists, git is initialised, and the first commit is in.
Set up your environment properly
The moment a real service is involved, your project needs keys. A key is a password that proves your app is allowed to talk to Supabase, or Resend, or Stripe. They cannot sit in the code, because the code goes to GitHub, and anything in the repo is one bad setting away from being public.
So keys live in a file called .env.local that stays on your machine and never gets committed. Ask for the walkthrough, then type the real values in yourself in VS Code.
Walk me through setting up my local environment for this project. Tell me every key I need, where in each dashboard I get it, and what each one does. Show me the .env.local with placeholder values only, and tell me which of these are safe to expose to the browser and which must stay server side. I will fill in the real values myself.
The rules that keep you out of trouble
- Never paste a key into a chat message. Not here, not in Claude Code. Claude can read the file directly when it needs to, and anything you type into a chat lives in that transcript for good.
- Check the ignore list before the first commit, not after. Once a secret is in git history, removing it is an afternoon of work.
- Know which keys are public. Some are designed for the browser and some will drain your account if they leak. In a Next.js project, anything named with a
NEXT_PUBLIC_prefix is visible to anyone who opens the page. Never put a secret behind that prefix. - Your host keeps its own copy. Vercel and Netlify each store environment variables in their dashboard. Local values do not travel with the code, so when a site builds fine locally and breaks live, this is the first thing to check.
- Rotate anything that leaks. Generating a new key takes two minutes. Assuming it was probably fine does not.
Show me exactly what git would commit right now. Confirm that .env.local and any other secret files are gitignored, and flag anything in this list that should not be going to GitHub.
Move on when the app runs locally with real keys, git cannot see the env file, and the same variables are saved at your host.
Build it in slices
This is the step that swallows the hours, so it deserves a method. The method is slices: one thing a user can do, built all the way through, before you touch the next one.
Add a task Slice 2
See the list Slice 3
Mark it done Screen Form List view Checkbox Logic Validate Fetch Update Data Save row Read rows Edit row Shipped Next Later
How one slice runs
Before slice 1, deploy an empty skeleton
Get one page rendering with the layout and routing in place, push it, and connect the host. A deploy on day one surfaces the boring problems early: environment variables, build settings, the wrong Node version. Finding those on your last day is how a two hour launch becomes a two day launch.
Order matters
- Data model and login early. Changing a schema on day three is a prompt. Changing it on day thirty is a project.
- The ugly paths next: empty states, bad input, someone who is not logged in.
- Polish last. Fonts, spacing and animation are cheap to change and easy to redo.
Ask for the plan before the code
Any change big enough to make you nervous gets a plan first. You catch a wrong assumption while it is still one paragraph.
Before you write any code, give me your plan for this slice and the list of files you will touch. Flag anything that changes the data model or affects a feature that already works. Wait for my go ahead.
Keep the brief alive
When a decision changes, update CLAUDE.md in the same session. It is the memory that survives when the context window does not. At the end of each slice, reread PARKED.md and see whether you can now answer anything on it.
Move on when one user-facing thing works end to end, including the paths where the user does the wrong thing.
Test every build on localhost
Every time Claude finishes something it runs a dev server and hands you an address like localhost:3000. That is your build, running on your machine, updating a second or two after each change. Keep it open in a browser tab beside your terminal.
Test after every build, not every third one. Claude reports what it intended to do. Only you can confirm what it actually did, and finding a fault three slices later means unpicking three slices.
What to click
- The happy path first. Do the thing the slice was built for, start to finish.
- The empty state. Load the page with no data in it at all.
- Bad input. Submit the blank form. Put letters in the number field. Paste a paragraph into a name field.
- Interruptions. Refresh halfway through. Hit back. Open it in a second tab.
- Phone width. Drag the window narrow, or open dev tools and pick a phone.
- Last week's features. Check the thing that already worked still works.
Report faults like a tester
The quality of the fix depends almost entirely on the quality of the report. "It doesn't work" gets you a guess, and a guess usually changes three files that were fine. Give it four things: what you were doing, what you expected, what actually happened, and the exact error text.
The error text lives in two places. The terminal running the dev server holds server errors, and the browser console, which opens with F12 or right click then inspect, holds the ones the page threw. Copy the whole block, not the first line. For anything about layout or spacing, a screenshot says more than a paragraph.
Something is broken. Here is the detail. What I was trying to do: [the steps you took, in order] What I expected to happen: [the correct outcome] What actually happened: [the current outcome, described exactly] Error from the terminal or browser console: [paste the whole thing] Find the cause before you change anything. Tell me what is wrong and what you plan to fix, then fix only that. Do not touch anything unrelated.
Then retest the same path before you move on. Fix one fault at a time. Two fixes at once and you will not know which one worked, or which one broke the next thing.
Move on when the slice survives the list above and the console is quiet.
Commit at every milestone
A milestone is anything you would be annoyed to lose. A working slice, a fix that took an hour, a schema change that finally runs. Ask Claude to commit and push, with a message that says what changed and why.
Commit before you try anything risky too. A commit is a save point, and knowing you can walk back makes you braver with the experiments.
With GitHub wired to Vercel or Netlify, the push triggers a build and your link updates itself. Open the link and check the same path you just tested locally, because the live environment has different keys and can fail where localhost passed.
Then send it to one person, in front of you, and watch them use it. Their first thirty seconds will tell you more than an hour of your own testing.
Move on when the work is pushed, the build passed, and the live URL shows what you just built.
Repeat five to seven
The loop is the job. Everything before it was setup and everything after it is admin.
Every few loops, stop and read CLAUDE.md against what you have actually built. Some drift is normal. Drift you have not noticed is what turns a two week build into an abandoned folder.
New ideas will arrive mid-loop and they will feel urgent. If it sits outside v1 scope, park it in ROADMAP.md and keep going.
Move on when the v1 scope from step one is built and the new ideas are parked rather than half-built.
Ship it and hand it over
Done means someone who is not you can use it without you sitting beside them. Test that literally. Send the link, say nothing, watch.
If it deserves one, add a custom domain. Both Vercel and Netlify take a few minutes and Claude can walk you through the DNS records. Then ask for a short README covering how to run it locally and which keys it needs, so future you can pick it up cold.
After that you either park the project or start the loop again, this time with real feedback instead of assumptions. The second version is always faster.
You are done when a stranger reached the end of the main flow on the live link without asking you a question.
Seven ways this goes wrong
- Building across the rows. Three half-finished layers and nothing you can test.
- Answering clarifying questions with guesses. Park it instead. The guess becomes load-bearing.
- Pasting keys into chat. They live in the transcript forever. Rotate anything you leak.
- Forty changes and no commit. One bad session takes the good work out with the bad.
- First deploy on the last day. The first deploy always breaks on something dull. Get it out of the way early.
- Reporting faults as "it doesn't work". Four lines and the error text turn a guess into a fix.
- Letting CLAUDE.md go stale. The next session starts from a brief that describes a different product.
People keep asking me what vibe coding actually looks like day to day. The demos compress it into one prompt and a finished app. A real session runs longer and moves in a loop, and that loop has a shape you can learn.
This is the shape I use. The map is up top so you can see the whole thing at once, then you walk it one step at a time. Step four is where most of the hours go, so it gets the most detail. The prompts are copyable because they are the ones I actually type.
Written for people who can follow instructions but have never shipped a web app before. If you have shipped a few, switch it to read all and skip to the loop and the failure list.