it's me, a dev

The Spec Is the Deliverable. The Code Is Build Output.

Mon, 08 Jun 2026 00:00:00 GMT

Here's the claim, and I'll defend it the rest of the way down: when you're building with an AI in the loop, the spec is the artifact that matters. The code is build output. Treat it that way and a lot of the second-order problems with AI-assisted development get quieter. Treat it the old way (code as the source of truth, spec as the thing you wrote once for the kickoff deck) and you're going to have a bad time about six months in.

I know how that sounds. Bear with me.

What I mean by "spec"

Not a Word doc. Not a Confluence page that nobody updates. I mean a living, precise, markdown-shaped description of what the system does, what it doesn't do, what the invariants are, what the failure modes look like, and how you'd know it was broken. The kind of thing that, handed to a competent dev team, lets them rebuild the thing without playing twenty questions with you. Detailed enough to generate from. Detailed enough to test against. Detailed enough that you'd notice if it was wrong.

Most teams don't write that document. They write something shorter and call it a spec, then let the code drift, and the code becomes the only truthful description of the system. That's been a problem forever. AI just makes the problem more obvious, and a lot more expensive to ignore.

Why this matters more with AI in the loop

The old workflow was simple: spec is approximate, code is precise, code wins. Fine. A senior dev reads the code, reconstructs intent, makes the change. Slow but honest.

The new workflow is different. You prompt, the model writes, you review, you ship. The code is now downstream of two things: the prompt and the model. Change either one and the code changes. So what's actually persistent across the project? Not the code. The code is a snapshot of what the model produced for a particular prompt on a particular Tuesday. The thing that persists, the thing you can hand to another dev (or to another model in eighteen months) and get something equivalent back, is the spec.

Code becomes a build artifact. The spec becomes the source.

Right? It feels backwards. Let me earn it.

The honest concession, up front

The strongest argument against everything I just said: LLM output is non-deterministic. If I regenerate from the same spec tomorrow, I get similar code, not identical code. So the tested, reviewed code in the repo is the real source of truth, because that's the only artifact you can actually prove things about. The spec is just a wish.

That argument is correct. I want to be very clear about this, because I've seen people get themselves in trouble pretending otherwise. You will sometimes hear "specs make regeneration almost deterministic." That phrase is doing a lot of work, and most of it is bad work. The gap between "deterministic" and "almost deterministic" is exactly where the silent failures live: the small percentage of regenerated code that's subtly different, ships unreviewed, and breaks something in production three weeks later. "Almost deterministic" is a comfort phrase. Delete it from your vocabulary.

So I'm not claiming the spec lets you regenerate the system on demand. I'm claiming something narrower and, I think, more useful.

A bigger caveat while I'm being honest. I haven't run this on a real client engagement yet. The four projects I'm drawing on are private, small-to-medium things I built on my own time. It works surprisingly well at that scale, well enough that I'm writing this post about it, but I want you to weight the evidence accordingly. I'm telling you what I've seen, not what I've shipped to a paying customer with an SLA. The shape of the argument should hold under client conditions (the failure modes I'm describing get worse at scale, not better, which means the discipline matters more, not less) but I haven't proven that, and I'm not going to pretend I have.

With that on the table: the stability I got out of AI-assisted coding did not come from the spec magically reproducing the code. It came from senior judgment. Mine. Encoded as specs. Enforced by TDD. Backed by code review I'd have done anyway. The spec wasn't a substitute for that judgment. It was the format I used to encode it so the AI could play along.

So the defensible version of the claim is this. Disciplined senior practice makes AI output stable, and the spec is the artifact that carries that discipline through the handoff. The generated code gets regenerated at dev time, reviewed hard, then frozen and version-pinned at handoff. Nobody regenerates code in production. (If your CI is calling out to Claude to rebuild a service, we need to have a different conversation.)

The spec is not a regeneration button. It's the thing that means the code in the repo isn't an illegible black box six months from now.

Where this earns its keep: POCs and MVPs that don't stay POCs

I want to scope this honestly. I'm talking about POC and MVP work. Greenfield. Small teams. Tight loops. This isn't a claim about refactoring a fifteen-year-old monolith. That's a different problem and probably a different post.

