The spec strikes back
Specs were supposed to be dead. The software industry buried them alongside waterfall when it moved en masse to agile practices. No more spending six months on big upfront design to produce enormous specs that were out of date before they were finished. Teams learned better ways.
So why are so many of them quietly writing specs again?
The waterfall hangover
To understand where we’re going, it helps to remember exactly why waterfall broke down.
The core idea was sound: know what you’re building before you build it. The execution was the problem.
Specifications became enormous documents written by analysts who’d never shipped software, reviewed by stakeholders who couldn’t read them, and handed to engineers who filed them away and built what made sense. The time investment was extraordinary. Six months of design work, sometimes more. Then twelve months of development. Then a testing phase that discovered everything the spec got wrong.
By the time a product shipped, two years had passed. The market had moved. Users wanted something else. Competitors had already shipped three versions. The spec had been a bet on a static future, and reality had refused to cooperate.
Agile promised a way out. It delivered.
Agile’s hidden bargain
Agile didn’t eliminate design. It changed when and where it happened.
Instead of front-loading the entire design process into a document nobody would read, agile distributed it across the team, across time, across sprints. Teams built something, learned from it, and adjusted. User stories replaced requirements documents. Refinement sessions replaced architecture reviews. The acceptance that you wouldn’t know exactly what you were building until you’d started became a feature, not a failure.
This was genuinely faster. Feedback loops tightened. Early progress was visible. When requirements turned out to be wrong, and they always turned out to be wrong, course corrections happened in the next sprint rather than eighteen months later.
The bargain, though, was invisible at the time. The industry traded documented design for distributed design.
The tribal knowledge machine
Agile worked, and it’s worth being honest about why. It wasn’t the ceremonies. It wasn’t velocity tracking or burndown charts.
It worked because teams carried context.
Senior engineers knew why the authentication system was built the way it was, even without documentation. Product managers remembered the customer conversation that shaped the data model. Tech leads held a mental map of every architectural decision made over years, complete with the reasoning behind each one. That knowledge lived in the room, in refinement sessions and Slack threads and five-minute conversations at someone’s desk.
When requirements were ambiguous, and in agile they’re always a bit ambiguous, teams could fill the gaps. Not because the spec told them what to do, but because they understood the intent. They could make good decisions because they’d been part of every previous conversation.
An enterprise agile team spending 40% of its week in meetings isn’t doing something wrong. That is the design process. It’s just distributed into human heads instead of documents.
Agents don’t read the room
Now introduce an agent into that system.
An agent arrives without any accumulated context. It hasn’t been in the refinement sessions. It doesn’t know why the architecture changed in 2022. It has no intuition for the gap between what a ticket says and what it means.
Point it at Confluence and it will use what it finds. The problem is that documentation captures the what, the decisions made, without the why. Even when reasoning was documented at the time, it rarely gets updated when context shifts. What remains is an archaeology of past decisions, not a living map of current intent.
The output won’t be bad code. It will be correct code, written in the right style, following the right patterns. And it will often miss the point entirely, because the point was never written down somewhere an agent could read it.
The “just iterate faster” trap
One response to this is seductive: if agile worked by learning fast, and agents let you build faster, then agent-driven iteration should work even better. Compress the agile loop from weeks to hours.
The problem is that it confuses speed with learning.
Agile’s short cycles worked because each produced genuine feedback from real users. The iteration was fast so that learning could happen quickly, before too much had been built in the wrong direction.
Agent-driven fast iteration without that feedback loop is something different. You’re not learning faster. You’re generating more output with the same gaps in intent. Each cycle amplifies the original misunderstanding rather than correcting it. Token costs for agentic work aren’t trivial either. The more you iterate without improving intent, the more expensive the wrong direction becomes.
The spec strikes back
What’s emerging across the industry, quietly and with some awkwardness given how thoroughly we declared specs dead, is a return to intentional upfront design.
Not waterfall. Nobody is proposing six-month design phases or requirements documents written by analysts shielded from actual work.
But teams are discovering that agents need something waterfall had and agile abandoned: explicit intent. Not a ticket. Not a user story. A real articulation of what’s being built, why it’s being built that way, and what decisions have shaped the current system.
The encouraging part is that this doesn’t take months. The same AI capabilities that exposed the problem can help solve it. A team that previously needed weeks of refinement to align on intent can produce a coherent design document in days. The design phase isn’t being eliminated. It’s being compressed, and made explicit in ways agile never required.
This is what spec-driven development looks like now. Not a thick folder handed to a passive engineering team. A clear, current description of intent, produced collaboratively, that gives agents the context to do useful work.
Agile was right that heavy upfront specification slows you down. It was right that iteration beats planning for managing uncertainty. What it accidentally did was outsource design to tribal knowledge, to the accumulated context living in experienced engineers’ heads.
That worked when the people building the software were the same people carrying the design. Humans are good at reading the room. They infer intent from incomplete information, ask a clarifying question, remember a conversation from months ago that reframes today’s ticket.
Agents can’t do any of that. They don’t have the context, and unlike a new team member who absorbs it over weeks, agents start from zero every single time.
The spec isn’t coming back because waterfall was right. It’s coming back because agile made a bet that only works when the people building are also the people carrying the design in their heads. Agents have called that bet.
The teams that figure this out first won’t be the ones who spend longest writing specs. They’ll be the ones who figure out how to capture intent fast, keep it current, and give agents something real to work with.