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.

Written by · September 26, 2026

Donny Smith · ECD, Founder, 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.

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.

8 min read

How to Evaluate a RAG System

Evaluating a RAG system means scoring its two stages on their own, because a retrieval augmented generation answer is only as good as the passages behind it, and a wrong answer has two possible causes a single number cannot tell apart. Retrieval is measured before the model writes anything. The LlamaIndex evaluation guide scores a retriever with hit rate, the share of questions where the right passage lands in the top results, and mean reciprocal rank, which rewards ranking it high. Generation is measured given what was retrieved. Ragas, the open evaluation toolkit now maintained by VibrantLabs, splits the answer into claims and scores faithfulness as the share the retrieved context supports, then scores answer relevance by generating questions from the answer and comparing them to the real one. Read as two pairs, the four metrics locate the fault: high recall with low faithfulness is a generation problem, low recall with high faithfulness is a retrieval one. Anthropic showed the payoff in September 2024, cutting a retrieval failure rate measured by recall at 20 from 5.7 percent to 1.9 percent by adding context, keyword search, and reranking. And it is not a one time check. Models drift, documents go stale, so the teams that trust their systems run these scores on live traffic the way they run unit tests.

8 min read

What Is a Reasoning Model

A reasoning model is a large language model trained to work through a problem in steps before it answers, rather than reply in one pass. It spends extra computation at the moment you ask, called test-time compute, to write out a chain of thought and check its own work. Anthropic describes its extended thinking as letting the very same model give itself more time and effort rather than switching to a separate model, and reported that Claude 3.7 Sonnet reached 84.8% on the hard GPQA science set, with a 96.5% physics subscore, using parallel sampling at a 64K token thinking budget. The habit is trained, mostly by reward. DeepSeek showed in January 2025 that its R1 Zero model learned to reason purely through reinforcement learning with no supervised fine-tuning first, developing self checking and long chains of thought on its own, and shipped DeepSeek R1 under the MIT license at performance comparable to OpenAI o1. The cost is real, so the newest models add a dial. Claude Opus 4.5 hit its best score on SWE-bench Verified using 76% fewer output tokens at a medium effort. The skill is matching how hard the model thinks to how hard the task is.

8 min read

What Is Fine-Tuning

Fine-tuning is training a pre-trained model further on your own labeled examples so a behavior is set into its weights. It changes how a model acts, its tone, its format, its grip on a narrow task, rather than what facts it knows. Google frames the move as taking a general-purpose model and adapting it to your domain on a curated dataset of your own examples. The gains are measurable. When Anthropic opened fine-tuning for Claude 3 Haiku in Amazon Bedrock, a team fine-tuned it to moderate comments and lifted classification accuracy from 81.5% to 99.6% while cutting tokens per query by 85%. Lighter methods such as LoRA keep the base model frozen and train a small set of new weights beside it. The order that saves money is a plain prompt first, retrieval when the model lacks facts, fine-tuning only when it lacks the right behavior. A fact that changes is a retrieval problem. A behavior that drifts is a training problem.

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.