The Spec Comes Last

Spec-driven development is having a year. There are courses for it, tools for it, and a chain of skills that ends in a command called /implement-spec.¹/01field noteThe tooling came from everywhere: Kiro at one company, Spec Kit and Thoughtworks’ taxonomy in one Spanish-language explainer, OpenSpec in David Cramer’s repo, and, as one reply teased Matt Pocock, a chain of skills from /to-specs to /implement-spec.saiz, Oct 27 · Gentleman Programming, Nov 1 · David Cramer, Jul 13 · Ben Eng, Oct 22The pitch is flattering: write down exactly what you want, let the agent build it, and become the thoughtful one who never has to touch the code.

Here’s what usually happens instead. An AI writes the spec. It’s long, confident, and close to illegible. A human skims it, approves it, and hands it to another AI, which reads every word and believes all of them. Whatever human attention went into that loop came out of the one place it was needed: the code.

My argument has three parts. A spec detailed enough to work is code, written by someone who can’t compile it. A spec written by an agent pulls human attention away from cleaning the code the agent will actually learn from. And agents copy what’s already there, so the codebase is the real spec, and bad context in it spreads like a virus. The fix is to flip the order. Build the garbage first, clean it, and write down what survived. The spec comes last.

This is the long version of one chapter of What We Had to Unlearn. I’ll give spec-driven development its best case before I answer it, and I’ll end with the person who might prove me wrong.

Code that can’t compile

The cleanest test case arrived in March. OpenAI published Symphony, a service that orchestrates coding agents, along with a SPEC.md that describes itself as “language-agnostic.” The README’s suggestion was the whole pitch: tell your favorite coding agent to implement Symphony in the language of your choice, from the spec.

Gabriella Gonzalez took that literally. Gabriella asked Claude Code to build Symphony in Haskell and published the result as symphony-haskell. It didn’t work. There were several bugs to prompt away, and even when it ran without errors, the agent it launched spun silently on a sample ticket that asked for nothing more than a blank git repository.²/02field noteGabriella’s point isn’t limited to Symphony. YAML has a detailed, widely used spec with a conformance test suite, and most YAML implementations still don’t fully conform. And by Gabriella’s count, Symphony’s spec is already a sixth the size of the Elixir implementation that ships with it.Gabriella Gonzalez, “A sufficiently detailed spec is code” · symphony-haskell

The failure wasn’t the interesting part. The interesting part was what Gabriella found on reading the spec closely, written up in A sufficiently detailed spec is code. The “language-agnostic” document contains prose dumps of database schemas, prose dumps of code, a section titled “Reference Algorithms” that is plainly pseudocode, and a config cheat sheet that admits why it exists: “This section is intentionally redundant so a coding agent can implement the config layer quickly.” Here is the spec’s retry rule, verbatim:

Failure-driven retries use delay = min(10000 * 2^(attempt - 1), agent.max_retry_backoff_ms).

And here is the same rule in TypeScript, written by me:

const delay = Math.min(10_000 * 2 ** (attempt - 1), maxRetryBackoffMs);

That isn’t a specification of the code. It is the code, wearing a trench coat.³/03the poststhe Symphony spec was almost literally code gabby, Mar 17

Gabriella names two misconceptions behind the pitch. The first is that a spec is simpler than the code it describes. It can’t be, if it has to produce working code reliably: to get there, you have to contort the document into code, or into English so structured it might as well be code. Gabriella quotes Dijkstra, who called medieval scholasticism “a vain attempt at verbal precision,” and Borges on the map the size of the empire. The second misconception is that writing a spec is more thoughtful than writing code. It used to be, when a spec was the slow, uncomfortable part of the job. Optimize it for delivery speed and you get Symphony’s section 10.5, which Gabriella calls “a grab bag of ‘specification-shaped’ sentences.”⁴/04field noteSomeone remembered that this was tried before: UML was supposed to let engineers draw diagrams and have compilers generate the code. Another reply reported the same from production: full specs become pseudocode you maintain alongside the real code.phil bohun, Mar 21 · Chen Avnery, Mar 17

Dex Horthy compressed the argument into a rule of thumb that I now repeat to anyone who’ll listen: a spec detailed enough to generate good code is about as long as the code, so review the code. A detailed enough spec is just code written by someone who can’t compile it. You get all the precision work of programming and none of the feedback.⁵/05field noteGabriella isn’t against specs. Gabriella has written plenty of specs and design docs, and named two good uses: supporting several implementations of the same thing, and promoting critical thinking.gabby, Mar 17

