Spec-Driven Development: When You Edit the Spec, Not the Code

There’s a question every developer working with agents eventually hits: if the agent writes the code, what exactly am I writing? For a year the honest answer was “prompts, and a lot of corrections.” In 2026 a clearer answer has emerged, and it has a name: spec-driven development. You write the specification — precise, durable, version-controlled — and the agent generates the code from it. The artifact you own moves up a level, from the implementation to the intent.

This isn’t a fringe idea anymore. With something like 84% of developers using AI tools and a large share of new code now machine-generated, the discipline shifted from optional to load-bearing. The reason is a single sharp observation: “AI-generated code is plausible by construction, not correct by construction.” It compiles, it reads well, it passes the obvious tests — and it can still quietly drift from what you actually meant. A spec is how you pin down “what you actually meant” in a form both a human and an agent can check against.

Three stages, ending somewhere radical

Martin Fowler’s framing is the cleanest map of where this goes, as a three-level maturity model:

Spec-first — you write a spec for a task, use it to drive the agent, and once the work ships, the spec is discarded. The spec is scaffolding. Most teams start here.
Spec-anchored — the spec becomes a living document, maintained across the feature’s life. Changes start in the spec; the agent regenerates the code to match. Most serious spec-driven tooling targets this level today.
Spec-as-source — the radical endpoint: the spec is the only artifact humans edit, and code becomes a transient, compiled output that no human touches by hand. The repository’s source of truth moves up a floor.

It’s worth sitting with how strange spec-as-source is. We have spent decades treating source code as the artifact — the thing under version control, the thing we review, the thing we own. Spec-as-source demotes code to the status of a build output, like a compiled binary. You wouldn’t hand-edit an executable; in this vision, you don’t hand-edit the generated code either. You edit the spec and recompile.

The spec is the leverage

This maps onto something we wrote in The Code Agent Orchestra: when you direct a team of agents, your spec is the leverage — and a vague spec doesn’t just slow you down, it multiplies across every agent acting on it. Spec-driven development is that insight turned into a workflow. The standard loop is four phases: specify what the software should do, plan how to build it, implement in validated increments, validate that the code meets the spec. Each phase produces an artifact that constrains the next, so error has fewer places to hide.

And critically, the spec stops being a document you write once and file away. It becomes a living operating agreement the agent reads on every run — the same role we’ve described for a human-curated AGENTS.md. The leading frameworks make this explicit: GitHub’s Spec Kit keeps a constitution.md of non-negotiable principles that sit above every spec; OpenSpec organizes work into change folders of proposal, specs, and tasks; BMAD assigns named personas with their own domain rules. Different shapes, one idea: the spec is the durable, governing artifact, and the code is downstream of it.

The critique worth taking seriously

It would be dishonest to sell this as settled. The sharpest pushback comes from Matt Pocock, and it deserves a fair hearing: by routing everything through “specs to code,” he argues, “we are not investing in the design of the system. We are divesting from it.” The worry is that a tidy spec can paper over the absence of real architectural thinking — that you can generate a lot of plausible code from a spec while the underlying design quietly rots.

The data gives the critique teeth. Experienced developers working on mature codebases have been measured as ~19% slower with AI assistance, which suggests that on real systems, codebase quality and design discipline matter more than specification polish. A spec is not a substitute for a shared mental model, a clean architecture, or the taste to know what not to build. The right reading isn’t “specs replace design” — it’s “specs are where design gets written down so agents can’t drift from it.” A spec with no real design behind it just lets you ship the wrong thing faster, which is the bad-loop problem one level up.

Why this is the right bet for Southeast Asia

Here’s where it lands for the region, and it’s the same place our thesis keeps landing. Spec-driven development relocates the valuable, durable work to writing down what correct means — and that is domain knowledge and clear thinking, not GPU spend.

A generic agent can generate plausible code all day. What it cannot do is know that a Cambodian payroll must handle a specific seniority bonus rule, or that a Khmer-language form has a field a foreign template omits, or how a local co-op actually books a harvest. Encoding those rules into a living spec is how local knowledge becomes durable, ownable IP — a spec is the most portable, lasting form that knowledge can take. The frontier lab will generate the code from your spec for pennies. It will never write the spec, because it doesn’t know your domain. That asymmetry is a seat at the table, and it’s a writing-and-thinking seat, which is exactly the kind we keep arguing the region should take.

What to take from this

Start treating the spec as a first-class artifact, not a throwaway prompt. Move from spec-first toward spec-anchored: keep the spec alive, change it before you change the code, let the agent regenerate. Invest your real effort in the design behind the spec — because a spec is only as good as the thinking it captures. And encode your domain’s hard-won rules into specs and skills the agent reads every run, because that is where your advantage compounds.

The agent writes the code now. Your job is to write — and keep writing — what the code is supposed to be. Edit the spec, not the code.