Adrian's Vibe Engineering Build Framework

// When should you use Adrian's Vibe Engineering Build Framework?

Use this skill when starting or scaling a web app that is complex enough that a short prompt leaves out too much — specifically when the project involves multiple interconnected layers (scraping, AI analysis, database, UI) where a mistake in one step breaks everything after it. Also use it when you want the AI to do the planning work while you retain control of all key decisions.

// What do you need before starting a Vibe Engineering build?

• Product Definitionrequired
  A clear statement of what the app is, what it must do, and — critically — what it must NOT do (the out-of-scope list).
• Tech Stack Choicesrequired
  The specific libraries, services, and tools the project will use (e.g. Next.js, Supabase, Clerk, OxyLabs, Vercel AI SDK).
• Data Model with Hard Rulesrequired
  The schema for your core entities defined once, including mandatory fields an item must have before it can be saved (e.g. an article must have an image URL and published date).
• UI Reference or Design Spec
  A visual reference (image, Figma export, or design system spec) for each screen so the AI builds a cohesive UI rather than styling each screen independently.
• API Keys and Accountsrequired
  Pre-created accounts and API keys for every third-party service before the build starts, so the build is never paused to sign up for something.
• Build Orderrequired
  The intended sequence of features (e.g. design system → auth → database → scraping → AI analysis → vector search → scheduling), chosen to eliminate uncertainty at each step.

// What are the core principles behind Vibe Engineering?

// How do you apply Vibe Engineering step by step?

1. 1

   Create the agents.md file — the project's operating system

   Include: (1) AI role definition (e.g. 'principal-level full-stack engineer responsible for implementation quality, architecture, testing and security'), (2) the exact workflow steps the AI must follow, (3) a product description — what it is AND what it is NOT, (4) the out-of-scope list, (5) the data model with hard rules (mandatory fields an item must have before it can be saved), (6) layer separation rules (UI displays stored data only; UI must not scrape, analyze, or mutate pipeline state), (7) tool/service assignments (which tool owns which job), (8) likely environment variables, (9) the fallback rule as a numbered list. Add step 8 to the workflow: 'On approval, reread the approved prompt file in the prompts folder and implement it strictly. Implement only after user approval.' Do not overbuild this file — keep it clear so the AI knows what to do and what not to do.

2. 2

   Install official agent skills for every tool in the stack

   Run `npx skills add <tool-skills>` for each service. Install from the tool team's own documentation so the AI gets up-to-date, tool-specific guidance rather than plausible-but-dated code. Keep separate skill files for each tool (Clerk skill, Supabase skill, OxyLabs skill, Vercel AI SDK skill). The agents.md references which skills to use; the skills hold the how.

3. 3

   Pre-create all third-party accounts and API keys before writing a single prompt

   Every service account (auth, database, scraping, analytics, AI) must be ready before the build starts. Stopping mid-build to sign up for something kills momentum. Add all keys to your .env.local file immediately.

4. 4

   Establish the build order — sequence features to eliminate uncertainty

   Standard order for a full-stack AI app: design system → auth → database schema + data access → scraping pipeline → AI analysis pipeline → vector search → automation/scheduling. Each step's output is the next step's known input. Never build UI before knowing the data shape. Never build integrations before the database exists.

5. 5

   For each feature, write a short one-to-two sentence prompt referencing agents.md and the relevant skill

   Example: 'Implement clerk authentication using the clerk agent skills.' You do NOT write a long prompt. The agents.md provides project context; the skill provides tool knowledge. Neither needs to be restated in the prompt. Open a fresh chat window for each new feature to prevent context pollution.

6. 6

   Let the AI read, analyze, and generate the implementation prompt — answer any clarifying questions

   The AI will: read agents.md, read relevant skills, inspect existing code, identify what it does and doesn't know, then ask focused questions before writing the prompt (not mid-build). Answer questions about scope, data behavior, and protection rules. Do not skip this step — the question surfaces decisions that belong to you.

7. 7

   Review the saved implementation prompt file in the /prompts folder — approve or reject

   The prompt file must contain: goal (one sentence), skills to read, codebase to inspect, assumptions/decisions, exact list of files that will change, specific requirements, security rules (what is server-side, what the route rejects), acceptance criteria (type check, lint), and step-by-step verification instructions (exact curl commands, what to click, SQL to verify). You are reviewing the prompt, not the code. Catch problems here before they become features that need to be undone. If it misses pipeline rules from agents.md, reject it and say why.

8. 8

   Approve the prompt with a single word or letter — the AI rereads the prompt file and implements

   After your approval, the AI rereads the saved prompt file (not from memory) and implements strictly. This matters especially when starting a new session — without the explicit reread instruction in agents.md, the AI implements from a degraded context. Confirmation of this step: the AI runs available checks (lint, type-check, build) and returns exact manual test steps.