But here's the thing about MVPs: a lot of them are lying about being MVPs. The "throwaway prototype" gets a customer. The customer pays. The thing is now load-bearing, and nobody is going to give you a three-month rewrite window to do it properly. You're maintaining the prototype now. Congratulations.

This is where the spec earns out. When the MVP quietly graduates to production (which is most of the time, in my experience) the receiving team inherits two things. They inherit the code, which the AI wrote and which a senior reviewed. And they inherit the spec, which describes what the code is supposed to do, what invariants matter, and what the tests are protecting. Without the spec, all they have is a pile of plausible-looking TypeScript and a prayer.

To be clear about the handoff audience: I'm not claiming the spec is something you hand to a non-technical client. The client gets demos and outcomes. The spec is for the dev team who picks it up next. People who can read a precise document and act on it. That's a real audience, and it's underserved.

What this looks like in practice

Light on the tooling, because the argument doesn't depend on it. But for grounding: markdown specs in the repo, alongside the code, version-controlled together. Tests written from the spec, not the implementation. Code generated with Claude or Cursor against the spec and the tests. Review with the assumption that the AI is a fast junior who sometimes lies confidently. Freeze at release, pin the model version in the spec metadata if you regenerated anything material, and move on.

The discipline isn't exotic. It's stuff senior devs already do. The only real shift is where you spend your effort. You spend it on the spec and the tests, because that's the leverage point. You spend less on the code itself, because the code is, increasingly, a derivable output.

Vibe coding, briefly

I should say what I'm not arguing against. "Vibe coding" has a literal version (don't read what the AI produced, just ship it if it runs) and I think that version is bad and will hurt you. But people also use "vibe coding" to mean any iterative, conversational, prompt-driven workflow, and that's fine. That's actually good. I do that. The difference is whether there's a spec underneath the conversation, anchoring it. Prompt iteratively, sure. Just have something durable to iterate against.

The thing I genuinely don't know

Here's where I get to be uncomfortable in public. I cannot yet tell you whether any of this works for someone who isn't a senior architect.

My honest worry is that the engine here is judgment, and the spec is just how I serialize my judgment. If that's true, then a less experienced dev with the same workflow gets faster, more confident slop. Output that looks like mine but isn't load-bearing in the same way, because the spec they wrote doesn't encode the right invariants. They didn't know which invariants to encode.

I'm credible on the rest of this post precisely because I've been both the decider and the implementer on these projects. That's also why I can't answer this question yet. I can't separate "this works" from "this works when I do it." I haven't run the experiment where I hand the method to a mid-level dev and watch what happens over six months without me in the loop. (And honestly, I haven't run it on a real client engagement either, which is the other shoe I'm waiting to drop.)

That's what I'm watching for next. Whether the spec is a vehicle for judgment or a substitute for it is the question that decides whether any of this scales past the people who already know what they're doing. I have a guess. I'd rather not publish it until I've seen it.

Until then: write the spec. Treat the code as build output. Don't regenerate in production. And be honest with yourself about who, exactly, is the source of the stability.

I Built This Blog With AI. Here's What Actually Mattered.

Sat, 30 May 2026 00:00:00 GMT

The blog you're reading was built almost entirely by an AI. I want to tell you how, because the interesting parts weren't the ones I expected — and because I keep making a particular claim: that the spec is the deliverable and the code is build output. It would be a little rich to make that claim and then not show the work.

So here's the work, including the parts where the AI was confidently wrong.

I wrote the spec first, and then I got interrogated

I started with a spec.md: purpose, scope, stack, a content model, routing, invariants, failure modes, and a "how done is verified" checklist. Opinionated, with explicit non-goals. Then, instead of asking the AI to build it, I asked it to grill me on it.

That was the first surprise: the most valuable hour was the one before any code existed. The AI walked the design tree one decision at a time, each with a recommendation, and it kept finding places where the spec contradicted itself or had quietly gone stale. It referenced a design.md that didn't exist. It assumed a sample post that wasn't there. And the stack table was written against tooling idioms that had already moved on — the spec wanted an older Tailwind and an older Astro content-collections API, both superseded. The AI checked the current docs and re-grounded the spec against today's reality.