A word with no meaning

Part of the problem is that nobody agrees what a spec is anymore. In October, Matt Pocock asked for a definition and blamed “semantic diffusion,” Martin Fowler’s term for a word that loses its meaning as it spreads. Dex’s answer was that the term is past saving, and that people should just describe what they do, even if it takes more words.⁶/06the postsSemDif is a one way door dex, Oct 23You do not keep your specs in your repo. You treat specs like you treat linear or Jira artifacts. AiDevGuy, Oct 22Matt Pocock, Oct 22

The replies proved Dex right. For one engineer at a Fortune 100 company, spec-driven development means a planning process: portfolio epics, feature epics, stories, and tech designs, kept outside the repo like Jira tickets. For others it means a spec you could regenerate the whole program from.⁷/07field noteOne reply drew a crisp line: if you can throw the code away and regenerate something equivalent from the spec, it’s spec-driven development; otherwise it’s just a long prompt.Atharv Yeolekar, Oct 22 For a third camp it means an agent that interviews you before it starts. Those are three different practices with one name, and the name is doing the selling.

Meanwhile the name became curriculum. In September, MoureDev released a free Spanish-language course that promised, in my translation, “the professional method to leave vibe coding behind and program with AI and agents.” Manz followed in October with a from-scratch guide. A month later, in the same community, Nicolás Schürmann said it in one line: “Spec Driven Development has never given me good results. The new thing is vertical slice development and AI pair programming.”

I’m not mocking the courses. They’re answering a real fear: vibe coding falls apart, and people want a method. But a method whose name means anything has stopped telling you what to do.⁸/08field noteIn the same community, Gentleman Programming answered with a video titled, in translation, “We killed SDD for ODD,” arguing that every definition of SDD starts with a spec written before the code, and that the truth should live “in the verified code, with the suite green.”Gentleman Programming, Nov 1

The best case

The case for specs deserves better than the worst examples, so here it is at full strength.

Companies are betting on it. One Spanish-language post in October said new projects at the author’s company were being built spec-first with Kiro, and that one senior with AI now does what used to take five juniors.⁹/09field noteThe enterprise reading is real too. At one Fortune 100 company, spec-driven development is a planning process for teams running agile at scale, with managers who still coordinate across initiatives and report across a larger org.AiDevGuy, Oct 22 Herbie Bradley, replying to Gabriella, argued that the Symphony spec really is simpler than its code: mostly plain English, with some schemas and pseudocode, and faster to write than the full program. And the strongest evidence came in November, from Amazon.¹⁰/10the postsspecifying how a model should implement a specific solution is significantly superior to writing prose Andrei Maxim, Nov 8Even various tactics like providing a test suite or an oracle is inferior Andrei Maxim, Nov 8the only way to verify if the solution was optimal is to read through a lot of AI-generated code Andrei Maxim, Nov 8

According to Andrei Maxim’s summary, a paper from Amazon researchers found that telling a model how to implement a solution, in a pseudocode-like form, beat prose specs, and even beat handing the model a test suite or an oracle. When developers defined the intended structure, Andrei writes, the error rate could drop dramatically, though past some point the gains stopped being worth the cost.¹¹/11field noteI haven’t read the paper; this is Andrei’s summary. One reply said another paper found the opposite, poorer outcomes from telling models how to implement something rather than describing success criteria. Another was less diplomatic: “may as well write the code.”Andrei Maxim, Nov 8 · iTwittles, Nov 9 · fj, Nov 10 That’s a real result for thinking before building.

Look at what kind of spec won, though. Not the prose. The pseudocode. The paper, as Andrei describes it, supports spec-first work and Gabriella’s title at the same time: the spec that works is the one shaped like code. Andrei’s reason is the important one. An unconstrained agent can pick any of many solutions that meet the requirements, and the only way to know whether it picked a good one is to read a lot of AI-generated code.

The fairest objection to Gabriella came from a reply in March: maybe specs shouldn’t be blueprints at all, but constraints. Not what to build, but what you can’t do without approval. Gabriella’s answer is worth keeping.¹²/12the postsA cron job requirement isn't a blueprint — it's a boundary checked before execution. MiauWorld, Mar 17of the same order of magnitude as the work to specify the desired behavior in code (sometimes more so) gabby, Mar 17

