Spec-First Engineering: The Most Important Skill of the Decade
The most common failure mode we see in teams adopting agentic engineering is not a tooling failure. It is not a model failure. It is not even, most of the time, a discipline failure in the conventional sense – the teams are working hard, the engineers are skilled, the leadership is committed. The failure is upstream of all of that.
The teams are writing code before they have written a specification. Specifically, they are letting agents write code before they have written a specification. The result is the predictable mess: implementations that satisfy half the requirement and ignore the other half, downstream rework that exceeds the cost of the original implementation, regenerations that drift in different directions every time, and a senior engineer’s review queue that has become a search-and-rescue operation rather than a quality gate.
This is not a model problem. It is a workflow problem. The workflow that produces good agentic code is spec-first. The workflow that produces the mess is implementation-first. The difference is large and learnable, and the teams that learn it pull substantially ahead of the teams that do not.
What Spec-First Actually Means
Spec-first does not mean “write a long document before writing any code.” That misunderstanding has produced a generation of waterfall ghost stories that the industry has been recovering from since the eighties. Spec-first, in the agentic context, means something more specific and less heavy.
It means: before the agent is invoked, the human has written down – in a form precise enough to be checked against the resulting code – what the implementation is supposed to do, on what inputs, with what outputs, under what failure modes, with what side effects.
The form is not a 30-page requirements document. It is closer to a focused, structured set of statements. The shape varies by domain, but in practice the components we use most often are:
The problem. What the code is being written to do, in business terms, in one or two paragraphs.
The interface. The exact shape of the function, endpoint, or service: signatures, types, fields, expected inputs, expected outputs, in the language of the system being modified.
The contracts. The invariants the implementation must satisfy. Things like “the caller can assume the result is sorted” or “the function is idempotent on inputs of type X” or “a request with field Y missing must return error code Z.” These are the constraints the agent has to respect.
The side effects. Anything the code touches that is not in its return value – database writes, external API calls, log emissions, state mutations. Each side effect is named, scoped, and bounded.
The failure modes. What can go wrong, what the code should do when it does, and what the caller should observe in each failure case.
The verifications. The specific behaviors that, if observed in the implementation, demonstrate that the spec is satisfied. These often translate directly into tests, but they are not the tests themselves; they are the criteria from which tests are derived.
Done well, this fits on one to three pages for a typical feature. It can be written in fifteen to thirty minutes by a senior engineer who knows the system. It is not enormous. It is not waterfall. It is the artifact that makes the rest of the work tractable.
Why It Works
The spec, written before the agent runs, does three things that nothing else in the workflow does.
It carries the cognitive load. The senior engineer who would otherwise have written the implementation – and would have carried the implementation’s intent in their head as they typed – now externalizes that intent into the spec. The agent then has access to the same intent, in writing, that the human would have used implicitly. The cognitive substrate that used to live in the engineer’s head now lives on disk, and the agent gets to read it.
It defines the success criterion. The reviewer no longer has to guess what the implementation was supposed to do. The reviewer compares the implementation to the spec. Drift becomes detectable. “I think this does the wrong thing” becomes “the spec says X, the implementation does Y.” This makes review faster, more rigorous, and less subjective.
It survives regeneration. When the implementation needs to change – because of a bug, a new requirement, a shift in the underlying API – the spec is the durable artifact. The agent regenerates from the spec. The new implementation is consistent with the spec by construction. There is no archaeological exercise of reverse-engineering intent from old code.
These three effects compound. Each one alone would be useful. Together, they reshape the engineering workflow.
What Spec-First Is Not
There are several near-neighbors of spec-first that are not the same thing and do not produce the same results.
It is not prompt engineering. A well-engineered prompt is a separate thing – it is the wrapper that gets the model to do what you want. The spec is the description of what you want. A team that writes good prompts but does not write good specs is producing well-prompted code that does not match the actual intent of the work. The prompt is upstream of the model; the spec is upstream of the prompt.
It is not test-driven development. TDD writes the tests first and lets the tests stand in for the spec. This can work in narrow cases. It does not work for most agent-assisted development, because the tests do not carry the semantic load required to guide generation. Tests describe what the code does. Specs describe why. The agent needs the why.
It is not requirements gathering. Requirements gathering produces a document for human consumers – product managers, stakeholders, executives. Specs are written for the agent and the reviewer. They are more precise than typical requirements documents and less narrative. A requirements document can be the input to writing a spec, but it is not itself a spec.
It is not architecture documentation. Architecture documents describe systems at a level above the implementation. Specs describe implementations. The two are complementary; the architecture provides the context the spec lives inside, but the architecture does not constrain the implementation precisely enough to be agent-actionable.
Each of these confusions produces a familiar failure mode. Teams that conflate spec-first with prompt engineering produce sophisticated prompts against under-specified goals. Teams that conflate it with TDD produce well-tested code that does the wrong thing. Teams that conflate it with requirements gathering produce documents the agent cannot use. Teams that conflate it with architecture produce abstractions without implementations.
Spec-first is a different artifact, sitting in a different layer, doing a different job.
The Skill Itself
The skill of writing specifications well is not the same as the skill of writing code well. They are related, but they are distinct. We have observed engineers who are excellent at one and merely competent at the other, in both directions.
The strongest spec writers we have seen share a few characteristics.
They have deep working memory for systems. They can hold an entire workflow in their head, trace consequences across boundaries, and anticipate where things will go wrong. This is the same skill that distinguishes senior engineers in any era, but the spec writer has to externalize it in writing rather than expressing it through implementation choices.
They are precise with language. They notice ambiguity. They notice the difference between “the system should be reliable” and “the system should retry transient failures up to three times with exponential backoff before surfacing the failure to the caller.” The first sentence is a wish; the second is a specification. The skill of moving from the first to the second is the core of the discipline.
They are willing to declare success and failure conditions in advance. Many engineers find this uncomfortable. It commits them to a definition of success that can be measured against, which means they can be shown to be wrong. The spec writers who are not afraid of being shown wrong are the ones who produce the best specs, because they push past the discomfort and write the precise conditions.
They edit. A spec, like any other writing, gets better with editing. The first draft establishes the surface; the editing pass tightens the language, catches ambiguity, removes redundancy, and exposes the assumptions that were quietly carried in. Engineers who treat the spec as one-and-done produce specs that look complete and read poorly. Engineers who edit produce specs that hold up.
How Teams Adopt It
The teams that adopt spec-first effectively tend to do so deliberately, not gradually. The “we will write better specs over time” approach almost always slides back into implementation-first under deadline pressure, because writing a spec costs ten minutes of work that the team can see, while the downstream costs of not writing one are diffuse and arrive later.
A few practices that work.
Spec is a separate, named artifact in every PR. Not buried in the description. A file, in a known location, that exists before the code does and is reviewed alongside the code. The PR template enforces it.
Reviewers approve specs first, code second. A reviewer who sees the code first becomes biased toward what the code does. A reviewer who reads the spec first can evaluate the code against the spec. The ordering matters more than it sounds.
Specs are versioned. When a spec changes, the change is reviewable. The history of what was promised, when, and by whom is preserved. This is most important for any spec that produces production code that has to survive longer than a quarter.
Specs are short. A team that drifts toward 30-page specs has misunderstood the discipline. The spec is the minimum precise description necessary to constrain the implementation. If the spec is longer than the implementation, something has gone wrong – either the spec is over-engineered or the implementation should be larger than it is.
Specs are written by senior engineers and reviewed by other senior engineers. Spec writing is not a junior task. The skill of compressing a problem into a precise specification is the skill that distinguishes senior engineering. Delegating it downward produces low-quality specs that produce low-quality code, and the senior engineer ends up debugging both.
The Honest Statement
The teams that have learned spec-first engineering are pulling away from the teams that have not. The gap is not subtle. We have seen it in our own delivery, in the work of clients we advise, and in the published output of competitors we watch.
The good news: it is a learnable skill. The bad news: it is a learnable skill that requires deliberate practice, and the industry has not yet built the training infrastructure for it. Most engineers learn it by writing bad specs, watching them produce bad code, and improving incrementally. There is no canonical textbook. There is no canonical course. There is just the work.
Start writing specs. Start reviewing them. Start treating them as the durable artifact. The implementation will follow.
