Specifications as the Product

The specification is becoming the durable product of software engineering, and the code a disposable rendering of it. Across compiler research, agent-swarm economics, enterprise platform migration, and the planning-first workflows now emerging around coding agents, the evidence converges on the same inversion: when generation is cheap, the record of what you meant — the spec, the plan, the acceptance criteria — is worth more than the implementation itself, and scarce human effort migrates upward from writing code to deciding and specifying what should exist. The live disagreement is no longer whether this inversion is happening but what a spec ought to be — prose, YAML, a DOT pipeline, a formal language — and how much of it is worth writing before the first line of code.

The Argument

The inversion: code becomes disposable

Stevey's Google Platforms Rant is the ancestral text. In 2011 Steve Yegge compared Amazon and Google across every dimension and found Amazon ahead on exactly one: platform thinking. Bezos' circa-2002 mandate — every team exposes data through service interfaces, all inter-team communication goes through those interfaces, no back-doors, interfaces designed from the start to be externalizable, non-compliance means termination — turned Amazon into a platform company in which the API spec was the product and the implementation an implementation detail. Yegge's Golden Rule ("Eat Your Own Dogfood") and his theory of Accessibility — that software must be accessible to everyone, and the only way to reach that at scale is through platforms that let third parties build the right thing for every user — are the same structural insight at different altitude.

Two decades later the same inversion is happening at the level of individual codebases. The Dark Factory is a DOT File states it bluntly: "Software is cheap now. Specs are the expensive part." The pipeline spec is the reusable artifact; the factory code is dorodango — polish it, throw it away, rebuild from spec. When code is fundamentally wrong you regenerate it rather than debug it. The convergence of independent teams (StrongDM, Dan Shapiro, 2389 Research) on the same three-layer architecture — LLM client, agent loop, pipeline engine — without coordination is what that source calls the Attractor Pattern: the structure was discovered, not invented.

Write Only Code pushes the inversion to its end: if nobody reads the generated code, the spec is the only human-readable artifact, and the metric that matters becomes Slop Radius — how far unintended behaviour can spread before detection — rather than review thoroughness. The engineer shifts from author and reviewer to systems designer and constraint writer.

Agent Swarm Model Economics completes the compiler analogy from the economics side. Each capability jump — autocomplete → line → block → file → spec — raises the abstraction level, until a spec becomes the prompt and the swarm becomes a probabilistic compiler translating intent into working code. The centrepiece experiment is the strongest single piece of evidence for the whole theme: implementing the 835-page SQLite spec in Rust without the source code, test suite, or internet, graded against sqllogictest, where every model mix eventually converged on a full pass — the difference between runs was efficiency, not capability. The Claude C Compiler confirms the pattern from the compiler domain: Chris Lattner observes that agents reproduce well-established LLVM/GCC abstractions rather than inventing new ones, so the scarce resource shifts from writing code to deciding what deserves building. His operational warning doubles as a spec-writing rule — "well-documented systems gain dramatic advantage," because AI amplifies structure, while poorly structured code scales into incomprehensibility faster than before.

The Plan Is the Program names the collapse of planning and doing from a different angle: with tools that stop distinguishing intent from execution, the plan stops being a metaphor and becomes the literal artifact. Rewrite All the Code All the Time carries the argument to its terminal: if regenerating a codebase drops to SaaS-subscription cost, the spec is the moat, and the only spec worth having is one a succession of adversarial implementers can each build to without supervision — which is why the author concludes the destination is formal languages, not better markdown.

What counts as a spec

The sources agree the inversion is happening but diverge sharply on what the durable artifact should be, forming a spectrum from narrative prose to formal mathematics.

Narrative plans. How to Write a Good Spec for Agents gives the practical doctrine: start from a high-level vision and let the agent draft details, structure like a professional PRD, break tasks into modular prompts, build in self-checks and constraints, iterate. Its three-tier boundary system — always do / ask first / never do — is a direct answer to the "curse of instructions": model performance falls as instruction count rises, so modular spec files beat monolithic prompts.

Structured specs with stable IDs. Specsmaxxing argues markdown gets you far but is still not enough. The feature.yaml format gives every requirement a stable Acceptance Criteria ID (ACID) that threads through code comments and test annotations, creating a bidirectional trace between spec and implementation, and shifting review from file-by-file diffs to requirement-by-requirement acceptance. The format is deliberately prescriptive — specs say how the system should behave — and the source is explicit that this stands against OpenSpec's descriptive stance.

