Part 1: Why Your Vibe Coding Keeps Breaking (And How to Actually Fix It)

Hi, it's G.

Let me guess how you got here.

You heard about AI coding tools. You got excited. You opened Cursor or Claude or whatever shiny new agent everyone's hyping up, typed "build me an app that does [thing]," and waited for magic.

Instead, you got broken code. Pages that don't connect. Colors you never asked for. A button that does absolutely nothing when you click it. And an app that kinda-sorta works until it completely doesn't.

So you blamed the AI. Called it stupid. Said it hallucinated. Moved on to the next tool, hoping that one would be better.

Pero ang totoo? The AI isn't the problem.

You are.

I know that stings. I've been there too. Spent days rebuilding the same feature over and over because I kept giving AI nothing to work with. No structure. No clarity. Just vibes and prayers.

Here's what I learned the hard way: AI doesn't hallucinate because it's broken. It hallucinates because you gave it nothing solid to hold onto.

This is Part 1 of a 4-part series where I'm going to teach you the actual system behind vibe coding. Not the TikTok version. The real one. The one that works when you need to ship something that matters.

If you follow this through to the end, you'll have a complete, production-ready workflow. If you skim it and forget it, well, you'll stay stuck. Your choice.

Let's fix you.

Why You're Actually Failing

You skipped the fundamentals.

You don't know what a component is. You don't know what state means. You don't understand why your button doesn't work. You don't know why your site looks fine on your laptop but breaks on your phone.

And because you don't know these things, you can't describe them to AI.

That's the core problem. AI is a translator. It converts your intent into code. But if your intent is shitty and vague, the code will be shitty and vague. If you can't articulate what you want, AI guesses. And those guesses compound into total chaos.

I used to think better prompts were the answer. Nope. The answer is better understanding.

Once you know what you're building, prompting becomes trivial. The words come naturally because you finally know what to ask for.

And that's what this series is about. Not teaching you to code. Teaching you to think like someone who can direct a coder, which is what AI actually is.

The System You've Been Missing: Documentation First, Code Second

Here's where everyone gets it wrong.

You open your AI tool, start describing your app, and let it generate code immediately. No plan. No reference. No source of truth.

This is why your project falls apart after three files.

The real system? Documentation first, code second. Always.

Before you write a single line of code, you write your project's canonical documentation. Clear, specific, unambiguous descriptions of what you're building.

Why?

Because AI coding tools have high capability but low certainty. They can execute tasks, but they have no structural guardrails. Without locked constraints and authoritative documentation, AI hallucinates requirements, makes unauthorized architectural decisions, and produces code that solves problems you never asked it to solve.

The failure isn't lack of coding ability.
The failure is lack of discipline and context preservation.

Think of it this way: if you hired a developer and said "build me a social media app" with zero other details, what would you get? Probably something that vaguely looks like social media but has none of the specific features you actually needed.

Same with AI. Except AI moves faster, so the mistakes compound quicker.

The 6 Canonical Docs (Your Knowledge Base)

These are the six markdown files you write before touching any code. They define your entire project.

1. PRD.md (Product Requirements Document)

This is your contract with reality.

What you're building. Who it's for. What features exist. What's in scope. What's explicitly out of scope.

Include user stories, success criteria, non-goals. Every feature should have specific criteria. If you can't describe when something is "done," you're not ready to build it.

Example snippet from a real PRD:

Feature: User can create a recipe
Success criteria:
- Form has fields for title, ingredients (array), steps (array), photo upload
- Ingredients and steps can be added/removed dynamically
- Photo uploads to storage and returns URL
- Recipe saves to database with user_id, timestamp
- User redirects to recipe detail page after successful save

Out of scope:
- Recipe sharing to social media
- Recipe ratings/reviews
- Ingredient quantity calculations

Don't have this? You're not building an app. You're praying for one.

2. APP_FLOW.md

Every page. Every user navigation path. Documented in plain English.

What triggers each flow. Step-by-step sequences with decision points. What happens on success. What happens on error. A screen inventory with routes.

