Spec-Driven Development: An Attempt at a Definition (Part 1 of 4)

#ai #agents #programming #specdriven

As I explained in the opening post of my series According to Plan: spec-driven development, spec-native systems, and whatever it all ends up being called, I am dissatisfied with the current lack of a definition of the term spec-driven development (SDD) that is recognized across the industry.

Since SDD's general approach to the problem domain and the reasoning behind it are compatible with how I think about software and systems as an architect, I see this approach as a promising solution space for how to create and maintain systems.

But before a solution space can be explored, its dimensions and boundaries must be properly defined. You need a solid foundation before you can build a house.

How can we get there?

Yet another definition of SDD

After more than 25 years of professional software engineering for various companies and projects, I am very familiar with the not-invented-here syndrome.

Therefore, my quest is primarily about reconciliation, not about deliberately reinventing the wheel. We already have a sufficiently large number of SDD definitions from industry-accepted sources at our disposal. The existing ambiguities stem both from various inconsistencies between these definitions and from the individual definitions themselves. At least to my taste, several of them are surprisingly short, do not address questions that immediately come to mind, and leave a lot to the reader's imagination.

I will try my best to bridge the gaps and fill in the details. Nothing I am about to say or do is intended to criticize or disparage the existing work or its authors. I might simply disagree as a professional and take things in a slightly different direction for the sake of clarity.

The only remaining problem is the following: to find common ground, you inevitably have to exclude. Not every variant of SDD conforming to at least one of the existing definitions will survive reconciliation. Something has got to give.

And so, strictly speaking, there is no way around ending up with yet another definition of SDD.

But at least it was invented here.

The quest

This post is the first part of a four-part series in which I attempt to arrive at a reconciled definition of SDD.

Instead of tackling spec-driven development straight away, I intend to dissect the term into its constituents, explore each one separately, and then put them back together again. Along the way, to make things more comprehensible (and hopefully more interesting), I will discuss options and considerations before arriving at a final definition.

To some readers, this might feel a bit too theoretical and detached from the realities on the ground. I am both an academic and a practitioner, so I understand where you are coming from. Of course, everyone is free to skip these supplementary bits and jump straight to the end results, which are visually highlighted as callouts. What I cannot do, however, is gloss over important details.

If you want a solid foundation, you have to dig deep enough.

What is a spec?

What struck me most when reading the existing definitions of SDD is the fact that they disagree even on something as fundamental as what a spec actually is. This observation is the reason why I decided to dissect the term SDD in the first place.

In an engineering context, spec is short for specification, and this term alone is already highly ambiguous. Specifications exist for various topics and on many different levels of detail. There are requirement specifications, functional specifications, and product specifications, to name just a few.

So, the real question is not what a specification is, but what the specification in the context of SDD is supposed to accomplish.

I will start with a collection of the most relevant statements about the nature of a spec from the sources of the SDD definitions mentioned in the opening post:

The following key properties of an SDD spec can be distilled from this:

A spec is written in natural language.
A spec defines testable behavior; it is about the "what", not the "how", not the "why".
A spec is executable in the sense that an AI coding agent is able to translate it to source code such that the execution of the resulting binary exhibits the specified behavior.
A spec prescribes; it does not describe.
A spec is long-lived.

With this in hand, we can dive deeper and define the term spec in the context of SDD more formally.

In part 2, I will do exactly that, starting with what a spec is made of: its format and its language.