Intent Is Upstream of the Spec

Intent Is Upstream of the Spec

Intent-Driven Engineering

Spec-driven engineering asks what the software should do. Intent-driven engineering asks why — and that difference changes everything an agent builds.

Mark Kendall · Intent-Driven Engineering

Spec-driven engineering usually starts with a question: what should the software do? It’s a good question. It produces acceptance criteria, interfaces, edge cases, test plans. Most of modern software engineering discipline is built on getting better at answering it.

Intent-driven engineering starts one level higher: why are we building software to do this in the first place?

Spec vs. Intent

Spec

What should the software do?

Intent

Why are we building software to do this, what context governs it, and how will we know it’s safe to deliver?

That shift matters more than it looks like on the page. A spec can describe a feature completely and still be building the wrong thing. Intent is where the business reason lives, the enterprise context, the constraints nobody wrote down, the evidence required before it ships, and the delivery decision behind all of it.

Why this matters now

This distinction was always true. It’s urgent now because of what’s changed: agents build fast. An agent handed a clean spec and no intent will produce a clean, well-tested, entirely wrong system — and it will do it in an afternoon.

Spec-only workflows used to fail slowly, over a sprint or a quarter, with humans catching the drift along the way. Agentic workflows fail at execution speed. The cost of missing intent didn’t go up because intent got more important. It went up because the distance between “spec written” and “system shipped” collapsed to near zero.

So I don’t see intent-driven engineering as competing with spec-driven engineering. I see it as sitting above it.

The spec doesn’t go away — it’s still how the system gets described precisely enough to build. But it stops being the starting point.

What a spec actually can’t hold

The honest pushback here is that a good spec already encodes the why — acceptance criteria, non-functional requirements, and success metrics are supposed to carry that context. And a good spec does carry some of it.

The distinction that actually holds up

A spec is an artifact of a decision. Intent is the decision-making process that produced it.

A spec doesn’t carry the tradeoffs that were considered and rejected, the enterprise constraint that shaped where the boundary landed, or the evidence trail for why this was judged the safe and correct call.

That information doesn’t fail to make it into the spec by accident — specs aren’t built to hold it. It lives in a meeting, a Slack thread, someone’s head, or nowhere at all.

Which means it’s the first thing lost when a human hands work to an agent, and the first thing an agent has no way to ask for.

That’s the difference worth building process around: not that specs are shallow, but that they’re downstream.

They freeze one decision without the reasoning that produced it — which means anyone or anything building from the spec alone is working from the answer with no access to the question.

The simple formula

Intent creates the reason.

The spec describes the system.

The agent builds against both.

The third layer: knowing it’s safe to ship

There’s a piece of the intent question that’s easy to fold into “why” but deserves its own attention: how will we know it’s safe to deliver?

That’s not the same question as “does it pass the tests.”

It’s the evidence layer — the proof that the constraints intent identified were actually respected by the system the spec described.

Testing checks the spec was implemented correctly. This checks the spec was the right one to implement in the first place, and that nothing got lost translating intent into it.

Skip that layer and you get systems that pass every test in the spec and still fail the business the moment they meet the constraint nobody wrote down.

None of this makes specs less necessary.

An agent still needs a precise description of the system to build it well, and “intent” without a spec is just a vibe with good intentions.

But sequence matters.

Intent first, because it’s the only layer that carries the reason.

Spec second, because it’s where that reason gets made buildable.

Agent last, because it’s the only one of the three that can move at the speed this now requires — and the only one with no judgment of its own about which reason it’s serving.

Specs are important. But intent is upstream. Intent gives the spec meaning.

Mark Kendall is the founder of Intent-Driven Engineering and Principal Architect at LearnTeachMaster, where he writes about agentic delivery, enterprise AI adoption, and the discipline of building software that knows why it exists.

https://intent-driven-engineering.netlify.app/#contactYou can paste this straight into a Markdown editor, GitHub README, Wix markdown block, or Claude intent file.