What is Spec-Driven Development?

Introduction

Spec-Driven Development (SDD) is a software engineering methodology where formal specifications are written before implementation begins, and those specifications remain the authoritative source of truth throughout the project lifecycle.

The concept is as old as software engineering itself. Formal methods researchers in the 1970s advocated for mathematical specifications before code. Over the decades, the practice evolved through API contracts, behavior-driven test suites, architecture decision records, and product requirement documents — each bringing structure to a different layer of the stack.

But in 2024 and 2025, something changed. AI coding agents — tools like Claude Code, GitHub Copilot, Cursor, and Windsurf — moved from autocomplete assistants to autonomous implementers capable of writing entire features, refactoring systems, and shipping code with minimal human intervention. And with that shift, SDD went from a discipline practiced by methodical teams to a practical necessity for anyone working with AI agents.

This is the story of Agentic SDD — Spec-Driven Development purpose-built for the era where your most prolific contributor isn't a person, but an AI.

The Problem Agentic SDD Solves

AI coding agents are remarkably capable at generating code. They can write functions, build components, set up databases, and wire together entire applications. But they face a fundamental challenge: they don't know what you're building.

Without structured context, every AI interaction starts from zero. You re-explain your stack, your patterns, your preferences, your product's purpose. The agent makes reasonable-sounding but often wrong assumptions — choosing the wrong framework, inventing a data model that contradicts your existing one, styling a component in a way that clashes with your design system.

This isn't an AI problem. It's the same communication infrastructure problem that has plagued software teams since the beginning — just with a new participant. When humans worked alone, misalignment happened between product managers, designers, and developers. Now it happens between humans and their AI agents.

Consider the typical AI-assisted workflow without specifications:

• You describe a feature in a chat prompt with partial context
• The agent interprets it, makes dozens of micro-decisions you didn't anticipate
• You review the output, correct the obvious mistakes, miss the subtle ones
• Three iterations later, you've spent more time steering the agent than you would have spent writing the code yourself

Agentic SDD solves this by giving AI agents what they actually need: persistent, structured context that defines your product's identity, technology choices, design language, engineering standards, system architecture, and feature requirements. With specs in place, the agent doesn't guess — it reads.

Traditional SDD: A Brief History

Before exploring how AI agents have transformed SDD, it's worth acknowledging the rich history of specification-driven approaches that laid the groundwork.

The idea that you should specify what software should do before building it has been around for decades. It has taken many forms, each targeting a different layer of the software stack and a different audience. These approaches established the core insight that agentic SDD builds upon: if you can't specify it clearly, you can't build it reliably — whether the builder is a human or an AI.

Notable Approaches

• OpenAPI / Swagger — The most successful traditional SDD framework. Defines RESTful APIs in a machine-readable format (YAML/JSON), enabling server stub generation, client SDK creation, interactive documentation, contract tests, and mock servers. Championed by API-first companies like Stripe and Twilio.
• Behavior-Driven Development (BDD) — Pioneered by Dan North, popularized by Cucumber, SpecFlow, and Behave. Uses natural-language Gherkin scenarios (Given/When/Then) as specifications that are simultaneously human-readable and machine-executable.
• Design by Contract (DbC) — Formalized by Bertrand Meyer in Eiffel. Embeds preconditions, postconditions, and invariants directly into code. Influenced modern type systems, Zod schemas, and Rust's ownership model.
• Model-Driven Development (MDD) — Uses formal models (UML diagrams, domain-specific languages, schema-first ORMs like Prisma) to describe system structure, then generates code from those models.
• Architecture Decision Records (ADRs) — Popularized by Michael Nygard. Lightweight documents capturing architectural decisions with context, rationale, and consequences. Solves the "why did we choose this?" problem six months later.
• PRDs & Product Specifications — The oldest form of software specification. From waterfall-era Word documents to modern lean formats in Linear, Notion, and Shape Up — defining what to build and why from the user's perspective.

Each of these approaches solved a real problem, but they shared a common limitation: they were designed for human-to-human communication. A developer reads the OpenAPI spec and writes the implementation. A QA engineer reads the Gherkin scenarios and validates behavior. The specification was a coordination artifact between people.

