What Nobody Tells You About Vibe Coding

Everyone tells you to build your dream app with AI. Almost nobody tells you what comes after the first demo.

The biggest pain I keep seeing isn't getting the app built. It's trusting it. A few months later, people no longer understand how their own codebase works. They make one change, something unrelated breaks. They fix that, something else breaks. Eventually the project becomes too frustrating to maintain, so they either abandon it or hire someone like me to untangle the mess.

I've been writing software for 16 years, and for the last 4 years I've been building with AI every single day. During that time, I've found myself giving the same advice over and over through articles, posts, comments, and consulting. Eventually I realized it was all solving the same problem from different angles. It belonged together in one place, in the right order. That's what led me to start writing This Vibecoder's Handbook.

Every project eventually reaches the same questions. How do you organize the code? How do you stop AI from making the project harder to maintain over time? How do you debug it, deploy it, secure it, and keep building without everything falling apart?

2 of the 10 parts are finished, and I'm currently writing the third. If you think something is missing, unnecessary, or just wrong, I'd love to hear it before I keep going.

TABLE OF CONTENTS

Part 1: Plan

Structure your idea into a clear specification

1.1 Workspace: Set Up Your Workspace

• Your own computer is enough
• The agent matters more than the editor
• Pick where you work
• Never lock into one model
• Make a folder and a home for your spec
• Set it all up in one pass

1.2 Requirements: Turning an Idea Into a List

• A requirement is testable, not a wish
• Write each one as a user story
• Split must-have from later
• Get them from real users, not your head

1.3 MVP: Cutting Scope to the Core

• An MVP is the smallest version worth shipping
• Apply the one core job test
• Expect to cut some must-haves too
• Build a walking skeleton, not half an app
• Guard the line against scope creep

1.4 Components: The Pieces of an App

• The five pieces
• Frontend and backend are two programs
• The API is a contract, not a place
• The database remembers, hosting runs it
• Trace one click through all five

1.5 Data Model: Mapping What You Store

• The shape of your data is called a schema
• List your entities and their key fields
• Draw the relationships between them
• Keep it a sketch, not a database

1.6 NFRs: The Hidden Requirements

• What it does vs. how well it does it
• Set a number, never an adjective
• Write them down for your AI before it builds

1.7 Spec: Writing It All Down

• A spec is a document your agent builds from
• Short and living, not forty pages
• Assemble the sections you already have
• Keep it in the repo, next to the code

Part 2: Dev Setup

Prepare your environment and tools

2.1 Stack: Picking Your Tech Stack

• A stack is layers, bottom to top
• Default to the popular choice
• A stack for almost any app
• Switch when the job demands it
• Let your agent choose for your case

2.2 Agent: Meeting Your AI

• What an agent actually is
• What it can and can't do
• It works from context, not memory
• Trust it to type, not to decide

2.3 Rules: Setting the Ground Rules

• A rules file is your standing instructions
• Put the non-negotiables in writing
• Keep it short and living
• Where the file lives

2.4 Version Control: Never Losing Work

• Git is your undo button
• Your AI runs Git, not you
• Every experiment gets its own branch
• Commit after every working step
• Version numbers that tell the truth
• Set the Git rules once

2.5 Dependencies: Living on Other People's Code

• What a dependency actually is
• Pick popular, maintained, and alive
• Update often, but never blindly
• Lock versions so builds stay identical
• Check the license before you build on it

2.6 Secrets: Handling Keys and Config

• What counts as a secret
• Keys never touch the code
• One .env file, never committed
• Rotate anything that leaks
• Wire it up for your stack

Part 3: AI Set Up

Setup your AI agents operating system
WiP...