The agents are here and we're all doing waterfall again

I can't code. I should say that upfront because it matters for what comes next.

For the past year or so I've been obsessed with vibecoding. Sitting with Claude Code, describing what I want in plain English, and watching working software appear. I've shipped websites, built automation workflows, created tools that would have taken a dev team weeks, even a card game for my daughters. Andrej Karpathy coined the term in early 2025: "fully give in to the vibes, embrace exponentials, and forget that the code even exists." That's exactly what it feels like.

But somewhere in the middle of all that prototyping, something started nagging at me. Every time I sit down to build something with an AI agent, I find myself doing the same thing: writing increasingly detailed specifications before I let the agent loose. What exactly should this component do? What are the edge cases? What's the expected output format?

I'm writing requirements documents. Detailed ones. Before any code gets written.

I've spent almost twenty years in and around software teams. I watched the industry fight its way out of waterfall and into agile. Stand-ups, sprints, user stories, iteration. The whole philosophy was: don't try to specify everything upfront because you can't. Ship something small, learn from it, adapt.

Now here I am, here we all are, managing teams of AI agents and doing the exact thing agile was designed to kill. The industry has even given it a name: spec-driven development. As Thoughtworks noted, some people call it a return to waterfall, "not unreasonably."

The agent spec problem

Here's what happens when you give a coding agent a vague instruction: you get vague output. Or worse, you get confident output that's wrong in ways you didn't anticipate. The agent fills in every gap in your specification with its best statistical guess, and those guesses compound.

So you learn fast. You learn to be precise. You describe the data model, the user flow, the error states, the dependencies. You write what is, functionally, a detailed design document, the kind of thing a waterfall project manager in 2004 would have recognised immediately.

This isn't just me fumbling around as a vibecoder. Watch experienced developers working with agents. They're doing it too. One engineering leader described the pattern as "agile planning, waterfall execution," with teams spending 3x more time on upfront design so that agents can execute without constant course-correction.

Why agents pull us backward

The thing that made agile work was humans. Specifically, humans' ability to operate with ambiguity. A developer on an agile team doesn't need a perfect spec. They can ask a clarifying question in Slack. They can make a reasonable assumption and flag it in the PR. They can build something rough, show it to the product person, and course-correct in real time. The feedback loop is fast and informal and full of context that never gets written down.

Agents can't do that. Not quite yet, at least. An agent doesn't wander over to your desk and say "hey, I noticed the API returns dates in two different formats, which one should I use?" It just picks one. Or it hallucinates a third option.

So to compensate, you front-load all the thinking. You try to eliminate ambiguity before the agent starts working, because ambiguity is where agents go sideways. As François Zaninotto put it bluntly: spec-driven development "revives the old idea of heavy documentation before coding, an echo of the Waterfall era."

But this isn't really waterfall (and the planning is kind of fun)

Here's where the analogy breaks down if you push on it. The reason waterfall was painful wasn't the planning itself. It was the feedback loops. You'd spend months writing a 200-page spec for a system that would take a large team years to build. By the time you saw working software, the requirements had drifted, the market had shifted, and the cost of rework was enormous. Long feedback loops meant high risk, high rework, and high pain.

What we're doing with agents looks like waterfall on the surface, but the feedback loops are compressed at every stage.

Start with the planning. Old waterfall meant sitting alone (or in endless meetings) trying to be omniscient. I plan with an LLM. I open a chat and start talking through the idea. "I want to build a tool that does X." The LLM asks me questions I hadn't considered. It surfaces edge cases. It proposes a data model and I push back on parts of it. We go back and forth, sometimes for twenty minutes, sometimes for an hour, and what comes out the other end is a thorough PRD that I didn't have to write from scratch. The feedback loop on planning has gone from weeks to minutes. And frankly, it's the part I enjoy most.