Living specs with deltas. OpenSpec treats the spec as a delta: a diff of how requirements evolved alongside code, so a reviewer sees the change in intent, not just implementation. Specs live in the repository, organised by capability, built incrementally rather than wholesale. Spec-Driven Development formalises the same idea as a triangle — specs define requirements, tests validate behaviour, code generates decisions that feed back into the spec — with a tool (Plumb) that intercepts commits to extract decisions from diffs and agent traces. The core insight is that implementing code clarifies intent, and that clarification should improve the spec.

Schema and contract specs. Spec-First Development at Benchling shows the enterprise version: each object declares its shape and behaviour once through a unified contract, and every platform capability consumes it generically. The integration point moves from per-platform implementations to a single shared contract.

Pipeline specs. The Dark Factory is a DOT File argues for workflow specs in Graphviz DOT — human-readable, version-controllable, familiar to anyone who has drawn an architecture diagram — with each node declaring whether it needs an LLM, a human gate, or a deterministic command. The pipeline is the blueprint; the runner is disposable.

Typed signatures. Prompt Debt diagnoses the failure mode that motivates all the stricter formats: natural-language prompts were never meant as a specification language, so every hot-fix risks regressing earlier instructions, and prose specs are the same lossy medium. The prescription is to specify behaviour with measurements — evals, metrics, typed constraints — rather than prose, and to search the prompt space algorithmically. DSPy — Programming Not Prompting is the framework that operationalises this: typed signatures define a task as inputs and outputs, modules control execution, and optimisers tune the prompt against a scoring function until quality converges — the prompt itself becomes a disposable compiler artifact.

The formal end. Rewrite All the Code All the Time argues structured natural language — EARS, YAML, BDD — shares a fatal flaw: formal keywords wrapped around freeform phrases leave ambiguity exactly where behaviour is decided. Only formal languages with mathematical semantics support automatic generation without human oversight. Lean Software Scaling Laws extends this with a testable research bet: the language a spec is written in matters for AI predictability, and by measuring frozen-LLM perplexity over codebases one could rank languages by suitability as spec targets, turning the case for formal methods from religious to quantitative. ZIL — Relational Language Embedded in Lean 4 gestures at the same destination from the data side: a small relational language that describes requirements coverage, dependency tracking, and change impact as relation tuples with Horn-clause rules, and computes full provenance for every derived fact — spec as something a machine can reason over, not just read.

The domain model as spec. BESSER sits at the formal extreme as a reference point: "model once, generate everywhere" — describe a system once and more than fifteen code generators compile it to working software across stacks. Because the generators are deterministic rather than probabilistic, BESSER marks the boundary where the translation stops being a prompt and starts being a compile, useful for calibrating the "how formal is formal enough" question.

Specs beyond code. Engineering Standards Enforcement at Cloudflare applies the thesis to organisational policy: engineering standards expressed as RFCs with SHOULD/MUST, fed to AI reviewers as compact JSON with stable slugs, enforcement gated behind a lifecycle state. The RFC is the durable artifact; the reviewer agents are its consumers. Tom Barraclough — Sovereign AI Policy takes the inversion to the scale of law — what if regulation shipped as structured, versioned, granularly referenceable datasets instead of PDFs — with the DocRef platform drafting a new API standard from regulatory corpus in an afternoon, work that traditionally takes nine months.

Finally, three tools collapse the distinction between the spec and the product entirely. barnstormer inverts the normal project: an agent swarm interrogates the user one question at a time and continuously builds a living spec as kanban cards, and the spec — not code — is the deliverable, with the pipeline diagram described as the "primary build artifact." Manifest-driven development inverts the workflow: tell the agent to pretend functionality exists, assume the behaviour for the whole session, and file every quirk encountered — "fake it until it works," spec-by-usage rather than spec-up-front. lat.md keeps the spec tethered to the implementation it describes: a knowledge graph of interconnected markdown where specs link into code and code links back, with a lat check command that fails when the two drift, on the premise that a spec only matters if it stays true.

The economics

