The New Code: Why Specifications Will Replace Programming

The agents were doing exactly what I told them to. That was the problem.

I'd built a pipeline where AI agents could take a spec file, implement a feature, run the tests, review the result, and commit — without me writing a line of code. It mostly worked. Dozens of features shipped. But I kept reviewing the output and feeling like something was off. Not broken. Just subtly wrong in a way that was hard to name.

I spent a while blaming the models. Then the prompts. Then the validation steps. Eventually I had to sit with the obvious: the agents were implementing exactly what I'd written. My specs were underspecified. The bottleneck was always me, at the planning stage.

The thing most people throw away

There's something that feels right about vibe coding. You're operating at the level of intent — describing what you want and letting the model handle the mechanics. That part is genuinely useful.

But watch what most people do with the output:

You've shredded the source and carefully version-controlled the binary.

The prompt — your structured description of what you wanted, why, and what "correct" meant — is the valuable artifact. The generated code is what compiles from it. When you discard the prompt and commit only the output, you've lost the thing that actually mattered.

The practical consequence shows up six months later: you're staring at code you wrote and spending twenty minutes reverse-engineering your own intent. The spec would have been a thirty-second read.

What a spec-driven pipeline is

I built what I call an SDLC (Software Development Lifecycle) harness — a system where instead of writing code directly, you write a spec describing what needs to be built, and AI agents handle the implementation, testing, review, and documentation.

The spec is the source. The code is what gets compiled from it.

Simple idea. The interesting part is figuring out how to run that pipeline efficiently. I made some expensive mistakes along the way.

The first version: expensive

My original design ran every task through the full pipeline — implement, test, review, document, wrap-up — independently, in an isolated environment, in parallel:

On paper: thorough. In practice: around 200,000 tokens per task. A five-task spec burned through a million tokens before I'd seen any integrated output.

The waste was structural. Setup phases that didn't vary between tasks ran N times. Per-task reviews could only see one task's changes — they missed integration problems anyway. Documentation ran in isolation before anything was assembled.

And the per-task review gave me false confidence: it caught issues within a task, but couldn't catch whether the integrated result actually worked. I was paying for isolation on tasks that were mostly sequential.

What I rebuilt

The redesign comes from a simpler question: what actually needs isolation, and what can be shared?

The implement step benefits from a fresh context per task — no bleed between unrelated changes. Everything else — setup, testing, review, documentation — can run once over the integrated result.

That produces a clean ladder of tools:

Pick the rung that matches the scope. A trivial hotfix doesn't need a review stage. A whole feature spec does. Multiple independent feature blocks running in parallel need the orchestrator.

The biggest change is in the orchestrator. The original version orchestrated individual tasks. The rebuilt version operates at the block level — each block is a complete feature-sized unit of work that runs its own full pipeline in its own branch:

And inside each sdlc-flow, the lean design runs one fresh implement agent per task, then one consolidated back-half over the integrated result:

Per-task agent isolation, at roughly the cost of running it once.

But the pipeline redesign didn't fix my outputs

Faster and cheaper, yes. Better results, no.

What made the results better was fixing the specs.

I'd been optimizing execution while planning was still the bottleneck. The agents were reading underspecified tasks, making reasonable assumptions, and producing technically correct results that missed the actual intent. No amount of pipeline tuning changes that.

You can't fix a bad spec with a better pipeline.

What a planning artifact actually looks like

The most interesting thing I've done with this pipeline: I used it to redesign itself.

Here's a condensed version of the master plan I wrote before touching a line of code. The goal was to redesign all four SDLC engines — and the spec-driven pipeline was the tool I used to do it:

A few things worth noting about how this spec works.

The goal section captures why this is happening before describing what to build. "Usage data: almost nobody runs it" is load-bearing context — without that, an agent might preserve backward compatibility with a behavior nobody is actually using.

The Files field is a commitment, not a description. The agent knows exactly which files to touch and which to leave alone. Anything not listed is out of scope by default.

The Interfaces / shared surface field tells the agent what this block exposes to the blocks that come after it. That's the contract other blocks depend on — changing it mid-implementation breaks downstream work.

The Out of scope field does something most specs skip entirely: it names the things you are not building. This matters because an agent trying to be helpful will often implement adjacent things that seem obviously related. Explicit out-of-scope entries prevent that drift.

And the acceptance criteria are verifiable against the diff. Not "the engine works better" — "these specific symbols are gone, this file is committed, node --check passes." These become the exact checklist the review stage runs.

Planning before generating

The flow that works for me now:

The planning step is where the hard questions happen: what does done actually look like, what are the real constraints, where are the edge cases. These are cheaper to answer before implementation starts than after.

When I rush through planning, I pay for it in review cycles. The root cause is almost always an underspecified task — and the fix is always "write a clearer spec," not "use a better model."

When I slow down at planning, implementations usually ship clean on the first pass.

The scarce skill

The scarce skill isn't writing code. It isn't prompting. It's writing specifications that fully capture intent — clear enough that a stateless agent can make the right call without asking follow-up questions.

This is hard. It requires thinking through your assumptions before you start. It requires distinguishing between "I have a vague sense of what I want" and "I can articulate what I want precisely enough for someone else to act on."

But it transfers. The same discipline that makes a good agent spec makes a better architecture decision record, a clearer PR description, a more useful design doc. It makes you a better collaborator regardless of whether the person on the other side is human or AI.

The tooling is changing fast. The underlying skill isn't.

Start with the spec.