The Complete Vibe Coding Playbook for Founders

For 14 years, we've built digital products with high-growth founders and Fortune 500 payments leaders. Projects like SDR (a fintech payments build) and NEU (a rehabilitation network of 250+ practices and 1,500+ certified specialists) taught us where vibe coding earns its place, and where it quietly costs you.

The rule underneath it: no one can read minds. Not the sharpest engineer, not the best AI. Useful software comes from breaking a problem into pieces small enough to fit in one head, where the logic is clear and the unknowns are gone. Vibe code shines when a task breaks down cleanly. It struggles when the value lives where a prompt can't reach: the business logic and the experience users feel.

Where the line really is

The screen count was never the point. What matters is how cleanly the task decomposes, and where the value lives.

• Making the AI talk like a therapist isn't a prompt. You define the clinical practices, bring in real therapists to validate behavior, and feed in user reactions as they arrive. The instructions never stop changing.
• The models cost real money. Each trades off price, intelligence, and speed. Finding the point where the AI helps a person and still protects your margin takes testing.
• B2C punishes the wrong call. What looks right to a founder can read as wrong to a user, and every lost user is lost revenue. Retention, conversion, and LTV are earned over time.
• Some answers only the market gives you. What's a "normal" sleep score? Which analytics does a user value? Research and real usage answer that — a prompt can't.

Fintech draws the same line. A couple of tables and a profile? Straightforward. Connecting to a bank, moving real money, and writing transaction logic that has to be right every time, the work behind SDR, is beyond what vibe code can own.

Lessons from real systems

• The "right" solution depends on what AI can't see. The AI told a client to build a website builder from scratch — a three-month estimate. We adapted a proven tool in two weeks on a $200-a-month subscription. The model couldn't weigh that trade-off. Experience could.
• AI will tell you it works before it checks. On a build, it assured us PayPal would work, wrote the code, and shipped nothing that ran. Its reply: "Oops, I didn't check." Harmless in a chat window. Costly in production.
• Scale is its own discipline. An app serving 5 to 10 pages to 200 users is not built to stay fast for 50,000 a day. Speed under load, fault tolerance, recovery — that's how a team keeps your business from losing money. In B2C, your users are the money.

Don't write this alone. Draft it with Claude, and keep going until it can explain your product back to you correctly.

Act as a sharp product manager. Help me define the first version of [my idea].
Ask me one question at a time about: the domain, the single user it's for, the
problem, the one core flow that proves it, what a tester should do end-to-end,
and what would prove it's worth building. Don't stop at my first answers — keep
asking until you can explain my product back to me correctly. Then summarize it
as a short product-map.md I can save.

Pressure-test it before you build

A definition that reads fine to you can still hide a vague user or a fuzzy core flow. Ask Claude to score your product-map.md and aim for 8.5 or higher before moving on.

Run scoring rubric. Think/reason thoroughly. Don't worry about tokens. Tell me
what works good/bad and what can be improved. Do not come up with new ideas if
nothing is actually bad. If it's okay, say that it's okay. Ask as many questions
as you need when in doubt.

The four rules that keep Claude on track

You put these in place across the next three parts: your stack, your master file, and your project files. After that, building is the straightforward part.

Getting started

You don't install developer tools yourself. Get Claude Code (or any alternative), and it guides the setup and runs most commands for you. You'll never need to understand the terminal deeply.

I'm non-technical and starting from nothing. Install anything this project
needs on my computer (Node, Git, etc.), then scaffold a starter app with:
- React + TypeScript + shadcn/ui on the front end
- NestJS + Prisma + PostgreSQL on the back end
- a plain placeholder home screen, no auth yet (we add Firebase auth later,
  only when a feature needs it)

Set up your project

A consistent stack keeps Claude from drifting. The exact choice is yours, or your team's — what matters is that you pick one and stick to it.

This guide defaults to a handoff-ready, full-stack setup: a real backend and database a team can inherit, with Firebase for auth and file storage. Firebase never holds your product data — that lives in PostgreSQL through Prisma.

Save your stack to CLAUDE.md