AI Agents Need Clear Specs supplies the missing economic framing. Total cost against specification completeness traces a U-curve: minimal spec defers and fragments cost into correction loops, token burn, and repeated human re-engagement, while a 40-page formal spec front-loads effort and back-loads almost nothing; the minimum sits at well-structured acceptance criteria, and it moves right as task complexity and agent handoffs rise. The source's sharpest point is that spec validation is a distinct cost category between writing the spec and running the agent, and it is never zero — a spec can fail invisibly, and an agent faithfully executing a flawed spec produces output where you must unwind both code and reasoning. "The handoff is the product": every agent boundary needs a contract with schema, invariants, and validation checks, or you are compounding interpretations, not orchestrating agents.

What a User Story Actually Costs in a Dark Code Factory puts a measured price tag on this inversion: the spec, written interactively at planning time, cost an order of magnitude more than the code it produced. When specification costs that much and implementation runs that cheap, the spec is the expensive artifact — asserted as a thesis by The Dark Factory is a DOT File and measured in a ledger by that source.

Unit Economics of AI Software adds the structural caveat the cheerleaders skip. The zero-marginal-cost property that makes code disposable to regenerate is the same property AI erodes: every user interaction carries real inference cost. "Just rebuild it from spec" solves the generation problem but not the operating problem — the spec is durable, the inference bill is recurring. Simplicity in the Age of AI-Assisted makes the complementary point that cheap regeneration is only as good as the judgment that decides which complexity is essential and which is inherited; the LLM will not question your architecture, you must.

Prompt Debt sharpens the economics into a rule: the spec must be measurable, not merely written, because a prose spec is the same lossy medium as a prompt. Hard edges — evals, metrics, typed constraints — are what make behaviour portable across models, turning model evaluation from weeks into hours.

The deepest economic warning comes from Dev Machine Foundry. Sam Schillace's dev machine ran for 39 days, produced 3,706 commits and roughly 350,000 lines of TypeScript, and faithfully delivered 1,111 obscure word-processing features — while the basic ruler, sitting in the candidate list for 25 days, got zero lines. The machine's reward function favoured the deterministic green checkmark over the ambiguous important thing. "The machine is honest, but it isn't strategic. Strategy is still my job." The spec is the highest-leverage hour, but a spec can only encode what; it cannot encode which matters, and a machine left to its own priorities will optimise the wrong thing.

The planning layer

The strongest new development in this evidence is that the discipline has moved from writing the spec to building the process around it.

The AI-Native SDLC Playbook (Anthropic) is the clearest articulation: the old SDLC was built for an era when writing code was the slowest stage; now that code is no longer the bottleneck, the controls migrate to the stages around the build. Its organising device is the committed artifact — every stage ends by writing something to version control (intent.md, spec.md, plan.md, the diff and its tests, the review findings) and the next begins by reading it, so the commit chain doubles as the audit trail. Requirements and design collapse into one session; nothing is implemented without an accepted plan; human attention concentrates at the gates rather than starting each stage from scratch.

A family of tools operationalises exactly this. SDDW (Spec-Driven Development Workflow) runs a seven-step pipeline — Requirements → Code Analysis → Design → Taskify → Implement → Verify → Self-Improve — with functional-requirement IDs traced through every artifact and a four-rule classification for deviations in which architectural changes always stop and ask the human, even in --auto mode. recursive-mode makes each phase produce one locked document consumed by the next, so requirements and plans survive as files rather than rotting in chat history. Structured-Prompt-Driven Development treats the prompt itself as a first-class, version-controlled delivery artifact, structured by a REASONS Canvas and governed by the golden rule "when reality diverges, fix the prompt first — then update the code."

The field-tested results are the same doctrine with the receipts. SDD Case Study — 13 Apps in 70 Days built a production crypto-payment platform — 13 apps, about 138,000 lines of TypeScript, about 1,650 tests — solo in 70 days, on the rule that when output is wrong you fix the spec, not the code, because patching code while leaving the spec untouched guarantees the same error reappears on the next regeneration; the spec is the external memory you give an agent that otherwise has none between sessions. TextForge Case Study shows the greenfield version: the first substantive commit was a 400-line CLAUDE.md with architecture diagrams and six implementation phases, and planning mode was the difference between structured thinking and chaos.

Optimizing for Decision Points adds the judgment theory underneath: the scarce resource is the handful of moments where human taste changes the direction, and the workflow's job is to surface those moments rather than drown them in review. It imports Donella Meadows' leverage-points argument — code review operates at the parameter level; the decisions that shaped what you are reading happened before any code existed. Load-Bearing Assumptions operationalises the same instinct for plans: enumerate every falsifiable assumption a plan depends on, classify each by its late-falsification cost, and verify only what would be expensive to get wrong — a falsification mindset applied to the plan itself.