9. 9

   Verify the feature using the exact test steps the AI provided

   For API features: run the exact curl commands. For UI features: follow the exact click steps. For database migrations: run the provided SQL verification. For mobile: test responsively. Use corrective prompts (voice or text) for small fixes without a new approval cycle. For significant scope changes, restart the prompt-writing workflow.

10. 10

    Repeat steps 5–9 for the next feature in the build order

    The project changes every time; the way of working stays the same. Your everyday prompts stay short because the agents.md and skills make long prompts unnecessary. You are maintaining a file that makes long prompts unnecessary, not writing a long prompt for every feature.

// What does Vibe Engineering look like in practice?

// What mistakes should you avoid with Vibe Engineering?

• Writing long prompts for every feature instead of maintaining the agents.md and skills files that make long prompts unnecessary.
• Letting the AI add features that 'sound useful' (comments, bookmarks, notifications, recommendation engines) by not explicitly listing them in the out-of-scope section of agents.md.
• Approving or rejecting the implementation without checking whether the prompt reflects the pipeline rules and data model from agents.md.
• Building out of order — making UI decisions before the data shape is known, or building integrations before the database they depend on exists.
• Allowing the AI to make large independent decisions mid-build by not including the fallback rule in agents.md.
• Treating agents.md as a one-time setup rather than the living project operating system — forgetting to add step 8 ('on approval, reread the approved prompt file') so the AI implements from degraded memory instead of the saved file.
• Frontloading everything — writing nine markdown files and a full planning system before the project starts, doing most of the planning work yourself that the AI could have done.
• Starting a new session and approving a build without explicitly instructing the AI to reread the saved prompt file, causing it to implement from memory of what it wrote rather than the actual approved document.
• Defining the data model across multiple places instead of once in agents.md — leading to inconsistent validation in the scraper versus the UI versus the database.
• Skipping the showcase or verification step after each feature, allowing visual or functional regressions to compound across features.

// What are the key terms in Vibe Engineering?

Vibe Engineering

The methodology where you define your product, write your agents.md and skill files, and then let the AI draft its own implementation prompts for each feature. You approve those prompts, and the AI builds what it planned. You control the decisions; the AI does the planning work and the implementation.

agents.md

The project's operating system — a single file that tells the AI what the application is, how it should be built, which tools are allowed, the workflow it must follow, the data model with hard rules, the out-of-scope list, and the fallback rule. Written once, enforced everywhere. The AI must read this before every implementation.

Skill File

A dedicated file for one tool that holds up-to-date, tool-specific implementation guidance (e.g. the Clerk skill holds how to implement Clerk properly; the Supabase skill holds query patterns and row-level security). When a library updates, you update one skill file. When you start a new project with the same stack, you bring the skills and write a fresh agents.md.

Implementation Prompt

A specific markdown document the AI writes and saves to the /prompts folder before touching any file. Contains: goal (one sentence), skills to read, codebase to inspect, assumptions/decisions, exact files to change, specific requirements, security rules, acceptance criteria, and step-by-step verification instructions. It is the contract between you and the AI.

Out-of-Scope List

An explicit list inside agents.md of features that sound useful but are not part of the current plan. Must be named because AI agents will add unplanned features by default. If it's not listed as out, it will appear.

Data Model with Hard Rules

The schema for core entities defined once in agents.md, including mandatory fields an item must have before it can be saved. Written once, the AI enforces it in the scraper, in validation, and in every feature that touches that data.

Fallback Rule

A numbered list at the bottom of agents.md for situations the file doesn't explicitly cover: (1) build the smallest thing possible, (2) ask a focused question if unclear, (3) save a prompt and get approval, (4) implement it, (5) share the test steps. Prevents the AI from making large independent decisions in unanticipated situations.

Ask Before Assuming

The rule that when the AI encounters a decision the agents.md doesn't cover — something that could reasonably go two ways — it must ask before writing the implementation prompt, never mid-build. The decision is made by you at the right time, not by the AI in the wrong place.

Build in Order

The discipline of sequencing features so that each step's inputs are fully resolved before the next step begins. Not because anything technically prevents building out of order, but because the wrong order means building against uncertainty — making UI decisions before the data shape is known, or building integrations before their database dependencies exist.

Acceptance Criteria

Checks the AI commits to running after implementation, specified inside the implementation prompt before any code is written — type check, lint, build, and exact manual verification steps (curl commands for APIs, click paths for UI, SQL queries for database migrations).

// FREQUENTLY ASKED QUESTIONS