Then there's the execution. An agent can actually read and follow a spec, which is more than you could say for a traditional waterfall handoff to a dev team. Nobody actually read those 200-page documents. Agents do. Hallucination risk aside, the spec has real value because it gets reliably consumed. And because the agent can start building against the spec immediately, you see working software in minutes, not months. You can steer it, give quick feedback, adjust.

And crucially, the scope is different. Traditional waterfall specs were blueprints for teams of engineers across many months or years. The specs I'm writing are for things that a small team (me and an agent) can build in days or weeks. The academic research distinguishes between "vibe coding" (conversational, exploratory) and "agentic coding" (autonomous, goal-driven), and the most productive workflow I've found uses both: vibe my way to a good spec, then let the agent execute it.

If anything, this is closer to what software engineers call modified waterfall, where the sequential phases overlap and include built-in feedback at each step. Traditional waterfall was essentially one-shot: plan, build, pray. What we're doing is more like plan-with-AI, build-with-AI, review, adjust, repeat. MIT Technology Review captured this shift from vibes to what's being called "context engineering," the systematic work of giving AI the right information to act on.

The agents are learning, slowly

One thing worth noting: this isn't completely static. The agents are getting better at retaining context, and that changes the dynamic.

Tools like Claude Code now support persistent project memory through CLAUDE.md files, where you can teach the agent your conventions, architecture decisions, and coding standards once, and it loads them automatically every session. The pace of improvement is visible in the changelogs: version 2.1.32 (released this week) added automatic memory recording and recall as you work, and 2.1.33 followed with persistent memory scoping for agents at user, project, or local levels.

The community is pushing even harder. Claude-Mem, a plugin that captures what Claude does during coding sessions and injects relevant context into future sessions, hit #1 trending on GitHub in early February 2026. Martin Fowler's team is already evaluating spec-driven development tools and finding the practice still immature but evolving fast.

Every time I correct an agent and that correction sticks in a memory file, the spec I need to write next time gets a little shorter. That's the trajectory. Not a sudden leap to agile, but a gradual reduction in how much upfront planning the agent needs from me.

What actually changed

So here's my honest read on where we are. We're not doing waterfall. We're doing something that has the shape of waterfall, in that we're specifying before building, but with feedback loops that are orders of magnitude tighter at every stage. The planning is fast and collaborative (thanks to LLMs). The spec actually gets followed (thanks to agents). The execution produces working software in minutes, not months (thanks to both). And the whole cycle, plan to build to review, can happen in an afternoon.

The real shift is this: we're using one AI to plan in conversation, then handing the plan to another AI to execute. The human in the middle (me, the vibecoder) is less an engineer and more a translator between two modes of artificial intelligence, one that thinks in dialogue and one that thinks in code.

Agile was a response to long feedback loops. Agents have compressed those loops dramatically. What they haven't done, not yet, is eliminate the need for explicit specification. Until agents can truly collaborate, handle ambiguity, and share context the way a human teammate does, we'll keep front-loading our thinking into specs.

We just call it "prompt engineering" now instead of "requirements gathering." Same energy.

Where this might go

I don't think we stay here forever. Thoughtworks calls the current moment an "emerging practice" and expects significant change in 2026. Persistent memory is improving fast. Context windows are growing. Claude Code just shipped multi-agent collaboration as a research preview, with agents that can coordinate across tasks. At some point, working with an agent will feel less like handing off a detailed blueprint and more like pairing with a junior developer who happens to type at the speed of light.

But right now? Right now the vibecoder in me is living in two worlds. One where I have superpowers I never imagined, shipping real software, prototyping ideas in an afternoon, building things that work. And another where I spend my mornings chatting with Claude about edge cases in data models before I let Claude Code anywhere near the implementation.

The tools changed. The fundamental communication problem didn't. And until it does, those of us managing agent teams will keep front-loading our thinking into specs, enjoying the process more than we probably should, and watching the feedback loops get shorter every month. Though I'll admit, this version is a lot more fun than waterfall ever was.