๐ก What is Vibe Coding? And Why Does It Constantly Veer Off Course?
In February of 2025, Andrej Karpathyโa founding member of OpenAI and former Director of AI at Teslaโposted a thought on X (Twitter) that sent ripples throughout the developer ecosystem:
“I don’t write code anymore. I just write prompts and review the output. I fully surrender to the vibes.”
Welcome to the era of Vibe Coding. Instead of manually typing out every line of code, developers (and even non-technical makers) now use natural language to tell an AI, “Build me an app with this vibe.” Recently, Y Combinator reported that 25% of startups in their latest batch have codebases that are over 95% AI-generated. The barrier to entry for building software has functionally vanished.
The Reality Check: The ‘Explosion of Technical Debt’
However, anyone who has seriously attempted Vibe Coding has likely fallen into its most notorious trap: The Explosion of Technical Debt.
Initially, the AI responds brilliantly, scaffolding your app in seconds. But as the project scales, the AI begins to suffer from amnesia (hitting the limits of its Context Window). It starts pulling in random libraries, overriding your strict architectural rules, and ultimately mangling the entire codebase (Hallucination). On Redditโs r/vibecoding community, a common sentiment is: “The AI tied my code in knots, and I spent the whole night trying to reverse-engineer its mistakes.”
Why does this happen? The AI’s short-term memory is severely limited. Over the course of hundreds of prompts, it simply forgets the foundational constraints and stylistic preferences you established at the beginning of the session.
The single, bulletproof method to solve this and ensure you actually ship your app to production is to stop relying on the AI’s internal memory. Instead, you must establish physical, unchanging Markdown documents within your project directory, forcing the AI to read them before taking any action.
Here is the underlying blueprintโthe ‘North Star’ 6-Document Markdown Frameworkโhighly praised by veteran AI developers to keep your LLMs rigorously on task.
๐ The 6-Document Markdown Framework for Vibe Coding Success
Create a `.vibe/` (or similar) folder at the root of your project directory and establish these six static files. (The templates below are cited completely intact for immediate real-world application, supplemented with beginner-friendly tips.)
1. [PLAN.md] – Business & Feature Scope (The Project Map)
Purpose: Defines “Where are we going?” for the entire development lifecycle. It prevents the AI from arbitrarily adding unnecessary features and throwing the ship off course. The most crucial element here is explicitly defining what is “Out of Scope.”
# ๐ฏ Project: [App Name Here]
## 1. Overview & Vision
- **Purpose**: [e.g., A productivity app that converts mobile voice ideas into structured development context and syncs them to the IDE.]
- **Core Value**: Prevents idea evaporation, maintains strict AI context, and removes psychological barriers to deployment.
## 2. User Journey
1. The user dictates: "Add Google social login to the auth page" into the mobile app.
2. The AI reads the existing `PLAN.md` and automatically appends a 'Google Login Implementation' step to `TODO.md`.
3. The modified guidelines sync instantly with the desktop Cursor IDE.
## 3. Feature Scope
### MVP (Phase 1 - Absolutely Non-Negotiable)
- [ ] Mobile input (Text/Voice) -> Markdown conversion engine.
- [ ] Local/Cloud file synchronization.
- [ ] Automated management of the 6-Document templates.
### Future Features (Phase 2 - Out of Scope)
- [ ] Model Context Protocol (MCP) server integration.
- [ ] Automated GitHub Commit linking (DO NOT attempt until Phase 1 is 100% complete).
## 4. Non-Functional Requirements
- **Speed**: IDE synchronization must happen within 5 seconds of mobile input.
- **Offline**: Save locally during network loss; sync immediately upon reconnection.2. [CONTEXT.md] – Tech Stack & Strict Rules
Purpose: The ultimate guardrail. It prevents the AI from “going rogue,” pulling in trending but unnecessary libraries, or writing convoluted spaghetti code. Set up your walls high and thick.
# ๐ง Engineering Context & Conventions
## 1. Tech Stack
- **Frontend**: Next.js 14 (App Router), TypeScript.
- **State Management**: Zustand (preferred for its lightweight, intuitive nature).
- **Styling**: Tailwind CSS + shadcn/ui.
- **Database**: Supabase (Auth + DB).
## 2. Development Principles
- **Clean Architecture**: Strictly separate business logic into `@/lib/services` and UI into `@/components`.
- **Type Safety**: The use of `any` is strictly prohibited. Validate all API responses using Zod schemas.
- **Server Components**: Default to React Server Components. Only use `use client` when interactivity explicitly demands it.
## 3. Specific Constraints
- **DO NOT** add external UI component libraries (like MUI) without explicitly asking me first.
- Only use `lucide-react` for icons.3. [TODO.md] – Milestone-Based Task Management (The Checklist)
Purpose: Breaks down the massive workload into ‘Atomic’ units. This prevents the AI from trying to digest too much at once, which leads directly to context overflow.
# โ
Task Backlog & Progress
## ๐ Phase 1: Foundation (In Progress)
- [x] Initial Next.js project setup and Supabase connection.
- [x] Basic layout and Global Navigation Bar (GNB).
- [/] 6-Document Editor UI implementation (80% complete).
- [x] Markdown preview functionality.
- [ ] Add real-time auto-save logic. (<- This is the precise target to assign to the AI right now)
## ๐ Phase 2: Core Logic (Queued)
- [ ] Design Mobile-to-Desktop data sync protocol.
- [ ] Build AI Prompt Engineering logic for parsing.
> **Tip:** Command the AI to resolve ONLY ONE checkbox at a time. Never give vague instructions like, "Go build Phase 2."4. [STYLE_GUIDE.md] – Personal Preferences (UI/UX)
Purpose: Eliminates the exhausting ping-pong game of telling the AI, “Make it darker, make the button bigger.” Document your exact vibe here once and for all.
# ๐จ Design System & Vibe
## 1. Visual Theme
- **Theme**: Dark Mode Only.
- **Colors**:
- Background: `#09090b` (Zinc-950)
- Primary: `#3b82f6` (Blue-500)
- Surface: `#18181b` (Zinc-900)
## 2. Typography
- **Font**: Inter (Google Fonts).
- **Size**: Heading (24px, Bold), Body (16px, Regular).
## 3. UI Patterns
- **Cards**: Border-radius 12px, subtle borders (`border-zinc-800`).
- **Feedback**: Add a subtle 0.98 scale animation on button clicks (use Framer Motion).
- **Loading**: Default to Skeleton UI instead of traditional loading spinners.5. [DEBUG_LOG.md] – The Correction Notebook (Issue History)
Purpose: Destroys the “Infinite Loop of Errors.” Document mistakes the AI has already fixed so it doesn’t accidentally revert to bad code right before deployment.
# ๐ Troubleshooting History
## [2026-03-05] Supabase Auth Session Issue
- **Issue**: Session data drops entirely upon browser refresh.
- **Root Cause**: Mismatch between Next.js Middleware and Supabase SSR configurations.
- **Resolution**: Switched to cookie-based authentication using `createServerComponentClient` instead of `createClientComponentClient`.
- **WARNING**: For all future Auth logic, refer strictly to `@/lib/supabase/server.ts`. Do not revert to the old client-side method under any circumstances.
## [2026-03-07] Mobile Sync Conflict
- **Issue**: Data overwriting during simultaneous Client/Server edits.
- **Resolution**: Implemented a Last-Modified (Timestamp) comparison check logic.6. [FLOW_SKETCH.md] – System Architecture & Data Flow
Purpose: Visualizes (via text) how data invisibly moves across your application. This prevents the AI from breaking the coupling between disparate components.
# ๐ Data & Logic Flow
## 1. Idea Input & Conversion Flow
1. [User] Inputs Voice/Text into the mobile app.
2. [App] Makes LLM API Call (Prompt: "Determine which of the 6 Document files this input belongs to").
3. [LLM] Returns JSON payload (`{ "target": "TODO", "content": "..." }`).
4. [App] Server parsing logic updates and saves the corresponding `.md` file.
## 2. Synchronization Flow
1. [App] Detects file changes -> Broadcasts via Supabase Realtime channel.
2. [IDE Plugin] Receives event -> Physically updates file in the local working directory on Desktop.
3. [AI IDE] The Cursor Editor compiler reads the updated file into Context, standing by to generate code.๐ Operational Guidelines: 3 Golden Rules for a Successful Finish
Merely dropping these files into a folder will not magically make your AI a senior developer. What truly matters is your prompting cycle (How you direct the AI). Memorize these three rules. We have included everyday examples so even total beginners can apply them immediately.
1. Sync First
The Rule: Before writing a single line of new code, update your documents (`TODO.md`, `PLAN.md`, `CONTEXT.md`) and force the AI to read them.
“I am about to code. Read these files entirely and brief me on your next assigned task.”
- Scenario A (Adding a new feature):
- Scenario B (Picking up where you left off in Cursor):
- The Technique: The key is making the AI parrot back your instructions: “Based on PLAN.md, my next task is to change the button color to blue.” This pre-emptively blocks the AI from hallucinating unassigned tasks.
2. Atomic Tasks (Break It Down)
The Rule: NEVER command the AI to build two or more features simultaneously. Once a single checklist item is completed, stop, perform a Git Commit (or backup), and then move on.
- Scenario A (Building large architectures):
- Scenario B (Solving complex errors):
- The Technique: Think in Save Points. Whenever a tiny feature works, `git commit` it or zip the folder. When the AI inevitably mangles the code, you can easily say, “Never mind, I’m rolling back to the code from 10 minutes ago.”
3. The Health Check (Critical Review)
The Rule: Periodically (at the end of a major phase or milestone), force the AI to perform a critical self-audit.
- Scenario A (Self-Audit post-feature completion):
- Scenario B (Refactoring and Cleanup):
- The Technique: Skipping this step leaves residual junk spread across your codebase, slowly forming ‘Spaghetti Code.’ Cluttered code rapidly deteriorates the AI’s contextual comprehension. Always provide the AI with a clean, blank slate before starting the next feature.
๐ Expanding the Framework: Advanced Use Cases
This 6-document architecture is not just for solo developers tinkering on weekends. Implementing this paradigm unlocks staggering levels of automation:
1. The ‘Idea Capture’ Mobile App (Vibe Dev-Sync) Imagine you’re walking or showering and a brilliant app feature hits you. You open your phone and dictate: “Add a multi-image upload feature to the bulletin board.” The backend LLM parses your voice, intelligently injects a new checklist item into `TODO.md`, and updates `PLAN.md` on your desktop at home. When you sit down at your PC, Cursor AI has already absorbed the new context and is waiting for your “Go” command. 2. Multi-Agent Workflow Orchestration With this folder structure, you can summon separate AI agentsโone dedicated strictly to Backend, one to Frontend. Instead of feeding them massive chat histories, you simply command them: “If your work overlaps, document your agreements in `FLOW_SKETCH.md`.” You effectively establish a digital development team that collaborates seamlessly. 3. Flawless Handoffs for Freelancing & Collaboration If you hire a human developer or invite a collaborator, ditch the 50-page PowerPoint slide deck. Just zip up these 6 Markdown templates and send them. They serve as an impeccable, comprehensive briefing that explains your intent, your hard limits, and your exact aesthetic vibe.
๐ Conclusion
Vibe Coding is not simply “talking to a chatbot and hoping for magic.” It is the refined art of directing and orchestrating an incredibly powerful, deeply enthusiastic, yet extremely forgetful intern.
These 6 Markdown Documents (.md) are the non-negotiable sticky notes you plaster on that intern’s desk every single morning. Implement this structural methodology today. You will stop abandoning half-finished projects and finally experience the profound satisfaction of actually deploying your ideas to the world.
๐ References & Recommended Reading
1. [Merriam-Webster: The Rise of ‘Vibe Coding’ in 2025](https://www.merriam-webster.com/wordplay/vibe-coding-meaning) – The linguistic origin and shifting LLM paradigms behind the Vibe Coding phenomenon.
2. [Andrej Karpathy on Twitter: Surrendering to the Vibes](https://twitter.com/karpathy) – The original thread by AI researcher Andrej Karpathy that ignited the Vibe Coding movement.
3. [Y Combinator: How Startups Are Adopting AI-Generated Codebases](https://www.ycombinator.com/blog/ai-code-generation-startups) – Recent insights into the adoption rates and technical debt risks of AI-generated codebases inside top startups.
4. [Anthropic Prompt Engineering Interactive Tutorial](https://github.com/anthropics/prompt-eng-interactive-tutorial) – A foundational guide on LLM behavioral patterns and maintaining context constraints.
5. [Cursor IDE Documentation: Context Rules](https://docs.cursor.com/context/rules) – Best practices for injecting global context (`.cursorrules`) effectively at the project level.
โ ๏ธ Important Disclaimer
1. Educational Purpose: All content, including code and strategies, is for educational and research purposes only. 2. No Financial Advice: This is not financial advice. I am not a financial advisor. 3. Risk Warning: Investing involves significant risk. Past performance does not guarantee future results. 4. Software Liability: Any tools or code provided are โas-isโ without warranty. Use at your own risk.