Agentic SDD changes the audience. The primary consumer of your specifications is no longer just your team — it's your AI agent. And that changes what specs need to contain, how they need to be structured, and how they need to evolve.

Why Agents Change Everything

Traditional SDD frameworks worked because humans are good at filling gaps. A developer reading an incomplete API spec can infer intent from context, ask a colleague, or make a reasonable judgment call. AI agents can't do this — or rather, they do it badly, hallucinating plausible-sounding answers that silently diverge from your intent.

This changes the requirements for specifications in several important ways:

Specs Must Be Comprehensive

An AI agent implementing a feature needs to know not just what to build, but which framework to use, what patterns to follow, how to name files, what the data model looks like, and what design tokens to apply. Traditional SDD frameworks each covered one slice. Agentic SDD needs to cover the full stack — product identity, visual design, technology choices, engineering standards, architecture, and feature requirements — all in one coherent system.

Specs Must Be Machine-Readable

An OpenAPI spec was machine-readable, but a PRD in Confluence wasn't. When your AI agent is the primary consumer, every spec needs to be in a format the agent can parse and act on. Structured Markdown, version-controlled alongside the code, has emerged as the lingua franca of agentic SDD — readable by both humans and LLMs, easy to diff, and natural to include in agent context windows.

Specs Must Be Living

Spec drift was always a problem, but with human developers it was a nuisance — the developer knew the code had changed even if the spec hadn't. With AI agents, stale specs are actively dangerous. An agent that reads an outdated architecture spec will generate code that contradicts your current system. Agentic SDD requires that specs evolve as part of every code change, not after.

Specs Replace Prompts

In the early days of AI-assisted coding, developers used increasingly elaborate prompts to steer their agents. "Use React with TypeScript, follow this naming convention, put files here, style it like this..." Agentic SDD recognizes that these prompts are just specifications scattered across chat sessions. The solution is obvious: write them down once, structure them properly, and let every agent interaction inherit the context automatically.

Core Principles

Agentic SDD inherits the timeless principles of traditional SDD, but reframes them for a world where AI is the implementer:

1. Specs Come First

Implementation follows specification. This is even more critical with AI agents — an agent without specs will generate something, but it won't be what you wanted. The spec is the steering wheel. Without it, you're a passenger.

2. Specs Are the Interface

In agentic development, specs are the primary interface between human intent and machine execution. When the spec and the code disagree, one of them needs to change — and the spec is the source of truth. If the implementation diverges, either the code is wrong or the spec needs to be updated intentionally.

3. Specs Are Structured for Agents

Specs use consistent formats — structured Markdown, YAML frontmatter, predictable section layouts — so AI agents can parse, reference, and act on them. A spec that a human can read but an agent can't process defeats the purpose.

4. Specs Are Living Documents

Specifications evolve alongside the software. Every code change that contradicts a spec triggers a spec update. This is the hardest discipline in SDD and the most important — stale specs are worse than no specs, because they actively mislead AI agents.

5. Specs Compound

Each spec builds persistent context that compounds across every AI interaction. Your first prompt with specs is more informed than your hundredth prompt without them. Over time, a well-maintained spec library becomes a massive productivity multiplier.

The Agentic SDD Workflow

The traditional SDD cycle of define-validate-implement-verify-evolve still applies, but the roles change when AI agents enter the picture:

1. Specify — Humans (often collaborating with AI) write the specifications. This might be a product profile, a feature PRD, a style guide, a technology stack definition, or an architecture document. The AI can help draft, but the human decides.
2. Review — Stakeholders review the specs. In agentic SDD, this is where you catch misalignment — before the agent writes a single line of code. It's dramatically cheaper to change a spec than to redirect an agent mid-implementation.
3. Implement — The AI agent reads the specs and builds the software. The agent has full context: what the product is, what technology to use, what patterns to follow, what the feature requires, and what it should look like. It doesn't guess.
4. Verify — Humans review the agent's output against the specs. Did it meet the acceptance criteria? Does it follow the architecture? Does it match the style guide? The spec is the rubric.
5. Sync — As the code evolves, specs are updated to reflect reality. The agent is instructed to update specs as part of implementation, keeping the system in sync. This is what makes specs "living."

The key difference from traditional SDD: the implement step is primarily executed by an AI agent, which makes the quality of the specify step the single biggest lever on the quality of the output.

