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.

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.

Plan

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

Tasks

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

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.

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.

7 min read

What Are Embeddings

A computer cannot read. It matches characters, so refund and get my money back look like strangers even though they mean the same thing. An embedding closes that gap. It turns a piece of text into a list of numbers that places its meaning at a single point in a large space, and puts text that means something similar nearby. OpenAI’s text-embedding-3-small returns 1,536 numbers per input and its larger model returns 3,072, and no one sets them by hand. The idea is older than the chatbot: Google published word2vec in 2013 and Stanford followed with GloVe in 2014, both trained on raw text with nothing labeled. Once meaning is a location, closeness becomes a number you can compute with cosine similarity, and that one move is the layer under semantic search, retrieval augmented generation, and recommendations. A token is not an embedding. Tokenizing tells you which pieces you have, embedding tells you what they mean.

8 min read

What Is a Vector Database

A relational database finds a row by matching it exactly. That breaks the moment the match is about meaning, because a refund article and a customer asking to get their money back share almost no words. A vector database closes that gap. It stores each document as an embedding, a list of numbers that places its meaning at a point in space, and answers a query by returning the records whose points sit closest, measured by cosine similarity, Euclidean distance, or dot product. To stay fast across billions of vectors it searches for the approximate nearest neighbor rather than the exact one, most often through the hierarchical navigable small world graph introduced by Malkov and Yashunin in 2016. This is the infrastructure under retrieval augmented generation and agent memory, and for most teams in 2026 pgvector on the Postgres they already run is the honest place to start.

7 min read

What Is a Context Window

A context window is the fixed span of text a model can hold at once, measured in tokens rather than words. Everything shares that one frame: the system prompt, the whole conversation, every tool definition, any document you attach, and the reply the model still has to fit. Anthropic calls it the model’s working memory, and its latest models hold up to one million tokens in a single request, with room for 128,000 tokens of output. A token averages about four characters. The catch is that a bigger window is not a longer memory. Accuracy falls as the window fills, so the real work is curating what goes in, not filling it.

View all insights →

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.

Intent first, code second

The spec is
the source of truth.

Vibe coding made everyone fast. Then the code drifted.

Define what and why before deciding how.