The Beginning of Vibe Coding — 6 Mandatory MD Files

Introduction

Vibe coding is building software with AI as a pair programmer — you describe intent, the model writes code, and you steer. Without guardrails, that loop drifts fast: wrong libraries, inconsistent folders, half-finished features, and no shared source of truth.

The fix is simple. Before you prompt, scaffold six markdown files at the project root. They are not bureaucracy — they are the context window you cannot fit into a single chat. The AI reads them; you update them; the project stays coherent.

This guide walks through each file, what belongs inside, and when to create it.

The 6 Mandatory MD Files

1. PRD.md — Project Requirement Document

Full name: Project Requirement Document

This file answers what you are building. It is the contract between you, the AI, and future you.

What to include

What to build

• One-paragraph product summary
• Core problem the app solves
• Success criteria (e.g. "user can complete checkout in under 3 steps")

Target users

• Primary persona (role, skill level, context)
• Secondary personas if any
• What they need that existing tools do not provide

Features

• Must-have features (MVP)
• Nice-to-have features (post-MVP)
• Explicit non-goals — what you are not building

Example outline

# PRD — CartPulse
 
## What to build
 
A multi-store e-commerce marketplace with bilingual storefront and admin dashboards.
 
## Target users
 
- Shoppers who want one catalog across multiple verified stores
- Store admins who need inventory, orders, and KPI dashboards
 
## Features
 
### MVP
 
- Product catalog with search, filters, and pagination
- Redux cart with server-side price validation at checkout
- Stripe + Cash on Delivery payment flows
- Role-based admin panel (ADMIN, SUPER_ADMIN)
 
### Out of scope (v1)
 
- Mobile native apps
- Multi-currency support

2. Architecture.md

This file answers how the system is organized — flow, folders, and stack.

What to include

App flow & architecture

• High-level user journeys (e.g. browse → cart → checkout → order)
• Layer diagram: UI → API → service → data
• Auth model, state management approach, and external services

Folder & file structure

• Top-level tree with one-line descriptions per folder
• Naming conventions for components, hooks, and utilities
• Where new features should live

Tech stack

• Framework, language, styling, database, hosting
• Key libraries with why each was chosen
• Versions when they matter (e.g. Next.js 16, React 19)

Example outline

# Architecture
 
## App flow
 
Public storefront → Auth (NextAuth JWT) → Checkout service → Prisma/PostgreSQL
 
## Folder structure
 
src/
app/ # Next.js App Router pages
components/ # UI — common/, page/, layout/
lib/ # Server helpers and data access
constants/ # Static content
data/ # JSON content (projects, config)
 
## Tech stack
 
- Next.js 16 (App Router, SSG for content pages)
- React 19, TypeScript, Tailwind CSS 4
- Prisma 7 + PostgreSQL
- Deployed on Vercel

3. Rules.md

This file sets boundaries for the AI — what to use, what to avoid, and how to behave.

What to include

What to use

• Approved libraries and patterns (e.g. "use motion/react, not framer-motion")
• Code style: naming, file layout, import order
• Testing expectations if any

What to avoid

• Banned libraries or approaches (e.g. "no Redux unless already in the project")
• Error-handling rules (e.g. "fail loudly in dev, user-friendly messages in prod")
• Scope limits (e.g. "do not refactor unrelated files")

Boundaries for AI

• Never commit unless asked
• Never add dependencies without approval
• Match existing conventions before introducing new abstractions
• Minimize diff size — smallest correct change wins

Example outline

# Rules
 
## Use
 
- Tailwind utility classes; neo-brutalist design tokens from globals.css
- Server Components by default; `'use client'` only when needed
- `cn()` from @/utils/twMerge for conditional classes
 
## Avoid
 
- New UI libraries (no MUI, no Chakra)
- Over-abstracting one-off helpers
- Editing files outside the requested scope
 
## AI boundaries
 
- Read Architecture.md and PRD.md before implementing features
- Do not install packages without explicit approval
- Follow Phases.md — complete one phase before starting the next

4. Phases.md

Break the project into phases — small, shippable slices instead of one giant "build the app" prompt.

What to include

• Ordered list of phases with clear done criteria
• Dependencies between phases (e.g. auth before dashboard)
• What not to touch until a phase is complete

Example structure

# Phases
 
## Phase 1: Login
 
- [ ] Credentials + OAuth providers
- [ ] JWT session with NextAuth
- [ ] Protected route middleware
      **Done when:** user can sign in and reach a blank dashboard shell
 
## Phase 2: Dashboard
 
- [ ] KPI cards and charts
- [ ] Sidebar navigation
- [ ] Role-based menu items
      **Done when:** admin sees real data from seeded DB
 
## Phase 3: Catalog
 
- [ ] Product listing with filters
- [ ] Product detail page
- [ ] Search with URL-driven state
      **Done when:** shopper can browse 50+ products end-to-end

5. Design.md

Define the visual language before the AI invents a new theme on every screen.

What to include

Color & theme

• Primary, secondary, and accent palette (hex values)
• Light and dark mode tokens
• Background, surface, and border colors

Fonts

• Body font family and weights
• Display/heading font family
• Where each is applied

Typography

• Heading scale (h1–h6 sizes and weights)
• Body text size and line height
• Label, caption, and code styles

Example outline

# Design
 
## Color & theme
 
- neo-yellow: #ffe543 — CTAs, highlights
- neo-pink: #ff6b8b — accents, active states
- neo-cyan: #4ce2e2 — cards, hover states
- Background: #fffdf0 (light) / #1a1810 (dark)
- Borders: 4px solid black (light) / white (dark)
 
## Fonts
 
- Body: Lexend (300–800)
- Display: Space Grotesk (400–700)
 
## Typography
 
- h1: 3xl–5xl, extrabold, uppercase, font-display
- Body: base/lg, font-medium, leading-relaxed
- Labels: text-sm, font-black, uppercase, tracking-wide

6. Memory.md

Track what is done and what is in progress. The notebook note says this file is not needed at the very beginning — add it once coding starts.

What to include

What has been completed

• Finished phases and features with dates
• Decisions made (and why) so the AI does not re-debate them

Which file is currently being worked on

• Active file(s) and branch
• Current task in one sentence
• Blockers or open questions

Example outline

# Memory
 
## Completed
 
- 2026-07-10 — Phase 1 Login: NextAuth v5 with Google + GitHub OAuth
- 2026-07-12 — Phase 2 Dashboard: KPI cards wired to Prisma queries
 
## Currently working on
 
- File: `src/app/(admin)/orders/page.tsx`
- Task: Order status workflow with customer notifications
- Blocker: none
 
## Decisions
 
- Using repository/service layer — do not call Prisma from page components
- Bilingual routing via next-intl (en/bn) — all new pages need both locales

Recommended order of creation

1. PRD.md — lock the product scope
2. Architecture.md — lock structure and stack
3. Rules.md — lock AI behavior
4. Phases.md — lock delivery order
5. Design.md — lock visuals before UI prompts
6. Memory.md — start when the first line of code is written

Quick-start checklist

• PRD.md — what to build, target users, features
• Architecture.md — app flow, folder structure, tech stack
• Rules.md — what to use, what to avoid, AI boundaries
• Phases.md — Phase 1, Phase 2, … with done criteria
• Design.md — colors, fonts, typography
• Memory.md — completed work + current file (add when coding begins)

Summary

Vibe coding without documentation is vibe drifting. These six markdown files give you and the AI a shared brain:

Spend thirty minutes on the first five files before your first coding prompt. You will ship faster, review smaller diffs, and spend less time undoing AI decisions you never agreed to.