Trycycle and Verbose Deployment are the loop made mechanical. Trycycle hill-climbs a plan through repeated strengthen-review rounds, each with a fresh agent so stale context never accumulates, up to five planning and eight review rounds. Verbose Deployment runs a ten-phase pipeline from inventory to production verification, each phase an independently useful, self-editing skill. The Enterprise Gap from Vibe Coding shows the same discipline demanded from the enterprise side: "prompt and hope doesn't scale past a demo," so a plain TOML plan is checked against policy before a deterministic engine executes it, with no model improvising through runtime errors.

Compound Engineering is the methodology that named the whole move — "plans are the new code" — a plan → work → review → compound loop that spends the bulk of the effort on planning and review rather than implementation. Dmitry Sotnikov's LLM Workflow is the same discipline at individual scale: have the agent emit a phased plan and a diagram, inspect the flow, then ship each piece as its own branch. Five Levels from Spicy Autocomplete to the Dark Software Factory places the destination on a maturity ladder — Level 4 is "autonomous specification," where the developer becomes a product manager writing and arguing about specs while AI handles development. Agentic Engineering at Kenn records what the durable spec becomes in production: the spec's durable parts survive the build, but they are deliberately not retained as a spec — they are converted into "living architecture documents" that serve humans and future agents. The Agentic Product Standard extends the same "spec as product" instinct to the standards layer itself, publishing a canonical standard as prose plus machine-readable skills.

Specification by surface

Prefix Effects shows that specification happens even when you think you are not specifying. Function names act as alignment surfaces that steer all subsequent generation — secure_create_user silently begets bcrypt hashing and password fields, energetic_create_user produces decorators and asyncio — so naming is not cosmetic but part of the spec, and the first code committed to a repository is disproportionately influential.

The social layer

Zero Alignment argues the productivity frame misses the point: software is a team sport, and when implementation becomes cheap the bottleneck shifts from "how do we build it?" to "should we build it?" Existing coordination tools were not designed for agentic development, and the pull request bears impossible weight as the coordination mechanism. DDD Matters More When AI Writes Your Code sharpens the human-judgment pole from the domain side: the value of a spec is that the team internalised it, so an AI-generated spec nobody read is a trap however complete it looks. speedrift-ecosystem sketches the coordination layer that would follow: a control plane that observes distributed task graphs across repositories, detects stall and drift, and separates execution from judgment — the task graph as the durable specification, the agent assignments as the disposable execution.

Where the Sources Disagree

Descriptive vs. prescriptive specs. OpenSpec defines specs as describing how the system currently behaves; Specsmaxxing insists specs describe how the system should behave and calls the descriptive stance fundamentally wrong. Structured-Prompt-Driven Development sits deliberately between, calling itself "spec-anchored" rather than spec-first or spec-only. The choice is not cosmetic: a prescriptive spec gives an executing agent pass/fail criteria and can serve as a contractual boundary between agents, while a descriptive spec is a living document that follows implementation.

Natural language vs. formal semantics. How to Write a Good Spec for Agents and Specsmaxxing treat structured markdown and YAML as sufficient for production work, with modularity and explicit boundaries as the defence against ambiguity. Rewrite All the Code All the Time argues these are intermediate forms — no more the destination than 1960s flowcharts were for programming languages — and that only formal languages with mathematical semantics can support truly automatic generation. Prompt Debt and DSPy — Programming Not Prompting occupy the middle: typed signatures and measured behaviour provide hard edges without full formal verification.

The spec author. Specsmaxxing is the sharpest voice for human authorship — "nothing beats an organic, pasture-raised, hand-written spec" — and reports that AI-generated spec writing "has never gone well." OpenSpec leans into AI-assisted generation from rough intent; AI Agents Need Clear Specs proposes a hybrid of draft → adversarial validation → human review; The AI-Native SDLC Playbook splits the difference by keeping intent.md in the originator's own words while letting the agent draft the spec from it. DDD Matters More When AI Writes Your Code warns that the disagreement is about who actually understands the spec, not who typed it.

