Frequently Asked Questions About Adrian's Vibe Engineering Build Framework
22 answers covering everything from basics to advanced usage.
// Basics
What does 'vibe engineering' actually mean?
Vibe Engineering is the methodology where you define your product, write your agents.md and skill files, 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 and implementation work. It's not vibe coding — it's structured delegation with an approval gate.
What is the fallback rule and why does it matter?
The fallback rule is 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. It stops the AI from making large independent decisions in unanticipated situations.
What is the 'ask before assuming' rule?
When the AI hits a decision 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 gets made by you at the right time, at the planning stage, not by the AI in the wrong place after code is already being written.
// How To
How do I set up an agents.md file from scratch?
Include nine things: an AI role definition, the exact workflow steps, a product description of what it is AND is not, the out-of-scope list, the data model with hard rules, layer separation rules, tool/service assignments, likely environment variables, and the fallback rule. Add a workflow step telling the AI to reread the approved prompt file on approval. Keep it clear — don't overbuild it.
How do I install skill files for my tools?
Run `npx skills add <tool-skills>` for each service, installing from the tool team's own documentation so the AI gets current, tool-specific guidance instead of plausible-but-dated code. Keep a separate skill file per tool — Clerk, Supabase, OxyLabs, Vercel AI SDK. agents.md references which skills to use; the skills hold the how.
How do I review an implementation prompt before approving it?
Read the saved prompt file in /prompts and check it reflects the pipeline rules and data model from agents.md. Confirm it lists the goal, skills to read, exact files to change, security rules, acceptance criteria, and verification steps. You're reviewing the plan, not code — catch problems here before they become features. If it misses pipeline rules, reject it and say why.
How do I keep a fresh chat from losing context between features?
Open a new chat window for each feature to prevent context pollution, and make sure agents.md contains the instruction: 'On approval, reread the approved prompt file in the prompts folder and implement it strictly.' Without that reread step, a new session implements from degraded memory of what it wrote rather than the actual approved document.
// Troubleshooting
The AI implemented from memory instead of the saved prompt — what went wrong?
Your agents.md is missing the explicit reread instruction. Add a workflow step: 'On approval, reread the approved prompt file in the prompts folder and implement it strictly.' This matters most when starting a new session — without it, the AI builds from a degraded context of what it remembers writing, not the exact approved contract in /prompts.
The AI keeps adding features I never asked for — how do I fix this?
Your out-of-scope list is incomplete. AI agents add features that sound useful by default. Explicitly name every one you don't want — comments, bookmarks, notifications, dashboards, recommendation engines — inside the out-of-scope section of agents.md. If it isn't listed as out, it will appear. This is a hard boundary, not a suggestion.
My validation is inconsistent between the scraper, the UI, and the database — why?
You've defined the data model in multiple places. Define it once in agents.md, including the mandatory fields an item must have before it can be saved. Written once, the AI enforces the same rule in the scraper, in validation, and in every feature that touches that data. Scattered definitions cause the inconsistency you're seeing.
The AI made a big architectural decision on its own mid-build — how do I prevent that?
You're missing the fallback rule in agents.md and the 'ask before assuming' discipline. Add the numbered fallback list so unanticipated situations default to building the smallest thing and asking a focused question. Combined with the approval gate, this ensures decisions that could go two ways come back to you at the planning stage, not during implementation.
My build stalled because I had to sign up for a service mid-way — how do I avoid this?
Pre-create every third-party account and API key before writing a single prompt — auth, database, scraping, analytics, AI. Add all keys to your .env.local immediately. Stopping mid-build to sign up for something kills momentum and pauses the AI. Every service must be ready before the build order begins.
// Comparisons
How does Vibe Engineering compare to vibe coding?
Vibe coding lets the AI make decisions and write code freely with minimal structure. Vibe Engineering keeps the loose, short-prompt feel but adds an approval gate: the AI must write a detailed implementation prompt and get your explicit approval before touching a file. You keep the speed of short prompts while retaining control of every key decision and catching problems before code exists.
How is agents.md different from a README or a spec document?
A README documents a finished project for humans; a spec is often written once and drifts. agents.md is a living operating system the AI reads before every implementation — enforcing the data model, out-of-scope list, and workflow on every feature. It's not documentation about the project; it's the executable contract that governs how the AI builds.
How does this compare to writing one giant planning document upfront?
Frontloading — writing nine markdown files and a full planning system before the project starts — makes you do the planning work the AI could have done. Vibe Engineering keeps agents.md lean and lets the AI draft each feature's detailed implementation prompt on demand. You provide the framework for thinking, not the answers, and review the AI's plans as they arrive.
Is Vibe Engineering better than just accepting AI code and fixing bugs after?
Yes, for complex multi-layer apps. Fixing bugs after means unwinding features that were built wrong, which cascades when one layer feeds another. Vibe Engineering catches problems at the prompt-review stage — before code exists — and ships with acceptance criteria and exact verification steps. You spend review time on plans, which is far cheaper than undoing built features.
// Advanced
How do I handle small fixes without a full approval cycle?
Use corrective prompts — voice or text — for small fixes without restarting the prompt-writing workflow. Reserve the full plan-and-approve cycle for significant scope changes. This keeps momentum on minor tweaks while still gating anything that meaningfully changes what's being built.
How do I add semantic search the Vibe Engineering way?
Write a short prompt referencing the Supabase skill. If agents.md designates PGVector as the vector tool, the AI writes an implementation prompt to enable pgvector, add an embedding column, generate embeddings per item with a model like text-embedding-small, store them, and expose a SQL function using cosine distance. You approve the prompt; it implements. Two differently-worded articles about the same event then surface as related.
What's the right build order for a full-stack AI app?
Design system → auth → database schema and 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 they depend on exists. The order eliminates building against uncertainty.
How do I keep skill files current when libraries update?
Because tool knowledge lives in dedicated skill files — one per tool — you update a single skill file when a library changes. agents.md stays untouched since it holds only project knowledge. When you start a new project with the same stack, you bring the updated skills and write a fresh agents.md. This separation is why the system scales across projects.
What are layer separation rules and why include them in agents.md?
Layer separation rules define what each layer may and may not do — for example, the UI displays stored data only and must never scrape, analyze, or mutate pipeline state. Putting them in agents.md ensures the AI never blurs responsibilities across features. It keeps the data pipeline authoritative and prevents the UI from becoming a side channel that corrupts state.
What should acceptance criteria include in an implementation prompt?
Acceptance criteria are checks the AI commits to running after implementation, specified before any code is written: type check, lint, build, plus exact manual verification steps. For APIs that's exact curl commands; for UI, exact click paths; for database migrations, SQL queries to confirm the change. The AI tells you how to confirm what it built before it builds it.