This prevents AI from guessing how users move through your app.

Example:

Login Flow:
1. User lands on /login
2. Sees email field, password field, "Login" button, "Sign up" link
3. On submit:
   - If credentials valid: redirect to /dashboard
   - If credentials invalid: show error "Invalid email or password"
   - If user doesn't exist: show error "No account found"
4. "Sign up" link goes to /signup

See how specific that is? No ambiguity. AI reads this and knows exactly what to build.

3. TECH_STACK.md

Every package, dependency, API, and tool. Locked to exact versions.

When AI sees "use React," it might pick any version. When it sees "Next.js 14.1.0, React 18.2.0, TypeScript 5.3.3," it builds exactly what you specified.

This eliminates hallucinated dependencies and random tech choices.

Example:

Framework: Next.js 14.1.0
Language: TypeScript 5.3.3
Styling: Tailwind CSS 3.4.0
UI Components: shadcn/ui
Database: Supabase (PostgreSQL)
Auth: Clerk
Deployment: Vercel

Copy-paste this into every AI session. No guessing allowed.

4. FRONTEND_GUIDELINES.md

Your complete design system.

Fonts, color palette with exact hex codes, spacing scale, layout rules, component styles, responsive breakpoints, UI library preferences.

Every visual decision locked down. AI references this for every component it creates. No more random colors or inconsistent spacing.

Example:

Colors:
- Primary: #3B82F6
- Background: #F9FAFB
- Text: #111827
- Border: #E5E7EB

Spacing Scale: 4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px

Typography:
- Font: Inter (Google Fonts)
- Headings: 32px, 24px, 20px (bold)
- Body: 16px (regular)
- Small: 14px (regular)

Border Radius: 8px (cards, buttons), 12px (modals)

Design Style: Glassmorphism with bento grid layouts

If you don't have this, every component will look different. Your app will look like five different people built it. Because functionally, that's what happened.

5. BACKEND_STRUCTURE.md

Database schema with every table, column, type, and relationship defined.

Authentication logic. API endpoint contracts. Storage rules. Edge cases.

If you're using Supabase, this doc contains the exact SQL structure. AI builds your backend against this blueprint, not its own assumptions.

Example:

Users Table:
- id (uuid, primary key)
- email (text, unique, not null)
- created_at (timestamp, default now())

Recipes Table:
- id (uuid, primary key)
- user_id (uuid, foreign key -> users.id)
- title (text, not null)
- ingredients (text[], not null)
- steps (text[], not null)
- photo_url (text)
- created_at (timestamp, default now())

Relationships:
- recipes.user_id references users.id (cascade on delete)

This is what separates apps that work from apps that break when you scale.

6. IMPLEMENTATION_PLAN.md

A step-by-step build sequence.

Not "build the app." More like:
Step 1.1: Initialize Next.js project
Step 1.2: Install dependencies from TECH_STACK.md
Step 1.3: Create folder structure
Step 2.1: Build navbar component per FRONTEND_GUIDELINES.md
Step 2.2: Build hero section
And so on.

The more steps, the less AI guesses. The less AI guesses, the fewer hallucinations.

Example:

Phase 1: Setup
1.1 Initialize Next.js 14.1.0 project
1.2 Install dependencies from TECH_STACK.md
1.3 Create folder structure (app/, components/, lib/)
1.4 Set up Tailwind CSS
1.5 Initialize Supabase project

Phase 2: Auth
2.1 Install and configure Clerk
2.2 Create /login and /signup pages per APP_FLOW.md
2.3 Add protected route middleware
2.4 Test auth flow end-to-end

Phase 3: Core Features
3.1 Build recipe creation form
3.2 Connect form to Supabase recipes table
3.3 Build recipe list page
...

You work through this sequentially. One step at a time. No jumping ahead.

The 2 Session Files (Your Persistence Layer)

These are different from the canonical docs. These keep AI aligned across sessions.

CLAUDE.md

This is the file AI reads first, automatically, every session.

