Spec-Driven Development: The End of Amateur Vibe Coding and the Dawn of Systems Engineering for UX

The concept of [[Vibe Coding]] is appealing. You write in natural language, AI spits out code, and you have a prototype in minutes. It works perfectly for a 100-line script. Try scaling that to a real product, and the system collapses.

I sat down with Ryan Edge to break down exactly how he’s using [[AI]] agents to build complex software. The consensus is clear: relying on chat interfaces to code has a glass ceiling. You lose context, the AI hallucinates, overwrites existing logic, and you end up doing manual work to correct a robot.

The solution isn’t asking the AI for less. The solution is giving it a deterministic contract. This is [[Spec-Driven Development]] (SDD).

This post is the exhaustive documentation on how to migrate from being a casual “vibe coder” to operating as a systems architect. If you’re a UX designer, you have an unfair advantage: you already think in states, flows, and rules. You just need to switch your medium from Figma to Markdown.

1. The Chat Trap and the Illusion of LLM Memory

[!warning] The GUI Problem “Chat isn’t a good interface for being in a flow state. It hurts productivity.”

Most people interact with AI through web windows (ChatGPT, Claude). This is inefficient for three technical reasons:

  1. Context window saturation: Large Language Models (LLMs) don’t have persistent memory. They have a token limit. When you spend days iterating on a project in the same chat window, the model starts to “forget” initial instructions. The result is the AI breaking features that were already working.
  2. Feedback loops going into flames: When an LLM loses context and generates bad code, it often tries to fix it by patching over the error. This creates a destructive loop where data goes from client to server, bounces off bad validations, and the app breaks in real-time.
  3. Copy-paste friction: Moving code from the browser to your editor breaks your flow state. AI-assisted development needs to happen where the code lives.

Chat forces you to be reactive. We need a proactive system.

spec driven design diagram

2. What is Spec-Driven Development (SDD)?

SDD is the antithesis of winging it. It is a framework where software behavior is exhaustively defined in a document before a single line of code is written.

In the pre-AI era, SDD was useful but tedious. Today, in the generative AI era, SDD is the operating system of development.

Instead of telling the AI: “Add a dark mode to the app.” You tell the AI: “Read the specs/dark-mode.md file. Analyze the state machine, respect the architectural rules, review the task checklist, and execute the plan.”

The “Spec” as external memory

A Spec (Specification) acts as a requirements document that lives directly in your codebase. It functions as the AI’s long-term memory.

[!info] SDD Memory Mechanics If you shut down your computer on Friday and return on Monday, a chat-based agent doesn’t know where you left off. An SDD agent reads the Spec, checks which tasks are marked with an [x], and resumes execution exactly where it stopped. The Spec is a progress database.

3. The UX Designer’s Advantage

If you’re a designer, traditional programming feels cryptic because it focuses on syntax. SDD doesn’t require you to write syntax. It requires you to structure logical systems.

Figma already taught you how to do this. Every time you build a complex prototype or a Design System, you are doing visual systems engineering.

The direct translation to understand SDD from a UX perspective:

  • Figma Variants -> State Machine: When you design a button in Default, Hover, Active, and Disabled states, you are defining an explicit state model. In SDD, you force the AI to declare these states before it attempts to paint the UI.
  • Figma Auto-Layout -> Rendering Rules: In UX, you define logical constraints (dynamic spacing, padding). In SDD, you translate this into responsive behavior requirements.
  • Figma Prototyping -> Event Bus / Routing: When you connect one screen to another with an arrow that says “On Click -> Navigate To”, you are defining data flow.
  • Design Tokens -> Global Variables: You understand that a primary color isn’t hardcoded ("#FF0000") every time. It’s referenced as a variable. In SDD, you order the AI to build using a centralized token architecture.

[!quote] “Every Figma design is telling a story of inputs, outputs, if/else statements, and conditional logic. We can map that into pseudo-code, it’s a language everyone in the business can understand.”

Junior developers panic when code doesn’t compile. A UX designer operating with SDD doesn’t care about the compilation error; they check the Spec to see if the logical instruction was ambiguous. You control the logic, the AI controls the syntax.

4. Spec Architecture: The 3-Layer Method

A system doesn’t use a single chaotic document. It uses a file architecture separated by purpose. In your repository (or documented here in your [[Obsidian]]), SDD is divided into three critical documents that you control.

Document 1: The Proposal

proposal.md This is the high-level context. If the AI agent doesn’t know why it’s building something, it will make the wrong architectural decisions.

Key components of a proposal:

  1. The Problem: (e.g., “The current system mixes legacy state logic with new patterns, creating technical debt”).
  2. The Goal: (e.g., “Migrate all screens in the settings flow to the new unified architecture”).
  3. Scope: What is in-scope and what is strictly off-limits.

Document 2: System Design

design.md This is the core of your work as a UX professional. Here you define the rules.

[!important] The Golden Rule of SDD NEVER include actual implementation code in your Spec. If you put real code (e.g., function toggleTheme() {...}), your Spec becomes obsolete the moment a human or agent updates the codebase.

Instead of code, you use Pseudo-code and BDD (Behavior-Driven Development).

BDD Example (Given-When-Then format):

## Scenario: State class generation
* **GIVEN** a state class is defined in the system.
* **WHEN** the code compiles.
* **THEN** the copyWith, equals, and toString methods are generated automatically.