Marc Brooker’s version of the case is the one I take most seriously. In What’s Easy Now? What’s Hard Now?, Brooker argues that agents are feedback loops, so tasks with good feedback get easy and tasks without it stay hard. That, Brooker writes, will “raise the importance of specification,” defined as “the writing down of what good looks like to drive the feedback loop,” along with the tools that check code against it: Rust, TLA+, P, Kiro’s spec analyzer, property tests.¹³/13field noteThe same essay predicts which work gets easy first: a database storage engine, which has a fairly simple specification, before a delightful photo-editing website, whose feedback loop needs humans.Marc Brooker, “What’s Easy Now? What’s Hard Now?” I agree with every word of that. It just isn’t the spec anyone is selling in a course. Brooker’s spec is something a machine runs on every change. Nobody has to read it and believe it.

A novel of slop

So where does spec-driven development go wrong in practice? Mostly in who writes the spec. The idea assumes a person sat down and thought hard. What it gets, more and more, is a document an agent produced in a minute, reviewed by a person in less.¹⁴/14the postsEvery check in that process was AI checking AI. Mark Ajzenstadt, Nov 5made it much easier to write flawed specs that look like finished work Matija Grcic, Mar 17Ayush, Aug 26

Mark Ajzenstadt tells the story of a team building software for government agencies that followed spec-driven development by the book: specs first, agents building from the specs, tests generated automatically. They still ended up, in the co-founder’s words, “vibe coding a bunch of slop.” The specs were AI-written, so their design decisions went straight into the code unexamined. The tests restated the code, so they could never fail. Treat it as an anecdote, not data: Mark’s team sells this kind of review, and the thread ends with an offer of a 30-minute look at your specs.¹⁵/15field noteMark’s own prescription keeps the spec but puts a person on it: a human writes and signs off every spec, and tests come from the spec, never from the code. Replies asked the sharper question: did the specs fail, or did nobody check the code against them?Mark Ajzenstadt, Nov 5 · Exori, Nov 5 · Tolu, Nov 5 But it matches the most-liked reply to Gabriella, which said LLMs had made it much easier to write flawed specs that look like finished work. And it matches the plainest complaint I found: someone asked an engineer for a PRD so it could be reviewed quickly, and got back “a novel of slop.”

That’s what spec-driven development often means now. An AI writes a novel of slop, a human’s eyes glaze over somewhere in section four, and another AI reads the whole thing and does what it says.

This is the part I care about most, because the cost isn’t the tokens. It’s attention. A team has a fixed amount of human care to spend, and every hour spent polishing a spec is an hour not spent cleaning the actual code. People drowning in documents and pull requests that nobody wrote on purpose stop wanting to improve anything.¹⁶/16field noteThe organizational version: a meeting, then a PRD someone generated that “most people never read,” then another meeting and another document, for something one person could have built in two hours. Lauren (poteto)’s counter: build it and share a PR or prototype instead.GosuCoder, Oct 24 · lauren, Jul 16 The will to fix the code dissipates, and the code is the one artifact the agent is certain to read.

the trade nobody prices in

Every hour polishing a spec is an hour not spent cleaning the code.

This is the same problem as AI-written prose, which I wrote about in “Send Me Your Prompt”: a document nobody wrote is a document nobody should have to read. The only difference is the reader. Here the reader is an agent, and an agent doesn’t skim.

Stale before the merge

Suppose the spec is good. It still has a shelf life, and it starts going bad before the change that inspired it lands.¹⁷/17the postsI dont think its adding value. … Going to delete them all David Cramer, Jul 13

David Cramer ran the experiment in July. After months of keeping specs next to the code, Cramer found they had quietly become docs, cost a lot of compute to keep updated, and didn’t help much with steering. Worse, they drifted far enough that “the agent misunderstood what truth was.” Cramer’s other finding is the one I keep coming back to: even when a spec described intent, the models often ignored it “and they simply end up doing more copy paste.” The conclusion was to delete them all and spend the effort on careful code design instead.¹⁸/18field noteMatt Pocock replied that a lot of folks seemed to be converging on that setup. Others kept specs only as history: Jamon Holmgren doesn’t update them once committed, so the agent treats them as a record of how something was built, not as docs.Matt Pocock, Jul 13 · Jamon, Jul 14

