The Vibe Code Bible in 10 seconds:

  • Docs before code.
  • Required docs/: 00–11 (overview, requirements, data, stack, design, components, build, phases, API, testing, deploy, checklist).
  • Default stack: Next.js + TS + Tailwind + Convex + Go + OpenAI/z.ai.
  • Lifecycle: Spark → Spec City → Scaffold → Thicken → Polish → Steward.
  • AI Builder Contract: you (AI) must help me fill docs/ before writing serious code, must keep code and docs in sync, and must not invent new core concepts in code without updating docs.

If my repo doesn't have a dense docs/ folder, we are not vibe coding yet.

Read the full Bible below ↓

The Vibe Code Bible

A docs-first canon for building with AI

0. How to use this

This is not a blog post. It's a workflow standard.

You use it in three ways:

  1. As a human
    Read once, skim often. Treat it as your "how I start projects" rulebook.

  2. As an AI contract
    Paste the AI Builder Contract section into ChatGPT, Cursor, Replit, etc.
    Do that before you ask it to build anything.

  3. As a scaffold template
    Copy the folder structures, prompts, and checklists into new repos.
    If your project doesn't have them, you're not done speccing.

1. What is "Vibe Coding"?

Vibe coding is not "ask the AI for code and hope".

Vibe coding = architect-first, docs-before-code, AI-amplified building.

You bring the vision, constraints, tastes, and weirdness.
AI brings speed, pattern recall, and implementation.

The core belief:

If AI doesn't know, it doesn't do.

If the architecture, entities, flows, and constraints are not written down,
the AI has to guess. Guessing is where chaos and junk repos come from.

2. The Vibe Rules

  1. Docs before code
    No serious project starts with a blank index.tsx.
    It starts with a dense docs/ tree.

  2. Architect first, AI second
    You decide what exists and why.
    AI decides how to implement it cleanly.

  3. One source of truth
    The spec in docs/ is the law.
    Code that disagrees with docs is wrong until the docs are updated.

  4. Greenfield only once
    The first build should be coherent enough that future work is migration, not reinvention.

  5. AI is a team, not a genie
    Treat AI as:

    • staff engineer
    • documentation goblin
    • test writer
    • UX copy helper
      …not as a magical product owner.

  6. No ghost routes, no dead functions
    Every route, component, and API in the docs must exist in code.
    Every major thing in code must be mentioned in docs.

3. Canonical Lifecycle

Every greenfield project follows the same six phases:

  1. Spark → Seed
    Turn a raw vibe into a sharp idea.

  2. Spec City (docs/)
    Build the documentation city: architecture, UX, data, API, testing, deploy.

  3. Scaffold
    Create the repo, folders, and empty modules that mirror docs.

  4. Thicken
    Implement core flows, connect backend, integrate AI.

  5. Polish & Ship
    Hardening, visual polish, error states, deployment.

  6. Stewardship
    Memory, migrations, second-brain behavior, and future docs.

If you're in phases 3–5 and docs are incomplete or drifting,
go back to phase 2 and fix them. That's the Bible talking.

4. Required docs/ Tree

For any serious project, you must have at least:

docs/
  00_PROJECT_OVERVIEW.md
  01_PRODUCT_REQUIREMENTS.md
  02_DATA_ARCHITECTURE.md
  03_TECHNICAL_STACK.md
  04_VISUAL_DESIGN_SYSTEM.md
  05_COMPONENT_SPECIFICATIONS.md
  06_BUILD_INSTRUCTIONS_LOCAL_IDE.md
  07_IMPLEMENTATION_PHASES.md
  08_API_AND_INTEGRATION.md
  09_TESTING_AND_QA.md
  10_DEPLOYMENT_AND_DEVOPS.md
  11_PRODUCTION_CHECKLIST.md

You can add more, but you don't delete these.

Rule of thumb: If a concept is important enough to argue about later, it deserves its own .md now.

5. Default Stack Canon (You Can Override)

The Bible has a default stack so examples are concrete. You may change it project-by-project, but choose intentionally.

Default:

  • Frontend – Next.js (App Router) + React + TypeScript
  • Styling – Tailwind + a component library (e.g. shadcn/ui)
  • Backend / Realtime / DB – Convex.dev
  • Services / CLIs – Go (Golang)
  • AI Providers – OpenAI and/or z.ai behind a provider adapter
  • Auth – Anything that gives you a stable userId (Clerk / NextAuth / Auth0)

If you swap something (e.g. Go → Rust, Convex → Supabase), you must write it down in 03_TECHNICAL_STACK.md before building.

6. The AI Builder Contract

This is the core text you paste into ChatGPT / Cursor / etc.

You are an AI build team (architect + staff engineer + tech writer).

We are using The Vibe Code Bible:
- Docs before code.
- The docs/ folder is the source of truth.
- No new core concepts are invented outside docs/.

Your rules:

1. Do not write production code until there is a populated docs/ tree with at least:
   - 00_PROJECT_OVERVIEW.md
   - 01_PRODUCT_REQUIREMENTS.md
   - 02_DATA_ARCHITECTURE.md
   - 03_TECHNICAL_STACK.md
   - 04_VISUAL_DESIGN_SYSTEM.md
   - 05_COMPONENT_SPECIFICATIONS.md
   - 06_BUILD_INSTRUCTIONS_LOCAL_IDE.md
   - 07_IMPLEMENTATION_PHASES.md
   - 08_API_AND_INTEGRATION.md
   - 09_TESTING_AND_QA.md
   - 10_DEPLOYMENT_AND_DEVOPS.md
   - 11_PRODUCTION_CHECKLIST.md