Agentic SDD Tools

The rise of AI coding agents has spawned a new generation of SDD frameworks designed specifically for human-AI collaboration. These tools share a common insight: AI agents produce dramatically better code when guided by structured specifications rather than ad-hoc prompts. Here are the most prominent.

GitHub Spec Kit

Spec Kit is GitHub's open-source toolkit for spec-driven development, designed to bring structure to AI-assisted coding workflows. It provides a guided, multi-step process that turns a vague idea into a comprehensive specification, then into an implementation plan, and finally into actionable tasks for a coding agent.

The Spec Kit workflow follows three phases:

• Specify — Through iterative dialogue with AI, a rough idea becomes a comprehensive PRD with acceptance criteria. The AI asks clarifying questions, identifies edge cases, and helps define precise requirements.
• Plan — The specification is translated into a concrete implementation plan covering components, architecture, and dependencies.
• Tasks — The plan is broken into actionable tasks that a coding agent executes sequentially, building the project piece by piece.

Spec Kit supports a wide range of AI tools including GitHub Copilot, Claude Code, Gemini CLI, Cursor, and Windsurf. Its key strength is making specifications the central source of truth — when requirements change, you update the spec, regenerate the plan, and let the agent handle the rest.

Scope: End-to-end project scaffolding. Spec Kit excels at greenfield projects where you're building from scratch, guiding you from idea through implementation.

OpenSpec

OpenSpec, created by Fission AI, is a lightweight spec-driven framework for AI coding assistants. It's open source, requires no API keys or external services, and works with 20+ AI coding tools. Its distinguishing philosophy is that specs live in the repository alongside code, providing persistent context that survives across chat sessions and team changes.

OpenSpec organizes work around a propose-apply-archive workflow:

• Propose — Describe your intended change, and OpenSpec creates a complete change proposal including a proposal document, updated specs, a design document, and a task list.
• Apply — The coding agent implements the tasks defined in the proposal, with progress tracked as each task completes.
• Archive — Completed changes are archived with timestamps, and the canonical specs are updated to reflect the new state of the system.

A key concept in OpenSpec is the spec delta — each change captures what shifted in the system's requirements, making it easy for developers and reviewers to understand modifications at a high level without digging through code diffs.

Scope: Iterative feature development. OpenSpec is particularly well-suited for brownfield projects — existing codebases where you need to evolve specifications alongside ongoing development.

Kiro

Kiro, developed by Amazon Web Services, is an agentic AI IDE and CLI that embeds spec-driven development directly into the development environment. Rather than being a standalone spec framework you install, Kiro is a full IDE (based on VS Code) where spec-driven workflows are a first-class feature.

Kiro's approach to specifications has a distinctive feature: it uses EARS notation (Easy Approach to Requirements Syntax) to transform natural-language prompts into structured requirements with explicit constraints and acceptance criteria. When you describe a feature, Kiro generates formal requirements that remove ambiguity from the original prompt.

As an AWS product, Kiro integrates deeply with the AWS ecosystem — connecting to services like Amazon SageMaker and supporting MCP (Model Context Protocol) for accessing documentation, databases, and APIs during development.

Scope: Full IDE with integrated spec workflows. Kiro bundles the spec-driven process into the development tool itself rather than existing as a separate framework you add to your workflow.

Benefits of Agentic SDD

Teams that adopt spec-driven practices for AI-assisted development see compounding advantages:

AI Output Quality

The single biggest benefit. AI agents with structured specs generate code that actually fits your project — right framework, right patterns, right style, right architecture. Without specs, you get generic code that requires extensive rework. With specs, you get code that looks like your team wrote it.

Persistent Context

Every AI chat session starts with a blank slate. Specs give your agent persistent memory across sessions — your product's purpose, your technology choices, your design language, your engineering standards. You stop repeating yourself.

Reduced Rework

Finding a requirement error during spec review costs minutes. Finding it after an AI agent has implemented the wrong thing costs hours of untangling generated code. Specs shift discovery left, where the cost of change is lowest.

Parallel Agent Work

When specs define clear boundaries — feature requirements, architecture patterns, component interfaces — multiple AI agents (or multiple sessions) can work in parallel without stepping on each other. The spec is the coordination mechanism.

