Share this
Table of Contents
- Quick Summary
- Key Takeaways
- What Exactly Is Vibe Coding?
- What Does the Data Say About AI-Generated Code?
- Enter Spec-Driven Development
- How Does Spec-Driven Development Work in Practice?
- A Simple Example: An OpenAPI Spec
- Vibe Coding vs. Spec-Driven Development: How Do They Compare?
- SKILLs & Structured AI Instructions: The Connective Tissue
- The Spec-Driven Pipeline: Putting It All Together
- Why This Matters for Network & Infrastructure Automation
- The Road Ahead
- Frequently Asked Questions
Quick Summary
Spec-driven development (SDD) is a methodology where a formal, machine-readable specification – such as an OpenAPI or AsyncAPI document – is written before any code. That spec becomes the single source of truth for code generation, testing, documentation, and AI agent guidance. Unlike vibe coding, which relies on ad-hoc prompts to generate code, SDD constrains what (and how) the AI can build, which dramatically reduces security vulnerabilities, technical debt, and hallucination risk.
Key Takeaways
- AI-generated code carries a 45% vulnerability rate and is 2.74x more likely to contain security flaws than human-written code (Veracode, CodeRabbit 2025)
- Developers using AI tools are actually 19% slower in practice, despite believing they’ll be 24% faster (METR RCT, 2025)
- Spec-driven development uses formal specifications (OpenAPI, AsyncAPI, JSON Schema) as the single source of truth – driving code generation, testing, docs, and AI agent behavior
- SKILLs and structured instruction files (CLAUDE.md, AGENTS.md) complement specs by telling AI agents how to build, not just what to build
- For network and infrastructure automation, where a misconfigured rule can mean a security incident, SDD isn’t optional – it’s essential
If you’ve spent any time in the developer ecosystem over the past year, you’ve probably heard the term vibe coding. It felt amazing right? Like strapping a rocket to your laptop and watching entire applications materialize out of thin air.
But then you try to maintain what you built. Or hand it to a teammate. Or take it beyond science experiment status. And that’s when the hangover kicks in.
The industry is having a collective reckoning right now. Fast Company called it “the vibe coding hangover.” Even Andrej Karpathy – the person who coined the term in the first place – quietly hand-coded his latest project after admitting that AI agents just didn’t cut it for anything beyond throwaway experiments. The person who told us to “forget that the code even exists” went back to writing code by hand.
That should tell us something.
Here’s the thing: the problem was never AI-assisted development. The problem was unstructured AI-assisted development. We handed powerful tools to smart people and said “go vibe” without giving those tools any architectural guardrails, any contracts to honor, or any specifications. Hindsight is 20/20 – what did we think was going to happen?
There’s a better way. It’s called spec-driven development, and it’s rapidly becoming the standard for how serious engineering teams work with AI. Let’s dig in.
What Exactly Is Vibe Coding?
Andrej Karpathy introduced the term on February 2, 2025, in a post on X that racked up over 4.5 million views. The idea is simple: describe what you want in natural language, let an LLM generate the code, and – crucially – accept the output without reviewing it. Don’t read the diffs. Don’t understand the internals. Just run it, see if it works, and iterate with more prompts if it doesn’t.
Vibe coding works beautifully for a certain category of work. Weekend prototypes. Personal utilities. The “software for one” use case where you’re building a quick tool for yourself and don’t care if the code is a mess. Collins Dictionary named it Word of the Year for 2025, and Y Combinator reported that 25% of their Winter 2025 startups had codebases that were 95% AI-generated.
The enthusiasm was real. But so were the consequences.
What Does the Data Say About AI-Generated Code?
When organizations started leaning heavily on unstructured AI code generation, the results were measurable – and uncomfortable. The data below is drawn from Veracode’s 2025 State of Software Security report and corroborating research from CodeRabbit and METR.
| Metric | Value | Source |
|---|---|---|
| AI-generated code with security vulnerabilities | 45% | Veracode 2025 |
| Java AI code failure rate | 70%+ | Veracode 2025 |
| AI code security vulns vs. human-written | 2.74x higher | CodeRabbit Dec 2025 |
| XSS protection failure rate in AI code | 86% | Veracode 2025 |
| Experienced devs slower with AI tools (actual) | 19% slower | METR RCT Jul 2025 |
| How much faster devs believed they were | 24% faster | METR RCT Jul 2025 |
| Code duplication increase (2020–2024) | ~4x | GitClear |
| Projected technical debt by 2027 | $1.5 trillion | Analyst estimates |
That METR randomized controlled trial deserves a second look. It was conducted with experienced open-source developers. They were actually 19% slower when using AI coding tools, despite believing beforehand that they’d be 24% faster. That’s a 43 percentage-point gap between perception and reality. We’re not just building fragile code – we’re doing it while convinced we’re moving faster.
Enter Spec-Driven Development
Spec-driven development (SDD) isn’t new. If you’ve ever written an OpenAPI spec before writing your API implementation, defined a Protobuf schema before building your gRPC service, or authored a JSON Schema before accepting user input – you’ve done spec-driven development. The concept predates AI-assisted coding by years. API-first design, contract-first development, design-first approaches – these are all branches of the same tree.
What’s changed is why it matters so much right now. In 2026, spec-driven development has found its moment because of AI. Here’s the core idea:
The Spec-Driven Principle: Write a formal, machine-readable specification first. That specification becomes the single source of truth that drives everything downstream: code generation, testing, documentation, validation, and – critically – AI agent guidance. The specification takes precedence over code. Code serves the spec, not the other way around.
GitHub’s Spec Kit project crystallized this thinking. Their manifesto states that the product requirements document isn’t a guide for implementation – it’s the source that generates implementation. Thoughtworks added SDD to their Technology Radar. AWS built an entire IDE around it (Kiro). The Linux Foundation now hosts both the OpenAPI and AsyncAPI specifications that underpin the approach.
If you’re a network engineer or infrastructure automation practitioner, this should feel familiar. We’ve been working this way for decades. An RFC defines a protocol before anyone implements it. A YANG model describes a network device’s configuration schema before a single CLI command is written. An Ansible role’s interface is defined before the tasks are authored. Specifications first, implementation second – that’s how network orchestration has always worked.
John Capobianco did a walk through of a SDD workflow using GitHub Spec Kit. Watch the demo →
How Does Spec-Driven Development Relate to API-First Design?
Spec-driven development and API-first design share the same core principle: define the contract before writing any implementation. API-first is effectively a subset of SDD focused specifically on web APIs – the interface is designed and agreed upon before a single line of server or client code is written. SDD extends that same discipline to the full software development lifecycle, applying it to schemas, event contracts, infrastructure workflows, and AI agent behavior – not just API endpoints.
How Does Spec-Driven Development Work in Practice?
The workflow has two variants depending on whether you’re using traditional tooling or AI agents, but both start in the same place: the spec.
Traditional SDD Workflow
- Define your specification (OpenAPI, AsyncAPI, JSON Schema, Protobuf)
- Validate it with linters like Spectral
- Generate server stubs, client SDKs, documentation, and mock servers (e.g. via OpenAPI Generator, which supports 40+ languages)
- Implement business logic inside the generated scaffolding
- Run contract tests to verify the implementation honors the spec
- When requirements change, update the spec first – then regenerate
AI-Assisted SDD Workflow
- Write your structured specification
- An AI agent reads the spec and generates an implementation plan, broken into discrete, reviewable tasks
- The agent tackles each task while you review, test, and validate
- When something needs to change, update the specification – never the generated code directly – and the agent regenerates from the updated source of truth
Thoughtworks’ Birgitta Böckeler describes three levels of maturity:
- Spec-first – write the spec, then use it during development
- Spec-anchored – keep the spec alive after initial development for ongoing evolution
- Spec-as-source – the spec is the only thing a human edits; all code is generated from it
That third level is where the most forward-thinking teams are headed.
A Simple Example: An OpenAPI Spec
Below is a minimal OpenAPI 3.0 specification for a task tracking API. This single file communicates the entire API contract – endpoints, methods, request/response shapes, validation rules, status codes – in a format that is simultaneously human-readable and machine-executable.
openapi: 3.0.3
info:
title: Task Tracker API
description: A simple task tracking API for demonstration
version: 1.0.0
paths:
/tasks:
get:
summary: List all tasks
operationId: listTasks
parameters:
- name: status
in: query
schema:
type: string
enum: [pending, in_progress, completed]
responses:
'200':
description: A list of tasks
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Task'
post:
summary: Create a new task
operationId: createTask
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewTask'
responses:
'201':
description: Task created
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
components:
schemas:
Task:
type: object
required: [id, title, status, created_at]
properties:
id:
type: string
format: uuid
title:
type: string
description:
type: string
status:
type: string
enum: [pending, in_progress, completed]
created_at:
type: string
format: date-time
NewTask:
type: object
required: [title]
properties:
title:
type: string
minLength: 1
maxLength: 200
description:
type: string
maxLength: 2000
status:
type: string
enum: [pending, in_progress, completed]
default: pending
From this single YAML file, you can generate a Go server with Gin routing, a Python client SDK, interactive API documentation, a mock server for frontend development, and contract tests – all before writing a single line of business logic. Hand this spec to an AI coding agent alongside a SKILL file defining your project’s conventions, and the agent has everything it needs to generate correct, spec-compliant code on the first pass. No vibes required.
Vibe Coding vs. Spec-Driven Development: How Do They Compare?
These aren’t competing religious factions. They occupy different points on a spectrum. But the differences matter enormously when you’re building software that has to work reliably at scale.
| Dimension | Vibe Coding | Spec-Driven Development |
|---|---|---|
| Speed to first prototype | Minutes to hours | Hours to days |
| Code quality | Unpredictable | Constrained by spec, verifiable |
| Security posture | 45% vulnerability rate | Contract-tested, lintable |
| Maintainability | “Black box” codebases | Spec serves as living docs |
| Team collaboration | Individual activity | Enables parallel development |
| AI guidance quality | Ephemeral prompts | Persistent, structured specs |
| Error handling | Copy-paste errors to AI | Automated contract testing |
| Enterprise readiness | Not production-grade | Built for governance |
| Scalability | Hits complexity ceiling | Designed for evolution |
| Skill requirement | Prompting ability | Architecture + spec writing |
The fundamental tension is output speed vs. outcome quality. Vibe coding gets you something fast. Spec-driven development gets you something right. For a weekend hack, speed wins. For a production system that manages network infrastructure across a multi-vendor enterprise environment? Right wins. Every time.
But doesn’t spec-driven development slow you down? It might seem that way at first glance. But consider: vibe coding’s speed is front-loaded. You ship fast, then spend weeks debugging, patching security holes, and rewriting when requirements change.
Spec-driven development invests time upfront in getting the contract right, then moves faster in every subsequent phase because the AI agent, the tests, the docs, and the mock servers all derive from the same source of truth.
It’s the tortoise and the hare, except the tortoise has an AI copilot.
SKILLs & Structured AI Instructions: The Connective Tissue
Specs tell the AI what to build. But how do you tell an AI agent how to build it – which patterns to follow, which conventions to honor, which mistakes to avoid? That’s where SKILLs and structured instruction files come in.
Over the past year, a new category of engineering artifact has emerged: persistent, versionable, shareable instruction files that live alongside your code and give AI agents the context they need to operate effectively. The ecosystem has converged on several formats:
| Tool | Instruction File | Format |
|---|---|---|
| Claude Code | CLAUDE.md | Markdown |
| OpenAI Codex | AGENTS.md | Markdown |
| GitHub Copilot | .github/copilot-instructions.md | Markdown + YAML |
| Cursor | .cursor/rules/*.mdc | Markdown Component |
| AWS Kiro | Steering files | Markdown |
| Agent Skills Standard | SKILL.md | YAML frontmatter + Markdown |
Two of these have reached industry-standard status. AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation (launched December 2025), with founding members including Anthropic, OpenAI, and Block. Think of it as a README for AI agents – project-wide instructions that any compliant agent can read and follow.
The Agent Skills Standard, originally developed by Anthropic and open-sourced in December 2025, takes a complementary approach. Skills are self-contained instruction packages that teach AI agents domain-specific workflows. They’re now adopted by OpenAI Codex, GitHub Copilot, Cursor, VS Code, Block’s Goose, and Spring AI.
The key design insight behind Skills is progressive disclosure: at startup, only skill names and descriptions are loaded (about 50 tokens per skill); when a skill is triggered, the full instructions load (500–5,000 tokens); scripts and reference files load only when needed. This solves the context window problem that plagues monolithic system prompts.
SKILLs and specs are complementary layers in the same pipeline.
The spec defines what to build. The SKILL defines how to build it. Together, they give an AI agent precise, persistent, validated context that ephemeral chat prompts can never match.
The Spec-Driven Pipeline: Putting It All Together
When you combine specs and SKILLs, you get a governed AI development pipeline:
Human Intent → Specifications (OpenAPI, JSON Schema, AsyncAPI) → Instruction Files (CLAUDE.md, AGENTS.md, SKILL.md) → AI Agent → Validated, Spec-Compliant Code
Each layer narrows the AI’s degrees of freedom. Specs constrain what the code must do – endpoints, schemas, contracts. Instruction files constrain how the code should be written – patterns, conventions, guardrails. Validation ensures the output actually conforms to both. There’s no ambiguity, no hallucination risk on structural decisions, and no “I just trusted the vibes” moments in your production codebase.
One source I encountered in researching this post summed it up well: feeding structured specifications to LLMs eliminates ambiguity and sends a precise description to the model, which dramatically reduces the risk of hallucinations and bugs.
That’s the entire argument in one sentence.
Why This Matters for Network & Infrastructure Automation
If you’re reading the Itential blog, you probably work in network engineering, infrastructure automation, or platform operations. And this is where spec-driven development isn’t just a good idea – it’s essential.
Network automation challenges are most acute in the highest-stakes environments in enterprise IT. A misconfigured firewall rule doesn’t just create a bad user experience – it creates a network security automation incident. A routing change that isn’t validated against the intended state can take down production traffic. An API that doesn’t honor its contract can break integrations across dozens of upstream and downstream systems.
This is exactly why Itential’s approach to infrastructure orchestration has always been contract-driven. When you define a workflow in the Itential Platform, you’re describing a specification of intent: which systems to touch, in what order, with what parameters, and what validation must pass before proceeding. There are network automation use cases across virtually every domain of enterprise IT where this contract-driven approach proves its value. When you expose that workflow through the Itential MCP Server, you’re publishing a machine-readable contract that AI agents and upstream systems can discover and invoke with precise, schema-validated inputs.
Spec-driven development isn’t a new paradigm for infrastructure teams. It’s a formalization of what we’ve been doing all along.
The difference now is that the specs aren’t just consumed by humans and traditional tools – they’re consumed by AI-driven automation agents that can generate, validate, and execute automation at a pace we’ve never seen before.
The Road Ahead
The industry is converging on something important. Karpathy moved from “vibe coding” to “agentic engineering.” GitHub built Spec Kit. AWS built Kiro. Anthropic and OpenAI collaboratively built the Agent Skills Standard. The Linux Foundation is hosting the governance infrastructure. Thoughtworks added spec-driven development to their Technology Radar.
These aren’t isolated signals. They represent a collective realization that AI-assisted development is incredibly powerful, but only when the AI is working from structured, validated, persistent specifications rather than ephemeral chat prompts. The future isn’t choosing between AI and engineering discipline. It’s using both, together, where the human architects the intent and the AI executes it faithfully.
So go ahead and vibe code your weekend projects. I’ll probably do the same. But when you’re building something that has to work every time, across multi-vendor infrastructure, with audit trails and compliance requirements and a team that needs to understand what’s happening six months from now – write the spec first.
Your future self will thank you. And so will the AI agent.
Frequently Asked Questions
What is vibe coding?
Andrej Karpathy introduced the term in February 2025 to describe a style of AI-assisted development where you describe what you want in natural language, let an LLM generate the code, and accept the output without reviewing it. It works well for personal projects and weekend prototypes, but breaks down quickly when code needs to be maintained, handed off, or scaled.
What is spec-driven development?
Spec-driven development is a methodology where a formal, machine-readable specification – such as an OpenAPI, AsyncAPI, or JSON Schema document – is written before any implementation begins. That specification becomes the single source of truth that drives code generation, testing, documentation, and AI agent behavior throughout the development lifecycle.
How is spec-driven development different from vibe coding?
Vibe coding uses ad-hoc natural language prompts to generate code on the fly, prioritizing speed over structure. Spec-driven development constrains what the AI builds by providing a validated specification upfront. The result is code that is verifiable, maintainable, and significantly less likely to contain security vulnerabilities – at the cost of more upfront investment in the contract.
What specifications are used in spec-driven development?
The most common are OpenAPI (for REST APIs), AsyncAPI (for event-driven APIs), JSON Schema (for data validation), and Protobuf (for gRPC services). These formats are human-readable, machine-executable, and supported by a rich ecosystem of generators, linters, and testing tools.
Is spec-driven development slower than vibe coding?
Upfront, yes – writing a specification takes more time than generating code from a prompt. But vibe coding’s speed is front-loaded: teams often spend weeks debugging, patching security issues, and rewriting when requirements shift. Spec-driven development invests time in getting the contract right, then moves faster in every subsequent phase.
What’s the difference between TDD and SDD?
Test-driven development (TDD) defines expected behavior through unit tests before writing implementation code. Spec-driven development (SDD) operates at a higher level – defining the full API contract, schema, or system interface before any code is written. The two are complementary: SDD defines the contract, TDD validates the implementation against it.
What is GitHub Spec Kit?
GitHub Spec Kit is a project that operationalizes spec-driven development by treating the product requirements document as the source that generates implementation – not a guide for it. It’s one of several major industry signals (alongside AWS Kiro and Thoughtworks’ Technology Radar) that SDD has moved from a niche engineering practice to a mainstream discipline.
What is API-first development and how does it relate to SDD?
API-first development means designing the API contract before writing any server or client code – effectively a subset of spec-driven development focused on web APIs. SDD extends the same discipline across the full software development lifecycle, covering schemas, event contracts, infrastructure workflows, and AI agent behavior, not just API endpoints.
What are SKILL files and how do they relate to specs?
SKILL files are structured instruction packages that teach AI agents domain-specific workflows and conventions. Where a spec defines what to build, a SKILL file defines how to build it. Together, they form a governed AI development pipeline that produces consistent, spec-compliant code across an entire team.
Why is spec-driven development important for network automation?
In network automation, errors carry high stakes – a misconfigured firewall rule can cause a security incident, and a routing change that isn’t validated against intended state can take down production traffic. Spec-driven development ensures every automation workflow is defined by a validated contract, reducing the risk of unintended consequences when AI agents are generating or executing automation at scale.
William Collins
Director of Technical Evangelism ‐ Itential
William Collins is a strategic thinker and a catalyst for innovation, adept at navigating the complexities of both startups and large enterprises. With a career centered on scalable infrastructure design, he serves as Itential’s Director of Technical Evangelism. Here, he leads the charge in network automation, leveraging his deep roots in cloud architecture and network engineering. William hosts The Cloud Gambit Podcast, diving into cloud computing strategy, markets, and emerging trends with industry experts. Outside of transforming networks, you can find him enjoying time with family, playing ice hockey, and strumming guitar.