Use this exact stack for the whole project and never switch without asking me:
React + TypeScript, shadcn/ui, NestJS, Prisma, PostgreSQL, Tailwind, and
Firebase for authentication and file storage (don't hand-roll auth). Add this
to CLAUDE.md so it applies in every session.

Your folder structure

You'll never touch these by hand. This is just so the structure feels familiar.

frontend/                  # everything users SEE (React + shadcn/ui)
  screens/
  components/
  types/
  
backend/                   # the ENGINE (NestJS)
  modules/                 # one folder per feature: orders, customers...
    orders.controller.ts   # receives requests
    orders.service.ts      # the business logic
  prisma/schema.prisma     # your database blueprint
  
.env                       # secrets — never shared, never hardcoded

Your master file: CLAUDE.md

The most important file in your project. Claude reads it at the start of every session. The long blocks here are written for Claude, not for you to study. Skim, paste, and move on.

Run /init to create a CLAUDE.md from this project, then update it to match the
rules below and keep it under 200 lines.

Then replace the file's contents with the standards below. These are the guardrails a senior engineering team would set. The security rules are non-negotiable; the architecture rules are strong defaults a developer can override with a clear reason.

# Project: [App Name]
You are building a working FIRST VERSION for a non-technical founder. A human dev
team will take this over and extend it. Optimize for clean, conventional, consistent
code any mid-level engineer can read on day one, not clever code. Explain everything
in plain English.
 
## How to work with me
- No jargon. Before writing code, show a short plain-English plan.
- Ask me before anything that affects product behavior, data, security, cost, or
  architecture. For small implementation details, pick the conventional option and tell me after.
- If a request will cause problems later, say so and propose a better way.
- Work in small steps, one feature at a time. Show me the result after each.
- After building, run the checks below and show evidence. Never just claim success.
 
## Tech stack (use every time, never switch without asking)
- Frontend: React + TypeScript (strict mode on)
- UI: your design system (shadcn/ui by default) - use its components, don't hand-roll UI
- Styling: Tailwind CSS - use theme tokens, no arbitrary hex values
- Backend: NestJS (Node + TypeScript)
- Database: PostgreSQL, accessed only through Prisma (no raw SQL)
- Auth & file storage: Firebase (or Supabase). Never build authentication yourself.
 
## Architecture (follow in every change)
- One screen = one file. One job per file. Split anything that grows too long.
- Business logic lives in services, never inside screens/components.
- One backend module per feature: controller + service + DTOs.
- All database access goes through Prisma. Use include/select to avoid N+1 queries.
- Reusable UI in /components. Shared data types in /types.
- No global mutable state. Pass data explicitly or use one documented store.
- Paginate any list that can grow. Never load unbounded data into the UI.
 
## Security (non-negotiable)
- Never hardcode secrets, URLs, passwords, or keys. Use environment variables (.env).
- Never commit .env or any secret. Confirm .env is in .gitignore.
- Never expose secret/service keys to the frontend. The frontend gets public keys only.
- Validate and sanitize every input on the server, not just the client.
- Require auth on every protected route. Check ownership before returning a user's data.
 
## Data standards
- Money: store as integer cents, never floats. Format for display only.
- Dates/times: store in UTC as ISO 8601 strings. Convert to local time in the UI.
- IDs: use UUIDs for anything user-facing, not sequential integers.
 
## Build order for any feature
1. Plan (plain English)  2. Data model (Prisma)  3. Screen
4. Actions (buttons, forms, filters)  5. Tell me exactly what to click to test
 
## Verify your own work (always)
- Write a test for the main path and run it. Run the build before finishing.
- For UI: screenshot the result, compare to the design, fix the differences.
- Show evidence (test output / screenshot). Do not just claim success.
 
## Never (hard rules, no exceptions)
- Hardcode secrets or commit .env.  - Skip the plan.
- Add libraries without telling me.  - Assume I know technical terms.

The files that keep Claude on track

A few plain-text files turn Claude from a clever stranger into a teammate who knows your project. Keep them in the repo (your project's code folder on GitHub), and Claude reads them every session.

# Conventions
## UI
- Use your design system's components by default (shadcn/ui). Build custom UI only when nothing fits.
- One consistent spacing and color scale. Use Tailwind theme tokens, no arbitrary hex.
- Every screen has three states: empty, loading, and error.
- Layout is responsive from 360px (mobile) to desktop.
 
## Files and structure
- One component per file. Split anything that grows too long.
- Co-locate types with the feature that uses them; shared types go in /types.
- Group by feature, not by file type (orders/ holds its screen, components, types).
- Prettier formats all code; ESLint passes with zero warnings before every commit.
 
## Naming
- Components: PascalCase (OrderList). Functions/variables: camelCase (getOrders).
- Booleans read as questions: isLoading, hasError, canSubmit.
 
## Data
- Money stored as integer cents; formatted for display only.
- Dates stored as ISO 8601 strings in UTC; shown in the user's local time.
 
## API
- REST routes named by resource: GET /orders, POST /orders, GET /orders/:id.
- Correct status codes (200, 201, 400, 401, 403, 404, 500).
 
## Comments and Git
- Comment the "why", not the "what". Good names remove the need for most comments.
- Conventional commits: feat, fix, chore ("feat: add customer detail").
- Commit after each working feature.

You already created product-map.md in Step 1. Keep it current so the whole app stays visible on one page.

Reliqio insights

Hard-won opinions from building production apps. Treat them as strong defaults, not gospel.

Use [shadcn/ui | MUI | Ant Design] for all UI - prebuilt components only, never
hand-rolled. I've connected my Figma over MCP: match its designs, colors,
spacing, and components. Add this rule to CLAUDE.md.

Start the app with a health check

Add a simple health-check home screen, then start the app. The screen should
check and show whether each part of the stack is connected: the frontend
(React + shadcn/ui), the backend (NestJS), and the database (PostgreSQL via
Prisma). Show each as a labeled row with a clear connected / not connected
status. Then tell me the exact URL to open and what I should see. If anything
fails, fix it and try again before you reply.

What you should see

Open the URL Claude Code gives you (usually localhost:3000). Every part of your stack should read connected:

• The health screen loads as a real screen, not a blank page or an error.
• Every row shows "connected" (green), none show "not connected".
• The terminal shows the app running with no red error messages.

No login yet, on purpose. You don't hand-build auth; Firebase handles that later, when a feature needs it.

If something doesn't work

A red row or a failed start is normal at this stage. Don't debug it yourself — hand it the problem.

The app didn't start, or a row on the health screen shows "not connected."
Here is what I see: [paste the error text or describe what happened]. Find the
cause, fix it, and tell me in plain English what was wrong and what you
changed. Then start the app again.

Describe what the user sees, not what the code should do.

Describe it from the user's side: what they see, what they click, what happens next. Claude handles the technical work; you give direction. You're the director describing the scene. Claude is the cinematographer choosing the angles. Name the constraints you actually understand, and don't invent architecture you don't.

Think like a product manager (the part most founders skip)

A requirement isn't a wish like "build an orders page." It's a small, clear agreement about what counts as done:

• Who it's for, and why. The user story: "As a manager, I want all orders in one place, so I can act fast." (user stories)
• What must be true to call it done. Acceptance criteria, each a clear yes or no. (acceptance criteria)
• When you'd actually ship it. Definition of done: it works, it's tested, no errors on screen. (definition of done)
• One thin slice, not the whole cake. One screen a user can use end to end.

The anatomy of a good prompt

Good, vague, and over-specified prompts

Good vs. bad feature definitions

# Feature: Orders
Build an orders page where users can see and manage their orders.

# Feature: Orders list
Who uses it:   Manager, Admin
What they see: Table (date, customer, total, status); filter by date & status; empty state
What they do:  Click a row -> order detail; filter; export CSV
Data source:   Orders for this org, last 90 days
Rules/edges:   Managers see only their own orders; admins see all; validate inputs
Done when:     I can filter the table and open any order's detail

Write each feature in two or three iterations

Use the product management skill. Help me write a requirement for the [Orders]
screen. Cover: who uses it, what they see, what they can do, where the data
comes from, edge cases, and a clear "done when". Ask me questions about
anything unclear before you draft it.

Read features/orders.md. Turn on plan mode and show me a short plan first.
Then build it in this order: data model, list, detail, form, actions. Use
shadcn/ui for all UI. When done, run the tests and tell me exactly what to
click to test.

Score your requirement before you build

Five minutes scoring a requirement saves hours rebuilding the wrong screen. Aim for 8.5 or higher.

Score my feature requirement from 1 to 10 on each of: clear user, clear
experience (see / do / next), defined data source, edge cases (empty, error,
permissions), a testable "done when", and tight scope. Think it through and
don't worry about tokens. Tell me what's weak and exactly what to add. Don't
invent problems if it's already solid, and if a category already scores 8.5 or
higher, just say no change needed. Ask me questions where it's unclear.
I want at least 8.5 before I build.

Three habits that compound

• Screen by screen. Never ask for the whole app at once. One screen per chat.
• Build by analogy. "Build the Customers page the same way as the Orders page." Claude copies the pattern and the app stays consistent.
• Refine in layers. Basic table first, then filters, then search, then export.

The mistake that wrecks more apps than bad prompts: context overload

Claude can only see the current conversation. The longer a chat runs, the more it loses the start. One conversation equals one screen. Start a new chat when Claude repeats code, slows down, forgets a component, or you can't scroll back. Paste a short brief so it picks up where you left off:

We're continuing [App Name].
Already built: login, Orders (list, detail, create form).
Data models: User, Order, Customer.
Now build: [the next screen].

Break it into small tasks

If you can't describe a task in a few plain sentences, it's two tasks. Split it, then build each screen in the same order. Each step depends on the one before it:

Build order, every feature: data model → list view → detail view → form → actions. Build a form before its data model, and Claude invents the fields on the fly.

You don't run any of this by hand. Ask Claude Code:

Set up git for this project, add a sensible .gitignore (never commit .env or
node_modules), and push everything to a new private GitHub repo. From now on,
commit after every working feature with a short message.

Push to GitHub → on railway.com, "Deploy from GitHub repo" → add a PostgreSQL database, then reference its DATABASE_URL in your app service. Then let Claude finish the config:

Prepare this project to deploy on Railway: set the build and start commands,
read the database from the DATABASE_URL environment variable, and walk me
through deploying step by step.

Handoff checklist

• Code on GitHub, committed after each working feature
• CLAUDE.md, conventions.md, product-map.md all current
• README with install / run / test / build commands (ask Claude to write it)
• .env.example listing required secrets (no real values)
• Reviewed with /code-review ultra or the Reliqio analysis skill; tests pass
• A short note of known rough edges for the team