From Prompts to Specifications

In late 2024, a reasonably well-run engineering team might have kept a wiki page called something like the “Prompt Engineering Playbook” — a house style for phrasing instructions, a set of worked examples, a few tricks that seemed to help. By the middle of 2026, that page is more likely to be archived than updated. What replaced it, team after team, was not a sharper version of the same page. It was a different kind of artifact: a specification template, checked into the repository itself, that a coding agent reads and executes before it writes a line of code.

This is not a rebranding exercise, and treating it as one — new label, same practice, nothing to see — misses what actually happened. Something carried over intact from prompt engineering; something else was quietly retired. The question worth asking plainly, before the rest of this volume goes deep on the mechanics of specifications, is which was which, and whether the field settled it by evidence or by momentum.

The toolkit that outgrew its category

The clearest marker of the shift is a piece of open-source tooling, not a research paper. On September 2, 2025, GitHub open-sourced spec-kit, built around a specific and unambiguous claim: specifications should be written so they can “directly generate working implementations rather than just guiding them” — not prose for a human or a model to interpret loosely, but an artifact precise enough to execute. As of this writing, the repository sits at roughly 120,000 GitHub stars and 10,600 forks, and its maintainers claim compatibility with more than thirty different AI coding agents, CLI tools and IDE-based assistants alike. That is an unusual adoption curve for a methodology distributed as command-line scaffolding and markdown templates rather than a product.

GitHub was not alone, and the timing matters more than either announcement on its own. Six weeks earlier, on July 14, 2025, AWS shipped Kiro, an agentic IDE built on the same premise from a different direction: unstructured prompting gets a prototype working, then leaves behind exactly the undocumented assumptions that make it unmaintainable, while a structured requirements-and-design specification is what lets that prototype survive into production. Two well-resourced platform teams, working independently, converged on nearly the same architecture within two months of each other. That kind of convergence is harder to wave off as one vendor’s marketing than either announcement is by itself.

Spec-driven development was not the only place the field’s vocabulary moved away from the prompt as the unit of account that year. Weeks after GitHub’s launch, Anthropic’s own engineering team was formalizing “context engineering” as a distinct discipline from prompt phrasing — everything a session accumulates around an instruction, not the instruction itself, a shift this Library’s second volume treats in full. Two different vocabularies, from two different corners of the same industry, both concluding independently that the single well-phrased message was no longer where the leverage lived.

Neither toolkit is, on inspection, exotic. spec-kit is a command-line installer plus a set of slash commands and markdown templates layered onto an existing coding agent; Kiro is an IDE with a panel for requirements and design sitting next to the editor. What both are selling, more than any specific feature, is a default: a new project starts by writing a document, not by opening a chat window and typing a request. That default is cheap to adopt and easy to underestimate, which may be part of why it spread faster than any single technical claim in either announcement would predict on its own.

What prompt engineering actually was

None of this makes the earlier discipline wrong, and it is worth being precise about what prompt engineering actually covered rather than caricaturing it as a fad. A widely cited 2024 survey catalogued fifty-eight distinct prompting techniques — chain-of-thought framing, few-shot examples, explicit role assignment, output-format constraints — and the survey’s own scope statement is instructive: it bounds the field to the construction of a single instruction or query. That was real craft, and teams that were good at it produced measurably better output than teams that weren’t. The claim worth making here is narrower than “prompt engineering was wrong.” It is that the instruction stopped being the primary unit of engineering effort — the thing a team built training, review, and tooling around.

This is the same reframe the previous chapter opened with, extended one step further. Prompts are interfaces, not incantations — that was the point of insisting a prompt’s failure is usually an interface-design failure, not a phrasing failure. Spec-driven development takes that insistence and gives the interface a shape durable enough to survive past the session that wrote it: sections, a review step, a place in version control, a document later sessions can read instead of re-deriving from scratch.

What survived, what didn’t

Put concretely rather than declared from a podium, the inheritance looks like this. The craft prompt engineering taught — precision, worked examples, explicit constraints — did not become obsolete. It became a subset of a larger practice, aimed now at a specification instead of a single instruction. What did not survive was the assumption underneath the whole discipline: that one well-worded message was the artifact worth iterating on.

• Constitution — standing project principles a spec inherits rather than restates each time
• Specify — what to build and why, argued before any solution shape
• Plan — the technical approach chosen to satisfy the spec
• Tasks — the executable, agent-sized breakdown of the plan
• Clarify — the step where ambiguity in the spec gets resolved before code generation starts, not after

That is the vocabulary the field converged on for the artifact itself — the terms the next two chapters take apart in full. None of the five words describe a better prompt. They describe a document with sections, a review cycle, and a place to live after the session that wrote it ends.

The inversion, named

Put together, this is spec-driven development: writing a structured specification of intent, requirements, and constraints as the artifact that gets engineered, versioned, and reviewed, with code as one of its outputs — regeneratable, in principle, if the spec changes enough to warrant it. GitHub’s own framing states the inversion directly, describing a move from treating code as the source of truth to treating intent as the source of truth. Historical practice, on this account, prioritized code and treated the spec — where one existed at all — as a means to that code, disposable the moment the code shipped. Spec-driven development reverses which of the two is disposable.

An open bet, not a settled one

Whether specifications should behave this way — permanent, living, load-bearing — is a genuine methodological argument inside the field, not a question this chapter is entitled to resolve on its way past. Martin Fowler’s site published the most careful practitioner analysis of the movement in October 2025, examining Kiro, spec-kit, and Tessl side by side and finding that each ships one opinionated workflow rather than a general answer suited to most real projects. The analysis names three positions teams actually take in practice: specs discarded once the code exists, specs retained and evolved alongside the code, and specs kept as the permanent, primary artifact. It also raises an uncomfortable comparison — an earlier generation tried making formal models the primary artifact and code their disposable output, under the name model-driven development, and that movement is remembered mainly for the ways it went wrong.

Kiro and spec-kit each ship one opinionated workflow — and neither is likely to fit most real engineering problems as written.

On the Fowler/Böckeler survey of spec-driven tooling, October 2025

This chapter is not going to adjudicate that comparison. The tension between specs as durable infrastructure and specs as scaffolding that outlives its usefulness the moment code exists is real, contested among the people building these tools for a living, and it earns a full chapter of its own later in this volume rather than a paragraph here.

For a staff engineer deciding where to spend scarce standardization effort, the practical upshot sits above the tooling debate rather than inside it. It does not much matter yet whether a team adopts spec-kit, Kiro, or a homegrown template — the toolkits are young, and Fowler’s critique that each encodes one workflow is a fair description of all three. What matters is deciding, deliberately, whether the specification a session starts from is meant to outlive that session. That decision determines whether the next session — the next engineer, the next agent — inherits a document or starts from nothing, and it is worth making on purpose rather than by whatever the first project happened to do.

Where this volume goes from here

The rest of Volume III follows the shape the inversion implies. Chapter 3 takes the executable-artifact claim seriously and asks what actually makes a specification precise enough to generate an implementation rather than merely describe one, positioned against unstructured prompting. Chapter 4 examines the constitution — the standing project context a spec inherits instead of restating. Chapter 5 lays out the canonical phase structure the field converged on, spec-kit’s and Kiro’s versions included, and where the two diverge. Chapter 6 returns to the living-versus-disposable question raised above and gives it the argument it deserves, rather than the deferral it got here.