Spec granularity. How to Write a Good Spec for Agents argues for modular, per-domain files; The Dark Factory is a DOT File presents a single pipeline file as the natural unit; Spec-First Development at Benchling argues for one unified contract; Specsmaxxing and SDDW (Spec-Driven Development Workflow) settle on one spec per feature. No source offers a framework for choosing among these, and the right answer almost certainly depends on system architecture and team size.

How much planning is worth it. Load-Bearing Assumptions and Trycycle treat heavy upfront verification as the default, while Optimizing for Decision Points warns that over-specifying trivial tasks creates decision points that cost attention without repaying it — the cost of the wrong amount of planning is not time but attention. AI Agents Need Clear Specs reconciles them with the U-curve: the optimum is task-dependent, and there is no single right density of spec.

What's Missing

Testing specs against themselves. There are tools for testing code against specs — Trycycle's review rounds, Verbose Deployment's verification phases, Load-Bearing Assumptions' assumption validators — but no general tool for checking a spec for internal contradictions, missing edge cases, or ambiguity before any code is generated. AI Agents Need Clear Specs's validation-agent pattern is a workflow, not a tool.

Spec provenance and blame. OpenSpec shows what changed; Spec-Driven Development's Plumb extracts decisions from diffs. But nobody has built the git-blame equivalent for requirements — who changed this constraint, when, and with what outcome — the loop that would make specification a falsifiable discipline. ZIL — Relational Language Embedded in Lean 4's provenance traces for derived facts are the closest existing machinery, but for relations rather than requirements.

Formal methods as an untested destination. Rewrite All the Code All the Time argues convincingly that structured natural language is an intermediate form, but no tool bridges the gap from feature.yaml or a PRD to a formal specification with mathematical semantics. Lean Software Scaling Laws proposes the experiment that could quantify the case — measuring frozen-LLM perplexity across languages — but it has not been run.

Encoding judgment in the spec. Dev Machine Foundry demonstrates the ceiling: a spec can encode what to build but not which part matters, and no source offers a mechanism for capturing taste or strategy in the artifact itself. Optimizing for Decision Points argues such judgment is precisely what cannot be delegated — but leaves open how it gets into the workflow beyond the human sitting at the decision point.

Cross-repo spec management. Current tools assume specs live within one repository. speedrift-ecosystem hints at cross-repo coordination via task graphs but does not solve spec synchronisation across service boundaries, and Specsmaxxing's dashboard has not been proven at team scale.

Machine-enforceable specs outside policy. Engineering Standards Enforcement at Cloudflare demonstrates machine-enforceable specs for organisational policy, and The Enterprise Gap from Vibe Coding's deterministic engine enforces plans — but the generalisation to continuous, in-production verification of application-level specs remains open.

Compiled from 40 sources: Stevey's Google Platforms Rant, Agent swarms and the new model economics, The Agentic Product Standard v2.0, barnstormer: Agentic Spec Builder, BESSER, Optimizing for Decision Points, How my dev machine built 1,111 word-processing features and forgot to add a ruler, How Cloudflare enforces engineering standards using AI, Five Levels from Spicy Autocomplete to the Dark Software Factory, How to Write a Good Spec for Agents, lat.md, Lean Software Scaling Laws (Summary), Manifest-Driven Development, OpenSpec, Prefix Effects, Introduction to recursive-mode, Rewrite All the Code, All the Time, SDDW — Spec-Driven Development Workflow for Claude Code, skill-load-bearing — Load-Bearing Assumptions Skill for AI Coding Agents, Software 2.0: Planning and Verifying a Greenfield Project, Something Is Changing in the Unit Economics of Software, Spec-Driven Development, Spec-Driven Development Case Study: 13 Apps in 70 Days, Solo, with AI, Fragmentation to Framework: Spec-First Development at Benchling, Specsmaxxing, speedrift-ecosystem, Structured-Prompt-Driven Development (SPDD), The AI-Native SDLC Playbook, The Claude C Compiler: What It Reveals About the Future of Software, The Dark Factory is a DOT File, The Enterprise Gap: From 'Vibe Coding' to Executable Architecture, The Plan Is the Program, The Problem Is Prompt Debt, Tom Barraclough: Sovereign AI policy and digital regulatory architecture, Trycycle, Verbose Deployment, Why AI Coding Agents Still Need Clear Specs, Write Only Code, Zero Alignment, ZIL Lean Last compiled: 2026-09-12