This structure tells the AI exactly how the component should behave without dictating which specific library or syntax to use.

Document 3: Task Checklist

tasks.md The agent doesn’t read the design document and write everything at once. That exceeds its cognitive capabilities. The agent translates the design into a granular list of sequential tasks.

Task breakdown example:

## Phase 1: Setup
- [x] Define state constants.
- [ ] Configure dependency injection.

## Phase 2: Views
- [ ] Migrate the Header component to a pure function.
- [ ] Extract business logic to an independent controller.

This file is your dashboard. As the AI executes, you watch the boxes get checked off in real-time.

5. Execution Tools: Terminal Orchestration

Ditch the web interfaces. Professional AI-assisted dev happens in the Command Line Interface (CLI). Ryan and I discussed two core tools for this process:

A. Conductor (The Orchestrator)

Conductor is a Gemini CLI tool designed specifically for the SDD paradigm. It is not a chat. It is an execution engine.

Basic Conductor commands:

  1. conductor setup: Configures your project and understands the base architecture.
  2. conductor new track: This command reads your proposal and design files, and generates the execution plan (tasks.md). Everyone asks “How do I create a Spec?”. With this command, you pass your notes and the AI creates the technical structure.
  3. conductor implement: The start button. The agent reads tasks.md, picks the first incomplete task, analyzes your current codebase, implements the solution, and marks the task with an [x].

B. OpenCode (The Agent Interface)

OpenCode lives in your editor. It allows you to pull deep context from your code to the AI. The main feature of OpenCode is model flexibility.

You don’t need to be tied to OpenAI’s closed ecosystem. You can invoke different engines depending on the task via shortcuts.

6. LLM Economics: Token Routing for Efficiency

Using the world’s most powerful model to do repetitive tasks is burning cash. Ryan mentioned how the cost of poor token management destroys the ROI of using AI.

[!danger] The Long Context Penalty Models like Claude Opus double their price per token once you exceed the 200,000 token context window. If you pass your entire app to Opus just to change an error text, you are paying a massive inefficiency tax.

The solution: Model Routing via OpenRouter. OpenRouter is an API that aggregates dozens of models. The correct strategy is assigning models based on the cognitive complexity of the SDD phase:

  1. Architecture Phase (The Brain): To read the Proposal, generate the Design, and structure the Tasks.
    • Models: Claude Opus, GPT 5.2.
    • Why: They are slow and expensive, but their spatial and architectural reasoning capacity is superior. They draw the blueprint.
  2. Implementation Phase (The Muscle): To execute the mechanical tasks on the list, write boilerplate, and update the UI.
    • Models: Claude 3.5 Sonnet, Claude Haiku, Gemini Flash, or Chinese models like Kimi (Kimi costs a tiny fraction in comparison and has a massive context window).
    • Why: They just need to follow clear step-by-step instructions. They are cheap, ridiculously fast, and thanks to SDD, they don’t need to “think” about deep architecture, just implement the contract.

7. Team Workflow: Source of Truth

What does this look like in a real team where designers and developers collaborate?

  1. The Spec PR: Instead of starting to code (or asking the AI to code), the UX Designer / Product Manager creates the design.md file documenting data flow and conditional rules.
  2. Review (Spec Code Review): You submit this Markdown file as a Pull Request (PR) to the repo. The engineering team reads it. They discuss edge cases. “Hey, in this state, what happens if the server returns a 404?”. You fix the Spec, not the code.
  3. Approval & Merge: Once the entire team agrees, the PR is approved. This Spec becomes the single Source of Truth.
  4. Decentralized Execution: Once merged, anyone on the team—from a senior architect to a junior dev or yourself as a designer—can open the terminal, type conductor implement, and let their AI agent read the contract and build the app.

No friction. No ambiguous interpretations of your Figma design. The behavior is locked in by the Spec.

8. When to use SDD vs. When to use Chat (Triage)

SDD is a heavy system. You don’t use it for everything. You need to know when to trigger the bureaucracy and when to apply quick Vibe Coding.

Scenarios for Vibe Coding (Chat / Inline Prompt):

  • “Change the color of this button from blue to dark green.”
  • “Add 16px padding to this text container.”
  • “Fix this typo in the alert component.”
  • Rule: Isolated, purely visual changes with no logical ramifications.

Scenarios for Spec-Driven Development:

  • “Migrate the authentication system from Supabase to Firebase.”
  • “Implement a full 5-step onboarding flow with async validation.”
  • “Create a dark mode that saves state locally and listens to OS preferences.”
  • Rule: Any feature that would take you more than 1 day of manual work to code. Any change that touches multiple files and state layers.

Conclusion: Control the System, Not the Syntax

As an efficiency-focused designer, Spec-Driven Development is the bridge that closes the gap between visual design and the final deployed product.

Manual coding is becoming irrelevant. Treating AI like an intern you chat with is inefficient. The future of product development belongs to those who know how to write precise contracts.

By adopting SDD:

  1. You eliminate ambiguity in the handoff.
  2. You force the AI to follow your high logical standards.
  3. You become independent. With a clear Spec and a CLI orchestrator, you can build enterprise-grade systems without writing the underlying syntax.

Define the state. Document the flow. Configure the agent. And stop wasting time in the chat.

And of course don’t forget to follow Ryan Edge.

arrow_back Back to Blog