None of that was code. All of it was the spec getting sharper. By the time we wrote a line, the spec was internally consistent and matched the tools that actually exist now.

The spec stayed the source of truth — because reality kept attacking it

Here's the part I find most convincing in hindsight. The spec didn't survive contact with the build unchanged. It survived because every collision got written back into it.

A few examples:

The spec had an invariant: the production image must be under 50 MB. Halfway through, the base web-server image we'd specified had quietly bloated to 92 MB. The invariant caught it — not me, not the AI's good intentions, the invariant — and we switched to a slim variant and landed at 22 MB. A constraint I'd written months earlier caught a regression in a dependency I didn't write.
A library version I'd pinned didn't exist. The package manager had started silently skipping build steps that the image actually needed. The pagination URLs the spec described weren't the ones the framework produces.

Each of these was a small lie the spec told about the world. Each one got corrected in the spec, not just patched in the code. That's the discipline I keep coming back to: the code drifts, and the spec is where you record what you learned so the next person (or the next model) doesn't relearn it the hard way.

The AI lied to me. Confidently. More than once.

There's a failure mode people don't talk about enough: "almost deterministic" output — the small fraction that's subtly wrong, ships unreviewed, and breaks something later. I got to watch it up close, on my own project.

The AI "verified" the custom 404 page by searching the output for the string 404. That string appears in both my page and the web server's built-in error page. False positive. It reported success. The page was fine, as it happened — but the check was worthless, and it took a second look to notice.
It tested against a stale container image and briefly turned a non-bug into a "bug."
It wrote a health check that pinged localhost, which resolved to IPv6, which the server wasn't listening on. Confident, plausible, broken.

Every one of these was caught the same way: by running the thing. Curling the endpoint. Inspecting the container's actual health status. Building the image fresh. Not by the AI's say-so, and not by mine reading the diff and nodding. The verification is the tax that turns "looks right" into "is right," and there is no skipping it. An AI that can produce a plausible check is also an AI that can produce a plausibly wrong one.

The four times I said no

If the AI was the implementer, the judgment was still mine, and it showed up mostly as refusals.

The about page contradicted itself. The draft described me as "an architect who still writes the code" — on a blog whose entire thesis is that the AI writes the code now. I caught it; we rewrote it to something truer: I stay in the code and I'm on the hook for the result, whether I typed it or reviewed it.
A config change almost touched the wrong scope. A git identity tweak that should have been local to this repo — I stopped to confirm it wasn't global before letting it through. It was local. I was still right to check.
The trademark line. I wanted the site to be playful about its domain pun. The AI's job was partly to draw the line: embrace the spirit, not someone else's intellectual property.
The privacy calls. Keep my CV out of the repo. Generalize client work for confidentiality. Use an alias address, not my personal one. The AI flagged these; I decided them.

A guardrail also flat-out refused to rewrite published history until I explicitly authorized it. I was glad it did.

What I still can't tell you

Now the caveats, because I'd rather state them than have you find them. This is one small, low-stakes, greenfield project — a personal blog, not a system with an SLA. A few of the "done" checks are still unrun: I haven't put it through a real performance/accessibility audit or validated the feed against an external validator; the structure is built to pass both, but built-to-pass and verified-as-passing are different claims, and I know better than to conflate them.

And the honest meta-point: I can't fully separate "this worked" from "this worked when I did it." I knew which invariants to write, which contradictions mattered, when the AI was bluffing. The spec was where I encoded that judgment so the AI could play along. Whether someone without that judgment gets the same result, or just faster, more confident slop, is the question I genuinely don't know the answer to.

But as a demonstration of the claim, this'll do: the code here was mostly machine-written, and it's not a black box, because the spec next to it says what it's supposed to do and why. Treat the code as build output. Keep the spec honest. And run the thing before you believe it.

Update (2026-06-08): I've since written the underlying argument up on its own — why the spec, not the code, is the artifact that lasts: The Spec Is the Deliverable.