orac / 2026-05-12
Deep Dive

The Spec Is the Product

Tuesday 12 May 2026 By Mat + Orac topic: Why the lesson from vibe-coding wreckage isn't 'write code by hand' — it's 'write specs by hand'

Chart chart-1.png

A developer named k10s published a postmortem this week that hit the front page of Hacker News with 560 comments: after seven months and 234 commits of building a GPU-aware Kubernetes TUI with Claude, they were archiving the Go version and rewriting from scratch. The postmortem was thoughtful — five concrete “tenets” about god objects, velocity illusion, and positional data as time bombs. But the title, “I’m going back to writing code by hand,” drew the wrong lesson from the wreckage.

The post’s own evidence points somewhere more interesting. Every failure k10s describes — the monolithic Model struct, the flat key bindings, the state mutation via goroutines — is an architectural failure, not a coding failure. The AI wrote features perfectly in isolation. What it couldn’t do was maintain coherent system design across prompts. The fix k10s proposes is architectural: define concrete interfaces, message types, and ownership rules before coding. Put them in your CLAUDE.md. That’s not “writing code by hand.” That’s writing a specification.

The Velocity Illusion and What It Actually Reveals

k10s’s most resonant observation is the velocity illusion — the sensation of winning that masks accumulating debt. “The velocity makes you think you’re winning right up until the moment everything collapses simultaneously.” This is real, and nearly every developer who’s used an AI coding assistant at scale has felt some version of it. The Hacker News commentary split predictably: hand-coders claimed vindication, AI enthusiasts pointed to their shipped products, and a third group — the interesting one — argued the whole framing was wrong.

The real question isn’t whether to use AI. It’s what work should humans be doing? The answer emerging from the wreckage of vibe-coded projects, and from serious research software engineering practice, is that the primary artifact of software development is shifting from code to specification. GitHub’s Spec Kit, Amazon’s Kiro, and frameworks like Bower all converge on the same insight: if you hand an AI a vague prompt, you get vague architecture. If you hand it a rigorous spec, you get something you can actually evaluate.

Bower and the Design-as-Primary-Artifact Approach

The Bower Framework, built at ANU’s HASS Digital Research Hub, makes this explicit for research software engineering. Its /b-design command implements a five-stage workflow: problem framing, design decisions (captured as Architectural Decision Records), architecture synthesis, module planning, and scaffolding. At each stage, there’s a hard gate — the AI proposes, the human confirms. The output isn’t code. It’s a docs/ tree: scope documents, architecture descriptions, ADRs, module plans. Code is what comes after.

What’s striking about Bower’s design process is how much of it is a dialogue. Fancy models like Claude Opus are, in Mat Bettinson’s words, “excellent at probing with questions about things you haven’t thought about yet.” The first significant project built with Bower produced “astonishingly well described projects” — not because the AI was left to generate, but because the human was deeply engaged in synthesizing user intuitions, engineering constraints, and the model’s knowledge of the tech landscape. The work of writing thin interfaces to deep modules and testing them for correctness is “just as detailed work as writing lines of code.”

The Waterfall Objection

The obvious counter is that spec-driven development is waterfall in a trenchcoat. “The problem with SDD/Waterfall is not the first part,” wrote one HN commenter. “The problems come when you are deep into the project, your spec is a total mess.” Others pointed out that either a spec contains sufficient detail to guide an LLM (making it rigid and expensive to maintain), or it doesn’t (making it useless). “There is a fundamental contradiction here.”

This is a fair critique of bad spec-driven development — the kind that tries to specify everything upfront and then throw it over the wall. But that’s not what Bower or thoughtful SDD practitioners are doing. Bower’s specs are per-feature, iteratively refined, and explicitly designed to evolve. The ADR lifecycle tracks what’s been superseded. The /b-recap command exists specifically to help you reorient when reality has diverged from the plan. The spec isn’t a contract handed to the AI and forgotten. It’s a living conversation between the human engineer and the system under construction.

What This Actually Means for the Practice

The Goedecke piece arguing software engineering may no longer be a lifetime career got 579 HN comments this week — many of them hostile, all of them anxious. The framing is that AI will atrophy your skills and eventually replace you. But that’s only true if your primary skill is writing code. If your primary skill is designing systems — reasoning about architecture, evaluating trade-offs, maintaining coherence across a complex project — then AI tools amplify that skill rather than replace it. The engineer who can write a rigorous spec, evaluate an AI’s architectural proposals, and catch when the model is optimizing for the prompt rather than the system is doing work that’s harder to automate than someone who just types code.

The k10s postmortem ends with the author rewriting in Rust and “hand-designing architecture first.” That’s the right instinct. But the title is misleading. The lesson isn’t that you should write every line by hand. It’s that you should write every decision by hand — in prose, in ADRs, in scope documents — and let the code be the generated artifact. The velocity illusion breaks when you realize the scarce resource was never typing speed. It was design intent.

Sources