Spec-Driven Development: How We Use AI Without Gambling Your Budget

Jeffy Susan October 21, 2026 0 comments

The demo worked. Then somebody had to own it.

If you’ve been near software this year, you’ve seen one. Somebody opens a laptop, types a few sentences into an AI tool, and twenty minutes later there’s an app on the screen. It has a login page. It has a dashboard. The buttons do things. Everyone in the room is impressed, and honestly, they should be.

Then the questions start. What happens when two people edit the same record? Who decided the chatbot should answer pricing questions? Which version of this is the one we’re paying for? And nobody can answer, because there’s nothing to check the app against. There’s a chat history, and the chat history is the only record of what anyone wanted.

That’s the gap this post is about. We’ve built software for clients since 2002, and we build with AI every day now. What we won’t do is build a client’s product without a written spec. Here’s what that spec looks like, and why it’s the part of the project that saves you money.

What we mean by a spec

Two definitions first, in plain words, because both terms get stretched.

Vibe coding is prompting an AI until something seems to work, with no written plan and very little reading of the code it produces. Andrej Karpathy coined the term in February 2025, and the OpenSSF security glossary puts the line in a sensible place: if a human reviews the AI-generated code, it isn’t vibe coding anymore.

Spec-driven development is the opposite order. You write down what the software must do, and how you’ll prove it does it, before anyone (or anything) writes code. The AI then builds against that document. GitHub thinks the idea is solid enough that it published Spec Kit, an open-source toolkit built around exactly this flow: specify, plan, break into tasks, implement.

A spec isn’t an 80-page requirements binder (we’ve written those, in the 2000s, and nobody read them). Ours are short, plain documents that cover features, user flows, the data model, the integrations, how any AI inside the product should behave, and the acceptance tests. Here’s a trimmed section from the kind of spec we’d write for a support assistant on a store. It’s an illustration, not a client document.

 

Notice what’s in there. Two rules say what the AI must not do. That’s the part a prompt almost never contains, because nobody thinks to ask for it until a customer gets a refund figure the chatbot made up.

Acceptance tests are where “done” gets written down

Most arguments on software projects aren’t about code. They’re about whether something is finished. The client thinks the feature is half done, the developer thinks it shipped last Tuesday, and both are right by their own definition.

Acceptance tests end that argument before it starts. Each one states a situation, an action, and the result you’ll accept. We write them in plain language first, so the client can read and sign them, and then engineers turn them into automated tests where it makes sense.

 

AT-03, AT-05 and AT-06 are wrong-answer tests. They check what the AI does when it shouldn’t answer. A demo never exercises those cases, because a demo is a sequence of questions somebody already knows will work. A product gets asked everything.

How a spec-driven build runs at Macronimous

This is the order every client build follows here, whether it’s a new AI app, an AI feature inside an existing Magento or WordPress store, or one of the workflow automations we build for operations teams.

1. The client brings what they have. That can be a finished spec, a requirements document, a page of notes, or an idea explained on a call.
2. We turn it into a build-ready spec. If the client sent one, we review it and send back a gap list. Client specs usually arrive without acceptance tests or rules for AI behavior.
3. Senior engineers build against the spec with AI coding tools, Claude Code among them. The spec decides what gets built. The tool doesn’t.
4. An engineer reads every AI-written change and runs it against the acceptance tests before it goes in.
5. The spec stays with the client, in the client’s repository, as a working document.

That last step matters more than it looks. When you add a phase next year, or move the work to another team (it happens, and we’d rather you could), the next people start from facts. They don’t start from a chat log and a guess.

I hold myself to the same order. I built TheTamilBible.com, a PHP and MySQL web app you can install like a phone app, with Claude Code. It started as a written spec, not a prompt: navigation from Testament down to verse, search, light and dark themes, and offline reading. The AI wrote most of the code. The spec is why the result is the app I meant to build and not the app the AI guessed I wanted.

We’ve written separately about the review discipline behind step four, which we call controlled AI coding.

Why the spec is the real cost saver

AI made code cheap. That’s real, and anyone who tells you otherwise is protecting an hourly rate. A screen that took two days now takes an afternoon.

But cheap code moves the expensive mistake somewhere else. The costly thing used to be writing the code. Now it’s building the wrong thing quickly, discovering it in month three, and paying to unpick features that three other features already depend on. Speed doesn’t help you there. It just gets you to the wrong place sooner.

The spec also changes how you pay. Once it’s locked, we can send a fixed-price proposal priced line by line against it, so the scope and the price live in the same document. Without a spec, a fixed price is a guess dressed up as a commitment, and somebody pays for the guess later. Usually the client.

Security is the other cost that hides until it doesn’t. Veracode’s 2026 GenAI Code Security Report found the models it tested passed its security tests 56 percent of the time on average, barely better than a year earlier. I don’t read that as “AI writes insecure code, so avoid it.” I read it as: unreviewed AI code needs something to be checked against. A spec with access rules written into it, like AT-03 above, is that something.

Where vibe coding still wins

None of this means vibe coding is wrong. I vibe code myself, and I’d be lying if I said otherwise. It’s the right call when:

• You’re testing whether an idea deserves a budget at all. A rough prototype answers that faster than any meeting.
• You’re building an internal tool that a handful of people use, that touches no money, and that nobody will mind rebuilding.
• You want to show a developer or an investor what you mean, in place of describing it.
• You’re learning. Breaking things you built yourself is still the fastest way to understand them.

The line is simple. Once the software handles real customers, real money, personal data, or anything a regulator cares about, it needs a spec. We wrote up where that line fell on one of our own builds in “Is Vibe Coding Bad?”, if you want the longer version.

And a vibe-coded prototype is a fine place to start a spec. It’s a sketch. We’ll happily write the spec from it.

Vibe coding vs spec-driven development

Question	Vibe coding	Spec-driven development
What is the build checked against?	The builder checks whether it seems to work.	The engineer checks it against written acceptance tests.
Who defines “done”?	Nobody writes it down.	The client signs the tests that define it.
What happens to AI behavior rules?	They exist only if someone remembered to prompt them.	The spec lists them, including what the AI must refuse.
Can the price be fixed?	A fixed price is a guess.	The price is set line by line against the locked spec.
What does a new team inherit?	The new team inherits code and a chat history.	The new team inherits code and the document that explains it.
Where does it fit best?	It fits prototypes, experiments and small internal tools.	It fits products that real customers and real money depend on.

Is your spec ready? A short checklist

If you already have a spec, run it against this list before you send it to any team, us or anyone else.

• Every feature names the user who uses it and what that user is trying to do.
• The data model lists each record type and who can read or change it.
• Every integration says what happens when the other system is down or slow.
• Any AI feature lists its sources, and what it must refuse to answer.
• Each feature has at least one acceptance test written as given, when, then.
• At least one test per AI feature checks a wrong or unanswerable question.
• The spec states what is out of scope for this phase.

FAQ

Where that leaves you

Use AI to write the code. We do, every day. Just don’t let it decide what the code is for. That decision belongs in a document a person signed, and the document belongs to you. If you’ve run a spec-driven build with a different structure that worked better, I’d like to hear about it.