Skip to main content

Insight · September 26, 2026

The spec is
the source of truth.

Spec-driven development is the discipline that grew up around AI coding. Write what and why first. Let the code be the artifact.

01 · The shift

Vibe coding made everyone fast. Then the code drifted.

A model will write plausible code from a loose prompt in seconds. That is the appeal, and it is real. The problem shows up later. The code drifts from what you meant, invents interfaces that were never agreed, and decays as the project grows, because the only record of intent was a chat that scrolled away.

Spec-driven development is the answer that went mainstream in 2026. The move is simple to state and hard to overstate. You write a precise specification first, and you treat the code as something the spec generates rather than the thing you argue about. The intent stops living in a scrollback and starts living in a file.

02 · The definition

Define what and why before deciding how.

GitHub frames its Spec Kit toolkit around one line. Define what and why before deciding how to build it. That order is the whole method. A specification captures the behavior and the reason for it. A plan captures the technical approach. Tasks break the plan into work. Code comes last, and it is checked against the spec that produced it.

The point is not more documentation. Documentation lags behind code and no one trusts it. A spec in this method is the opposite. It sits ahead of the code and the code is expected to match it. When the behavior needs to change, you change the spec and regenerate, rather than patching output and hoping the description catches up.

The order is the whole trick. Deciding what and why before how forces the disagreement to surface while it is still cheap, in a sentence, rather than after a day of building on a wrong assumption. A model is good at the how and careless about the why, because it cannot read your mind. The spec is where you supply the part it cannot infer, once, in a place both of you can point at.

The one line to keep

“Specifications do not serve code. Code serves specifications.”

GitHub · Spec Kit

03 · The four moves

Specify, plan, tasks, implement.

01

Specify

Turn a rough intent into a written specification. What the feature does and why, in language a person and a model both read the same way.

02

Plan

The model maps the spec to a technical approach. Stack, architecture, and the decisions that would otherwise be guessed at mid build.

03

Tasks

The plan breaks into discrete, trackable work items, each one small enough for an agent to pick up and finish on its own.

04

Implement

Only now does code get written, task by task, checked against the spec that produced it rather than against a memory of a chat.

GitHub adds a constitution step once per project, a short set of principles the agent holds to across every feature, then runs the four moves per feature and repeats implement and verify until the work converges on the spec. Different tools name the steps differently. The shape holds.

04 · A file, not a chat

The spec lives in the repo, next to the code.

The quiet shift is where the intent is kept. In prompt then hope, the requirement lives in chat history and disappears. In this method the spec is a plain file, reviewed and versioned like any other. OpenSpec, one of the open frameworks in this space, states the aim as human and AI align on specs before code gets written, and keeps its specs in plain Markdown with no special syntax required.

That choice does real work. A file can be read by a teammate, a reviewer, and a model. It can be branched. It carries into the next session so the agent does not start from zero. OpenSpec is built for existing codebases rather than only fresh ones, and reports working with more than thirty AI assistants, which is the practical tell that the spec, not any one tool, is the thing that lasts.

Review changes shape too. You are no longer reading a thousand lines of output you did not write, trying to reverse engineer the intent. You read the spec, which is short, and you trust the generation to follow it. The hard thinking moves to a document a person can actually hold in their head.

05 · One requirement, written to be testable

A spec is only useful if a machine can check it.

Amazon Kiro structures every feature as three files. A requirements file, a design file, and a tasks file. The requirements are written in a structured form called EARS, short for Easy Approach to Requirements Syntax, that turns a vague sentence into one a machine can test. Every requirement follows the same shape.

# requirements.md

WHEN a user submits a form with invalid data
THE SYSTEM SHALL display validation errors next to
the relevant fields.

Each line is one condition and one behavior, so the
task and the test both fall out of it. The design
file and the tasks file trace back to this line.

EARS notation · WHEN a condition · THE SYSTEM SHALL a behavior

The value is traceability. A requirement written this way maps cleanly to a task, and a task maps to a test. Kiro keeps the design file and the tasks file pointing back to the requirements file, so the three move together and none drifts alone. When the code fails a check, you can walk back to the exact line of the spec it came from, rather than guessing. That is the difference between a spec that documents and a spec that governs.

06 · When not to write one

A spec is overhead until the work is worth it.

A throwaway script or a one line change does not need a spec. If the whole job fits in a single prompt and you can eyeball the result, writing a specification first is slower for no gain. The method earns its cost on work that has many pieces, outlives one sitting, or will be handed to an agent to run without you watching each step.

The failure mode is a spec that is vague. If the requirement cannot be stated so a machine could check it, the generation has nothing firm to hit, and you are back to prompt then hope with extra ceremony. The skill is not writing more words. It is writing the few that pin the behavior down.

Treated well, the spec becomes the interface between a person and a model. The person owns intent. The model owns the typing. The review happens on the small artifact rather than the large one. That is why the method spread. It puts the human back in the one place judgment actually matters.

Closing

Write the spec. Let the code follow.

Take the next feature you would normally prompt your way through. Write what and why first, precisely enough that a test could check it. Then let the model plan, break it into tasks, and build. You will review a page instead of a pull request, and the code will finally match what you meant.

Donny Smith

Written by · September 26, 2026

· Founder & Executive Creative Director, Bttr.

Over the past 15 years, he has led creative teams and contributed to products used by millions of people worldwide, working with companies including Apple, Opendoor, JP Morgan, GE Aerospace, Pepsi, and Alterra Mountain Company.

LinkedIn

Sources · GitHub Spec Kit repository and its spec-driven method notes · OpenSpec framework repository · Amazon Kiro spec and EARS notation reference · read September 2026

Share this perspective

More insights

Adjacent perspectives.

What Is Synthetic Data

7 min read

What Is Synthetic Data

Synthetic data is artificially generated data that imitates the statistical shape of real data without containing any real records. A model or a simulator learns how a real dataset behaves, then produces new examples that keep its patterns. Teams reach for it when real data is scarce, private, or missing the rare case, and IBM frames it as a stand in for real data used mainly to train machine learning models. It is made by generative models such as GANs, by simulation, by statistical sampling, by oversampling a minority class, and by larger models writing training material for smaller ones, the way Microsoft trained its Phi family on filtered web data plus synthetic textbooks. The catch is real. A 2024 Nature paper named model collapse: train a model on its own output generation after generation and the rare tails of the distribution vanish first, until the output barely resembles the world it came from. A companion study found the collapse is not inevitable when synthetic data accumulates alongside real data rather than replacing it. The operator rule follows: generate to fill a gap, keep real data as the floor, and document how every synthetic set was made.

Bttr. Field Brief

The brief Bttr. writes for senior buyers.

Monthly. One signal worth your time on Brand Operating Systems, AI search visibility, and the infrastructure buildout. No filler.