It contains the rules, constraints, patterns, and context that every AI session must follow. Your tech stack summary. Your file naming conventions. Your component patterns. Your design system tokens. What's allowed and what's forbidden.

Think of it as the AI's operating manual for your specific project.

Example CLAUDE.md:

# Project: Recipe Sharing App

## Tech Stack
Next.js 14.1.0, TypeScript, Tailwind CSS, Supabase, Clerk

## Rules
- All components go in src/components/
- Use functional components with hooks
- Never use inline styles, always use Tailwind
- Mobile-first responsive approach
- Reference FRONTEND_GUIDELINES.md for all styling

## Design Tokens
- Primary: #3B82F6
- Background: #F9FAFB
- Spacing: multiples of 4px (4, 8, 12, 16, 24, 32, 48, 64)

## References
Read these docs before building:
- PRD.md for requirements
- APP_FLOW.md for navigation
- TECH_STACK.md for dependencies
- FRONTEND_GUIDELINES.md for styling
- BACKEND_STRUCTURE.md for database
- IMPLEMENTATION_PLAN.md for build sequence

## Session Protocol
1. Read progress.txt at start of every session
2. Update progress.txt after completing any feature
3. Review lessons.md for past corrections
4. Update lessons.md after every mistake

Claude Code reads this from your project root without you even asking. Cursor reads it if you point it to the file.

progress.txt

This is the file everyone misses.

It tracks what's been done, what's in progress, what's next. Every time you finish a feature, you update this file. Every time you start a new session, AI reads this file first.

Without it, every new session starts from zero context. With it, AI picks up exactly where you left off.

Example progress.txt:

COMPLETED:
- Project initialization (Next.js 14.1.0, all dependencies installed)
- Folder structure created
- Clerk auth configured (login, signup, Google OAuth working)
- Navbar component built per FRONTEND_GUIDELINES.md
- Recipe creation form (title, ingredients, steps, photo upload)
- Supabase recipes table created and connected

IN PROGRESS:
- Recipe list page (/recipes)
- Currently working on grid layout, 3 columns desktop, 1 column mobile
- Need to fetch recipes from Supabase and display

NEXT:
- Recipe detail page (/recipes/[id])
- Edit recipe functionality
- Delete recipe with confirmation modal

KNOWN ISSUES:
- Photo upload works but needs loading state
- Mobile nav doesn't close after clicking link (low priority)

Update this religiously. After every feature. This is your external memory. The bridge between sessions.

The Interrogation System (Before You Write Anything)

Here's the move that changes everything.

Before you write your documentation, make AI tear your idea apart.

Use this prompt:

"Before writing any code, endlessly interrogate my idea in Planning mode only. Assume nothing. Ask questions until there are no assumptions left."

AI hallucinates when your clarity ends. So extend your clarity. Force AI to find the gaps in your thinking before it starts building on a broken foundation.

What AI should ask you:

• Who is this for?
• What's the core action a user takes?
• What happens when they complete that action?
• What data needs to be saved?
• What data needs to be displayed?
• What happens on error?
• What happens on success?
• Does this need a login?
• Does this need a database?
• Does this need to work on mobile?

If you can't answer these questions, you're not ready to build. Go answer them first.

Real example from when I was building Resiboko (a recipe app):

AI asked: "Who is this for?"
I said: "Home cooks who want to save and share recipes."

AI asked: "What's the core action?"
I said: "User creates a recipe with title, ingredients, steps, photo."

AI asked: "What happens after they create it?"
I said: "Recipe saves to their profile and shows up on a public feed."

AI asked: "What data gets saved?"
I said: "Recipe title, ingredients array, steps array, photo URL, author ID, timestamp."

AI asked: "What happens if photo upload fails?"
I paused. Didn't think about that.
I said: "Show error message, let them retry or skip photo."

AI asked: "Can users edit recipes after creating them?"
I said: "Yes. But only their own recipes."

AI asked: "What happens if someone tries to edit someone else's recipe?"
I said: "Show error, redirect to home."