2. If any of those files are missing or clearly skeletal, your job is:
   - First: help me fill them out, asking for clarification when needed.
   - Only after that: start generating code.

3. Treat me as the architect.
   - I decide what we are building, who it's for, and hard constraints.
   - You propose structures, tradeoffs, and implementation details.
   - When something important is ambiguous, propose 2–3 options in docs/ instead of silently picking one.

4. Default stack (unless overridden in docs/):
   - Frontend: Next.js + React + TypeScript.
   - Backend: Convex.dev.
   - Services/CLIs: Go.
   - AI: OpenAI / z.ai behind a provider adapter layer.

5. Phased implementation:
   - Phase 0 – fill docs/.
   - Phase 1 – repo & folder scaffold matching docs/.
   - Phase 2 – core backend entities & flows.
   - Phase 3 – core UI routes & components.
   - Phase 4 – AI integration and advanced behavior.
   - Phase 5 – testing, hardening, deployment scripts.

6. No ghost routes or dead functions:
   - Every route / component / API mentioned in docs must exist in code.
   - Every major module in code must appear somewhere in docs.
   - If you need a new module, add it to docs and update the relevant spec file.

7. Self-document as you go:
   - When you make a meaningful design choice, update the appropriate docs/*.md.
   - Production code and docs must stay in sync.

You may generate code, config, and documentation, but you must obey the Bible:
docs first, then code, always in lockstep.

Keep this in docs/19_CURSOR_OR_BUILDER_BRIEFING.md (or similar) so you can copy-paste it easily.

7. Folder Structure Template

For full projects, the Bible suggests this skeleton:

your-project/
  docs/
    ... (Bible-required markdown files)
  apps/
    web/          # Next.js app
  packages/
    ui/           # shared components
    core/         # shared logic, types, scaffolder engines, etc.
  services/
    coreapi/      # Go microservices / CLIs if needed
  convex/         # if using Convex
    schema.ts
    *.ts
  scripts/
    dev.sh
    lint.sh
    test.sh
  README.md

The exact structure doesn't matter as much as the rule:

The repo layout must be explicitly described in docs/07_IMPLEMENTATION_PHASES.md or 02_DATA_ARCHITECTURE.md. No surprise folders.

8. Scaffolding Recipe (Idea → Docs → Build)

When you have a new idea:

Step 1 – Spark → Seed

Write a single paragraph about your idea in plain language:

  • What is it?
  • Who is it for?
  • What is the main outcome?

Then run this "Seed Distiller" prompt with your AI of choice:

Here is a raw idea paragraph.

Turn it into:
- A one-sentence product statement.
- Three user archetypes.
- A 'movie trailer' paragraph that explains the vibe.
- 3–5 hard constraints (e.g. bilingual, offline-first, mobile-first).

Do not write code. This is for 00_PROJECT_OVERVIEW.md.

Paste the result into 00_PROJECT_OVERVIEW.md.

Step 2 – Fill the Core Docs

Use AI, but police it:

  1. 01_PRODUCT_REQUIREMENTS.md

    • Features, non-goals, MVP vs later.

  2. 02_DATA_ARCHITECTURE.md

    • Entities, fields, relationships, example records.

  3. 03_TECHNICAL_STACK.md

    • Frontend, backend, storage, AI providers, infra.

  4. 04_VISUAL_DESIGN_SYSTEM.md

    • Colors, typography, layout, vibe words, example screens.

  5. 05_COMPONENT_SPECIFICATIONS.md

    • For each page: list components and props.

  6. 06_BUILD_INSTRUCTIONS_LOCAL_IDE.md

    • How to run locally (dev commands, env vars, tools).

  7. 07_IMPLEMENTATION_PHASES.md

    • Phase breakdown, with acceptance criteria per phase.

  8. 08_API_AND_INTEGRATION.md

    • Routes, request/response shapes, external services.

  9. 09_TESTING_AND_QA.md

    • Unit, integration, and manual testing plans.

  10. 10_DEPLOYMENT_AND_DEVOPS.md

    • Environments, CI/CD, deployment steps.

  11. 11_PRODUCTION_CHECKLIST.md

    • Checklist that must be true before you ship.

If any of these are half-baked, you are still in Spec City. Stay. Finish the city. Then build.

9. Quality Gates

9.1 Ready to Code (exit Spec City)

You can start serious coding when:

  • Every required doc exists and is non-empty.

  • You can answer, from docs alone:

    • What is this?
    • Who is it for?
    • What are the main flows?
    • What's the stack?
    • What entities exist?
    • How do I run it locally?

If you cannot, you're not done.

9.2 Ready to Launch

You can ship when every box in 11_PRODUCTION_CHECKLIST.md is checked, including at least:

  • Tests pass.
  • Errors handled (not white screens).
  • Basic logging in place.
  • Secrets are in env, not in repo.
  • README is clear enough that a stranger can get it running.

10. Quick Reference Cheatsheet

You can paste this into any chat as a mini-reminder:

The Vibe Code Bible, in one screen:

- Docs before code.
- Required docs/: 00–11 (overview, requirements, data, stack, design, components, build, phases, API, testing, deploy, checklist).
- Default stack: Next.js + TS + Tailwind + Convex + Go + OpenAI/z.ai.
- Lifecyle: Spark → Spec City → Scaffold → Thicken → Polish → Steward.
- AI Builder Contract: you (AI) must help me fill docs/ before writing serious code, must keep code and docs in sync, and must not invent new core concepts in code without updating docs.

If my repo doesn't have a dense docs/ folder, we are not vibe coding yet.

That's the Bible. Everything else is just implementation.