Matt Pocock put the mechanism in a drawer. Give an agent a markdown file and it will fill it with implementation details, session notes, and stale docs. That’s the trap. Your spec is stale before the merge, and the agent believes it anyway, because the agent has no way to tell an old sentence from a true one.

A Spanish-speaking team described the same arc in October. They started with a spec, then a plan, then a task list for every feature. In my translation: “the documents go stale fast and stop reflecting what the code does.” They spent a lot of time and tokens writing and reviewing them, and often did no better than working with the agent step by step. So they cut back to living specs only for what lasts and crosses services, like contracts, architecture decisions, and business rules, and made “tests and checks the real source of truth.”¹⁹/19field noteThe team cites Birgitta Böckeler’s three levels of spec-driven development: spec-first, spec-anchored, and spec-as-source. It keeps living specs because its features cross services and run on parallel agents, where one misunderstanding costs days.HyruleMuse ▲✨, Oct 22²⁰/20the postsThe spec goes away, and the ACs stay and are refined over time. SpecDLC, Oct 22

My favorite line from the whole debate came from a small account in that same thread: specs age like milk, acceptance criteria like wine. The spec is scaffolding. What stays is the part a machine can check.

Context is contagious

Here’s the analogy I’ve been building toward. Bad context spreads like a virus.

Agents learn your codebase the way a new hire does, except faster and with no judgment about what’s an accident. They find a pattern and repeat it. A temporary workaround becomes the house style. An outdated comment becomes a rule. A spec that describes a system you no longer have becomes the truth for every agent that reads it, and each of them writes code that matches it, which makes the next agent even more sure.²¹/21the postscompetent models should be able to infer the spec from the implementation Anthony Humphreys, Jul 13Reviewing it with the people who’ll use the software is part of the engineering, too The SI Maximalist, Nov 5

The people who build with agents all day keep landing on the same picture. Lauren (poteto) called a harmless-looking comment about a temporary workaround “one of the worst viruses you can have in your codebase,” because agents love copying what already exists. Ben Holmes wrote that agents, like humans, “copy bad patterns like a virus.”²²/22field noteLauren’s cure was to delete most code comments. Ben’s was a weekly automation that pulls out one improvement to the system architecture at a time.lauren, Oct 13 · Ben Holmes, Nov 9 A reply under Mark Ajzenstadt’s thread made the spec version of it plain: a spec can make a bad assumption very repeatable.

That’s why I think the codebase is the spec. Not as a slogan, but as a description of what agents actually do. Andrei Maxim made the same point from the other side: once a codebase grows, it narrows the space of solutions an agent will consider. The catch, Andrei adds, is that the codebase reflects your old understanding of the problem, which may not be your current one.²³/23field noteAndrei later tied the Amazon paper to the strict framework Lauren (poteto) has described for Grok Bot, and guessed that richer type systems, like Rust’s and TypeScript’s, can encode constraints that would otherwise need code skeletons.Andrei Maxim, Nov 8 · Andrei Maxim, Nov 9 Exactly. So update the codebase. Every rule you want an agent to follow is more contagious as working code than as a paragraph in a markdown file nobody reopens.

the real spec

Agents copy what’s there. The codebase is the spec.

If that’s true, the highest-value human work on a team isn’t writing better specs. It’s keeping the code worth copying: deleting dead patterns, fixing the one bad example before it has fifty children, and turning reviewers’ complaints into checks that fail. I made the long case for that in “Make Bad Code Impossible.” The short version is that the best vaccine is a codebase where the wrong thing doesn’t compile.²⁴/24field noteAccording to a Chinese-language summary of a talk by Lauren (poteto), the team ships about 11,000 pull requests a month with a 0.5% rollback rate, and the first rule on its list is to clean up old code so agents don’t copy it. I haven’t found the talk itself. Dex’s version of the same advice: push determinism as far as it can go.dex, Jun 20 · 高运通, Nov 12

Build the garbage first

If the spec doesn’t go first, what does? The build. Make something, look at it, throw most of it away, and write down what survived.²⁵/25the postsship and discard a version of it with an agent first before starting the manual part Igor Zalutski, Mar 17a spec that is more grounded in reality, instead of expressed in terms of hypotheticals Neo, Mar 18The majority of the finished product is in the iteration, not v1. Aaron Boodman, Jun 11