See what just happened? Every answer became material for my documentation. The user description feeds my PRD. The data structure feeds my BACKEND_STRUCTURE. The flows feed my APP_FLOW. The error handling feeds everything.

Once the interrogation is complete, use this second prompt:

"Based on our interrogation, generate my canonical documentation files: PRD.md, APP_FLOW.md, TECH_STACK.md, FRONTEND_GUIDELINES.md, BACKEND_STRUCTURE.md, IMPLEMENTATION_PLAN.md. Use the answers from our conversation as the source material. Be specific and exhaustive. No ambiguity."

AI will draft all six docs from the interrogation output. You review them, correct anything vague, add anything missing, lock them as your source of truth.

The sequence:
Interrogation → Documentation → Code

Never skip these steps. I've tried. It doesn't work. You just end up rebuilding everything three times.

Why This Matters (The Thing I Wish Someone Told Me)

I lost three weeks on a project once because I skipped this.

I was building Nana Tech, a tool for AI-powered automation. I had the idea clear in my head. I started coding immediately. Told AI what to build as I went. Seemed fine.

Until I realized the database schema I built didn't support the features I actually needed. So I had to rebuild the schema. Which broke all the API endpoints. Which broke the frontend. Which broke my confidence.

I ended up deleting everything and starting over.

The second time, I wrote the docs first. All six. Plus CLAUDE.md and progress.txt.

Took me two days to write them. Felt slow. Felt boring. Felt like I wasn't "building."

But when I finally started coding? Paubos ang features. AI knew exactly what to build. No backtracking. No "wait, how should this work again?" Every component matched. Every page connected. Every feature shipped cleanly.

That two-day investment in documentation saved me three weeks of rebuild hell.

Documentation isn't extra work. It's the work. The code is just the translation.

Your Part 1 Checkpoint

If you made it this far, you're ahead of 90% of people trying to vibe code. Most people skim this and go back to praying for working code.

Don't be most people.

Here's what you need to do before moving to Part 2:

Practical Checkpoint:

Step 1: Pick an idea
Doesn't have to be big. Can be simple. A recipe app. A task tracker. A portfolio site. Just pick something you actually want to build.

Step 2: Run the interrogation
Open Claude or Cursor. Use the interrogation prompt. Let AI ask you everything. Answer honestly. If you don't know, say you don't know and figure it out.

Example: "I want to build a habit tracker app."
Let AI interrogate that idea until you have clear answers about users, data, features, flows, edge cases.

Step 3: Generate your 6 canonical docs
Use the doc generation prompt. Let AI create:

• [ ] PRD.md
• [ ] APP_FLOW.md
• [ ] TECH_STACK.md
• [ ] FRONTEND_GUIDELINES.md
• [ ] BACKEND_STRUCTURE.md
• [ ] IMPLEMENTATION_PLAN.md

Review each one. Edit where needed. Make them specific.

Step 4: Write CLAUDE.md
Summarize your tech stack, rules, design tokens, and reference your six docs. Keep it under one page. This is the file AI reads every session.

Step 5: Create progress.txt
Start with something simple:

COMPLETED:
- Idea interrogated
- All documentation written
- Ready to start building

NEXT:
- Initialize project per IMPLEMENTATION_PLAN.md step 1.1

Step 6: Initialize git
Run these commands in your terminal:

git init
git add .
git commit -m "Initial commit: documentation complete"

Push to GitHub. Now your docs are backed up.

If you have those six things checked off, you're ready for Part 2.

If you don't, stop here. Don't move forward. I'm serious. The system only works if you do the work.

In Part 2, we're going to learn the vocabulary. The actual words and concepts you need to describe what you're building. UI vs UX. Components. State. Layout. APIs. All of it explained simply enough that you'll finally understand what AI is talking about when it asks you questions.

Pero for now, do the checkpoint. Write the docs. Set up your foundation.

Because the best code you'll ever write starts with words, not syntax.

See you in Part 2.

— G

P.S. If you actually did the checkpoint, send me a message or tag me. I want to see what you're building. Walang judgment. Just genuinely curious what people create when they finally have a system that works.