Spec-driven development

When software ships with its source, extending it is your right. The question is how to use that right without wrecking what you own. More and more of that extension work is done with AI assistants — you describe, it writes. Done well, this is the biggest productivity gift operators have ever been handed. Done badly, it produces something new and awful: a system nobody can describe.

The difference is one habit: write the spec first.

The failure mode

The tempting workflow is conversational: ask for a feature, run what comes back, describe what's wrong, repeat until it seems to work. It feels fast. But notice what you have at the end: code that passes the tests you thought to poke at, shaped by a conversation nobody will ever read again. What is it supposed to do? What must it never do? The only honest answer is "whatever it currently does." That's not software you own. That's software you're adjacent to.

The industry has a name for the failure — vibe coding — and the fix is older than the assistants: say what you want before you build it.

What a spec is

A spec is not a requirements document. For an extension, it's half a page with four headings:

Intent

one sentence on why this exists.

Add a "download as GeoJSON" button for the parcels layer.

Behaviour

what it does, observably.

Exports currently visible parcels; file named area-parcels-date.geojson; opens in QGIS.

Constraints

what it must never do.

Touches no model state. No new dependencies. Never blocks the UI. Never exports hidden layers. Existing export paths unchanged.

Verification

how you'll know, before you trust it.

Button appears only when parcels are loaded; exported file re-imports cleanly; every existing export still works.

Ten minutes of writing. Notice the constraints section — it's the one the conversational workflow never produces, and it's where owned systems get quietly broken.

Why this works with assistants

A spec does triple duty. It's the instruction — assistants are dramatically better when told what "done" and "never" mean, because they can check their own work against something. It's the test list — Verification is your acceptance tests, written before the code could argue back. And it's the documentation — six months later, the spec says what this thing is for, which the code never will.

There's a compounding effect too. Specs live in the repo. The next assistant — next week's session, next year's, or a contractor's — reads them and inherits your intent instead of reverse-engineering it. A repo full of specs is navigable by anyone. A repo full of vibe-coded features is navigable by no one, including its author.

Start today

You don't need tooling. A specs/ folder and the four headings. Refuse to let anything merge that can't point at its spec. That one rule is most of the discipline — and it's the difference between owning your extensions and merely having them.