Aaron Boodman doesn’t find “create giant spec and let it loose overnight” productive: “I need to be in the loop to even know what I want.” Igor Zalutski said it’s much faster to ship a janky approximation and rebuild from scratch than to ship the right thing on the first try, which is the old agile idea on a smaller clock. And one reply to Gabriella described the order I’d recommend: let the agent build something, have it summarize what it learned into a spec, then throw the build away and reimplement from that “grounded spec.” The spec is a receipt, not a blueprint.²⁶/26field noteEric Stevens located where spec-first breaks: not the first spec, but the second iteration, once the agent has built something and has to be talked out of it.Eric Stevens, Mar 27

The sharpest version is in Chinese, from a developer who goes by 工业聚 (guyingjie). In my paraphrase: don’t listen to any advice that tells you to think everything through before you let an agent touch the code. Build a piece of garbage first. If a product doesn’t have a hundred abandoned pieces of garbage behind it, you probably weren’t serious.²⁷/27the posts过去思考要多，是因为做的成本高；现在思考的成本高于做的成本，所以做的要多 工业聚, Nov 12Specs turn into pseudo-code fast. Brian Cheong, Mar 19

the math, translated

Assumptions stacked on assumptions make weaker assumptions. Results stacked on results make stronger results.

So when you do write the spec, write it last, and write it in a form that can’t go stale quietly. Brian Cheong said the only specs that hold up are executable: tests, interfaces, and invariants that fail loudly.²⁸/28field noteAnother production report from the March thread: short constraint files that encode gotchas and boundaries beat full specs. “Constraints scale. Specs don’t.”Chen Avnery, Mar 17 That’s the spec in Brooker’s sense, and the one the Amazon paper keeps pointing back toward. It’s also the one that doesn’t need a human to keep believing it, which frees the human for the thing only a human does well: deciding what was worth keeping.

The bet I might lose

I side with Gabriella. But I should say clearly where I could be wrong, because the best counterargument isn’t about today’s specs. It’s about next year’s models.²⁹/29the postsslop also exists in code, so this is not really an argument against specs Herbie Bradley, Mar 18we will move towards spec driven development. I believe this is true over the next 5-10y Herbie Bradley, Dec 10

Herbie Bradley’s argument is a clock. The detail a spec needs depends on how well agents make the small decisions a spec leaves out, and that keeps improving. Six months earlier, Herbie wrote, the Symphony spec would have needed to be more detailed. Herbie also points out that agents already fill in missing detail reliably every day, just at low levels, like implementing a simple function from a one-line description, and that the level keeps rising. In December 2025, Herbie predicted spec-driven development within five to ten years, mostly without formal specs. If that’s right, the spec that has to be as long as the code gets a little shorter with every model, and Dex’s rule of thumb expires.

Others think the whole stack moves up. Marc Brooker expects an industry-wide shift in where developers work, from “in the code” to “in the specification.” Kun Chen went a level further: first we reviewed the agent’s code, then its plans, and soon we won’t be able to review all the plans either, so influence has to move up again, to a VISION.md that says where a project is going.³⁰/30the postsa much larger industry-scale raising of the level of abstraction developers work at Marc Brooker, Sep 18When I'm coding, I also am discovering what I want and how to get there. Kirt, Mar 18

Notice what survives even in their versions, though. Brooker’s spec drives a feedback loop. Kun Chen’s vision is a short statement of direction, not two thousand lines of pseudocode. Neither is a novel of slop. And Kirt’s reply to Gabriella still holds: coding is how you find out what you want. A spec written before that discovery is a guess with formatting.³¹/31field noteKun Chen’s /vision skill makes you rule on 8 to 12 hypothetical borderline feature ideas before it writes the VISION.md, which is then used to triage ideas and catch drift. That’s a document that decides, not one that describes. One reply said agents heavily reference theirs.Kun Chen, Aug 17 · John Fuller, Aug 17

So here is what would change my mind. Show me a spec half the length of its code, written and read by people, that different agents implement correctly from scratch, twice, without anyone patching the result. Show me that it still matches the system six months later without someone spending their week keeping it true. When that happens, I’ll write the follow-up. Until then, I’m spending my attention on the code.