Day 5 · Lesson 1 — Spec-Driven Production Development
Vibe coding is not vibe-in-production. The spec is the asset now.
The capstone day opens with a role change: you step up from coder to technical architect. When the spec is rock-solid, the codebase becomes regenerable, even flippable from Python to JavaScript in an afternoon. That one shift reorganises everything about how you work.
From Day 1: what sits at the agentic-engineering end of the dial?
Formal specs. Day 5 is that end of the dial made into a daily practice: spec-driven development is agentic engineering, operationalised.
Developers were trained "code-first": vague idea → open editor → type until it works. Agentic AI inverts it. Most of your time now goes into high-quality specifications, the detailed instructions that tell the AI exactly what to build.1 The radical consequence:
Code is disposable. The spec is the asset.
With a solid spec, the whole codebase can be regenerated repeatedly, so there's no emotional attachment to code you didn't spend twelve hours debugging. Give the "brain" a vibe instead of a blueprint and it will guess, and in enterprise software, guessing is how "Rogue Agent" incidents happen.1
A good spec is an Architectural North Star, stored in a specs/ folder in
the repo, the source of truth for humans and AI. It prevents "context fragmentation": the game of
telephone where the AI loses the plot working from outdated file snapshots.1
A production-grade spec contains:
The author's tip: write the design in a doc, get humans to review it. You'd far rather a person catch a logic flaw in the design than after the AI has generated thousands of lines of broken code.
The sharpest tool for turning fuzzy intent into buildable precision is BDD, using
Gherkin's Scenario / Given / When / Then template. It forces the model to think in
State → Action → Outcome, which "completely eliminates vibe coding and keeps the agent
on a strict track."1
LLMs are startlingly sensitive to how instructions are formatted. A 2026 study found up to a
40% performance drop from generic Markdown. The winning strategy for Gemini is hybrid
Markdown + conditional YAML: Markdown headers to anchor narrative, YAML for structured
config nested deeper than 3 (YAML 51.9% parse accuracy vs JSON 43.1% vs XML 33.8%).1
Treat tokenization as a hard physical constraint: every character is budget and latency. A lean, compiled
specs/ folder keeps the agent on cost-efficient rails.
This reframes governance nicely: when code is regenerable, the spec (version-controlled in
specs/) is the durable source of truth, and therefore where policy and intent are
declared. That's the BIND phase from Day 2: the spec is where "what the agent may and
must do" is written down and reviewed. Human review of the design is a V
Validation gate placed before generation, and the versioned spec is an E
Evidence trail of intent.
Ladder read: a spec no one reviews is L1 vibe-in-production; a reviewed, versioned, BDD spec that agents build against is the L3 Controlled foundation the rest of Day 5 enforces.
Spend your time on the spec, not the syntax. Write it BDD-style (Given/When/Then), pin every version, and stop being attached to code you can regenerate from a good blueprint.
Put a specs/ folder in every repo as the shared source of truth, and review
the design before the code exists, catching logic flaws in the blueprint rather than in 2,000 generated lines.
Standardise a spec format (Markdown + conditional YAML) to dodge the 40% "format tax" and control token economics at scale. The spec folder is compiled instruction, not just documentation.
Recall, don't re-read.
In spec-driven development, the durable asset is —
Code is disposable, regenerable from a solid spec. The spec is the North Star and the source of truth for humans and AI alike.
BDD's Given/When/Then forces the model to think in —
State → Action → Outcome, a strict track that eliminates guessing. Gherkin turns fuzzy human intent into precise, buildable behaviour.
To avoid the "format tax" with Gemini, use —
Hybrid: Markdown headers anchor attention; YAML wins for structured/deeply-nested data (51.9% vs JSON 43.1%). Generic Markdown alone can cost up to 40% of performance.
Take a task you'd normally "just build" and instead write its spec first: Given/When/Then, schemas, versions, the "why." Then have a human read the spec before any code. If that feels slow, notice it's the exact place a logic flaw is cheapest to catch.
Boonstra, Spec-Driven Production Grade Development in the Age of Vibe Coding (Day 5) is the source; Gherkin is the BDD syntax reference.
Up next → Day 5 · Lesson 2: Where Instructions Live & Execution Modes. The hierarchy of where instructions actually go (chat, spec folder, skills, system prompts) and the five modes you switch between: Architect, Builder, Forensic Specialist, Author, Librarian.
Related: Day 1 L1: the dial · Day 1 L4: static/dynamic context · Course home