00. Foundation & Setup — Vibe Coding Series

The first time I let an AI agent run completely unchecked was on a Friday evening. I had an idea for a small SaaS tool — task management for indie teams — and I thought: “Just describe everything to Claude Code and let it handle the rest.”

I pasted in a 400-word brief: auth, task CRUD, dashboard, invite members, email notifications. Then I went to make coffee.

When I came back, the agent had finished. The code looked decent. I ran it — the app started, the UI was smooth, login worked. I excitedly pushed it to staging.

By Monday, when I opened it back up to continue, everything started falling apart.

The “invite member” flow worked but didn’t send emails. The dashboard query had no pagination — if you had 1000 tasks, it loaded all of them into memory. Auth used JWT but had no refresh token logic. And worst of all: not a single test.

I spent nearly a week fixing things that should have been designed correctly from the start. Not because the AI wrote bad code — but because I had no framework for working with it.

That’s when I started building what I now call the Vibe Coding Framework.

---

Why You Need a Framework

“Vibe coding” — a term coined by Andrej Karpathy — describes a style of programming where you describe your intent in natural language and let AI handle the rest. It sounds appealing. And it actually works — but only when you know what you’re doing.

Vibe coding without structure looks like this:

• Vague feature description → AI generates code → run it → find bugs → fix → find new bugs → repeat
• After 2 weeks: messy codebase, no tests, nobody understands the flow, AI starts “forgetting” context
• Result: rewrite from scratch or abandon the project

Vibe coding with structure looks like this:

• Clear requirements → API contract first → small tasks with acceptance criteria → AI implements each task → human review checkpoint → tests pass → merge
• After 2 weeks: complete feature, with tests, with docs, AI still understands context because it’s being fed correctly

The difference isn’t in the tool or the model. It’s in the process.

This series is that process — distilled from real-world experience, not theory.

---

The 8 Phases of the Vibe Coding Framework

Here’s the full framework, from idea to production:

Each phase solves a specific problem I ran into when working with AI agents. You can read each article independently, but reading in order will show you why each phase sits where it does.

---

Example Project: TaskFlow

Throughout the series, I’ll use a real project to illustrate each phase: TaskFlow — a small SaaS task management tool for indie teams.

TaskFlow is complex enough to surface real problems, but not so large that it becomes a distraction:

• Auth: sign up, sign in, JWT + refresh token, invite members
• CRUD: create/edit/delete tasks, assign, set deadlines, tag
• Dashboard: task overview by status, filter, pagination
• Notifications: email when assigned a task or deadline is approaching

Stack: Next.js 15, Supabase (PostgreSQL + Auth), Resend (email), Vercel.

I chose this stack because it’s widely used, AI agents understand it well, and it’s “real” enough that the examples don’t feel contrived. You don’t need to use this exact stack — the framework works with any tech stack.

---

Foundation Setup

Before starting any phase, you need the right environment. Here’s what I consider non-negotiable:

1. Choose Your AI Agent

Two main options right now:

• Cursor: IDE-first, deeply integrated with VS Code, great for workflows with lots of simultaneous file editing. Use .cursorrules to define project context.
• Claude Code: CLI-first, strong for automation and scripting, great for backend-heavy workflows. Use CLAUDE.md to define project memory.

I use both depending on context — Cursor for UI work, Claude Code for backend and automation. But if you’re just starting out, pick one and stick with it.

2. Git Workflow

Commit frequently — after each task is complete, not after each feature. The reason: when AI goes off track (and it will), you need checkpoints to revert to.

The convention I use:

feat: add user authentication endpoint
fix: handle refresh token expiry edge case
chore: update CLAUDE.md with auth module context

Branch strategy: main → develop → feature/task-name. Each AI task runs on its own branch, merged into develop after human review.

3. Project Memory File

This is the most important thing most people skip.

AI agents have no memory between sessions. Every time you open a new chat, it starts from scratch. CLAUDE.md (or .cursorrules) is how you “teach” the AI about your project once, and use it indefinitely.

Here’s the template I use for TaskFlow:

# TaskFlow — Project Memory

## Stack
- Next.js 15 (App Router), TypeScript strict mode
- Supabase (PostgreSQL + Auth + Realtime)
- Resend for transactional email
- Deployed on Vercel

## Architecture
- /app: Next.js App Router pages
- /components: UI components (atomic design)
- /lib: business logic, utilities
- /lib/supabase: Supabase client + server helpers
- /types: TypeScript interfaces

## Coding Standards
- No `any` type — use proper TypeScript
- All async functions must handle errors explicitly
- API routes return { data, error } shape consistently
- Use Zod for all input validation

## Current Phase
Phase 1 — Requirements & Architecture
Last updated: [date]

## Key Decisions
- Using Supabase Auth (not custom JWT) for simplicity
- Row Level Security enabled on all tables
- Email via Resend, not Supabase built-in (better deliverability)

Update this file after each phase. This is the AI’s “source of truth” about your project.

---

Glossary

Terms that will appear throughout the series:

HITL (Human-in-the-Loop): A mandatory checkpoint requiring human review before proceeding. Not every step needs HITL — but critical ones (merging code, deploying, changing schema) always do.

Context rot: The phenomenon where an AI starts “forgetting” or misunderstanding context as a conversation grows too long. Signs: the AI starts repeating code that already exists, proposes solutions that contradict earlier decisions, or ignores constraints that were already established. Fix: reset the session, re-feed CLAUDE.md and the necessary context.

Ownership map: A document that defines which parts of the codebase are AI-implemented, which are human-implemented, and which require mandatory human review. Prevents the “nobody knows where this code came from” problem.

AI_CONTEXT.md: A context file specific to a module or feature, supplementing CLAUDE.md. For example: auth/AI_CONTEXT.md contains the auth module spec, data model, and specific constraints. The AI reads this file before implementing anything auth-related.

---

What’s Next

The next article dives into Phase 1: how to work with AI to analyze requirements, avoid the “building the wrong thing” trap, and lock in architecture before writing a single line of code. This is the phase most people skip — and that’s exactly why they spend weeks fixing things that shouldn’t have existed in the first place.

→ Article 01: Requirements, Analysis & Architecture