Better Onboarding

New team members — and new AI agents — can read the specs to understand the system. Its purpose, its architecture, its design decisions, its feature requirements. This is dramatically faster than piecing together understanding from code, comments, and oral history.

Human Oversight at Scale

As AI agents take on more implementation work, humans need to shift from writing code to directing and reviewing it. Specs are the natural control surface for this shift — you steer by specifying, and verify by reviewing against the spec.

Challenges & Trade-offs

Agentic SDD is not without costs. Understanding the trade-offs helps teams adopt it effectively.

Upfront Investment

Writing specifications takes time. For rapid prototyping, a quick hack, or exploratory work, the overhead may not be justified. Agentic SDD delivers the most value when the project will involve multiple AI interactions, when consistency matters, or when the cost of misalignment is high.

Spec Drift

The biggest risk in any SDD practice — specs that fall out of sync with reality. With AI agents, this is especially dangerous: an agent reading a stale spec will confidently generate code that contradicts your current system. The discipline of updating specs alongside code is non-negotiable.

Over-Specification

There's a tension between giving agents enough context and creating specs so detailed they become rigid. Specs that are too prescriptive leave no room for the agent's (often good) judgment. Specs that are too vague provide insufficient guidance. Finding the right level of detail is a skill that improves with practice.

Tooling Fragmentation

The agentic SDD space is young and moving fast. Different tools take different approaches — some are IDE-integrated, some are framework-agnostic, some focus on greenfield, others on brownfield. Teams need to evaluate which approach fits their workflow rather than adopting everything.

Where gspec Fits

gspec is one implementation of Agentic SDD, designed to give AI coding agents the full-stack context they need to build software that matches your intent.

What gspec Does Differently

Traditional SDD frameworks each targeted a single layer — OpenAPI for APIs, BDD for behavior, ADRs for decisions. Agentic SDD tools like Spec Kit and OpenSpec focus primarily on feature requirements and task planning. gspec takes a full-stack specification approach, covering the entire surface area of a product across multiple spec types:

• Product identity (profile) — who you're building for and why
• Visual design (style) — design tokens and component patterns
• Technology choices (stack) — frameworks, infrastructure, and rationale
• Engineering standards (practices) — coding conventions and workflows
• System architecture (architecture) — data models, APIs, project structure
• Feature requirements (features) — prioritized capabilities with acceptance criteria

This matters because an AI agent implementing a feature doesn't just need to know what to build — it needs to know how your team builds, what your product looks like, and where code should go. gspec provides all of that context in a single, coherent system.

How gspec Compares to Other Agentic SDD Tools

• vs. Spec Kit — GitHub's Spec Kit follows a linear specify-plan-tasks pipeline optimized for greenfield projects. gspec takes a modular approach with independent spec types that can be generated in any order and used independently. Spec Kit is more prescriptive about workflow; gspec is more flexible about which specs you need and when.
• vs. OpenSpec — OpenSpec organizes work around change proposals with spec deltas, tracking how each change modifies the system's requirements. gspec treats specs as living documents that are updated in place as the code evolves. OpenSpec provides better change-level traceability; gspec provides a cleaner current-state view of the full product specification.
• vs. Kiro — Kiro bundles spec-driven development into a full IDE, tightly coupled with the AWS ecosystem. gspec is tool-agnostic — it installs as slash commands into whichever AI coding tool you already use (Claude Code, Cursor, Copilot, and others). Kiro gives you a more integrated experience; gspec gives you more flexibility in your tool choices.

When to Use What

Agentic SDD tools are not mutually exclusive. The right choice depends on your team, your tools, and what problems you're solving:

• gspec for full-stack product specifications that give AI agents comprehensive project context
• Spec Kit for structured greenfield project scaffolding with GitHub Copilot
• OpenSpec for change-tracked spec evolution in brownfield codebases
• Kiro for an all-in-one IDE experience with deep AWS integration

You can also layer traditional SDD tools alongside agentic ones — OpenAPI for detailed API contracts, BDD for executable acceptance tests, ADRs for preserving architectural decision history. The important thing is that your AI agents have the structured context they need to build what you actually want.

If you're interested in trying gspec, check out the Getting Started guide or explore the full documentation.