Spec-Driven Development: I Ran It for a Month on a Real Product (2026 Field Log)

Quick Answer: Spec-driven development (SDD) in 2026 means you write a structured spec first (goal, non-goals, constraints, acceptance criteria, and a task breakdown), then let an AI coding agent implement against that spec instead of prompting it freehand. After running SDD for a month on a live B2B product with one cofounder, my verdict is narrow and honest: it earns its overhead on greenfield features and large multi-file refactors, and it is pure ceremony on small edits and exploratory spikes. The spec is a real artifact you maintain, not a throwaway prompt.

I am a backend dev. I do not enjoy writing documents. So when the GitHub Spec Kit toolkit and the whole spec-driven-development idea blew up across my feed in mid-2026, my first reaction was that it was ceremony dressed up as methodology. Then I actually ran it for a month. This is the field log: where it paid for itself, where it wasted my afternoon, and the exact spec shape that survived.

What SDD actually is, in one paragraph

Every explainer says the same thing, so here is the short version. In classic AI-assisted coding, the code is the source of truth and the prompt is disposable. In spec-driven development you flip that: a structured specification becomes the primary source of truth, and the agent generates code, tests, and docs against it. Martin Fowler's team has a good tool-by-tool breakdown of the pattern across Kiro, Spec Kit, and Tessl if you want the theory (Martin Fowler, 2026). The point I care about: the spec is meant to be maintained, reviewed, and re-run, not written once and forgotten.

The setup I ran for a month

Nothing exotic. An existing Next.js + Postgres repo, a B2B agent product, two people. I used Spec Kit's /specify and /plan flow feeding into a coding agent, and for a week I also tried Amazon's Kiro to see if a spec-native IDE changed the math. Same underlying idea, slightly different ergonomics.

I tracked one thing across every task: did writing the spec save me more time than it cost, or not. No vibes, just a note per task. After ~30 tasks the pattern was obvious.

Where SDD earned its overhead

Three situations where I would now reach for a spec every time.

Greenfield features. A new "usage-based billing" surface touched the schema, three API routes, a background job, and the UI. Writing the spec forced me to name the non-goals ("no proration in v1") before the agent invented them. The agent's first pass was boring and correct, which is exactly what you want for money code.

Large multi-file refactors. Moving our auth from a homegrown thing to a library was the strongest case. The acceptance criteria doubled as a regression checklist. When the agent drifted, I pointed at the criterion it broke instead of re-explaining the whole change.

Handing off an unfamiliar area. My cofounder specced a queue change in a service I own. I could review the spec in five minutes and catch a wrong assumption before a single line was written. The spec was a cheaper review surface than a PR.

The through-line: SDD wins when the change is bigger than what fits in one person's head, and when being wrong is expensive.

Where it was pure ceremony

And three where it actively slowed me down.

One-line and one-file fixes. Writing a spec for a null check is a joke. By the time I described the acceptance criteria I could have made the change twice.

Exploratory spikes. When I do not yet know what I am building, a spec is a lie I have to keep rewriting. Spikes want vibe coding, not specs. I wrote about where that freeform mode helps and where it quietly makes you worse in an earlier field log on vibe coding, and SDD is basically the opposite tool for the opposite job.

Changes I already hold in my head. If I can see the full diff before I start, the spec is transcription, not thinking. I skip it.

The spec structure that actually survived

Most templates online are too heavy. I stripped mine down to six headings and stopped there:

• Goal: one sentence, outcome not implementation.
• Non-goals: the single most valuable section. This is where you stop the agent from gold-plating.
• Constraints: stack, existing patterns to follow, things not to touch.
• Acceptance criteria: a checklist, phrased so each item is testable.
• Task breakdown: the agent proposes this, I edit it. I do not write it from scratch.
• Open questions: anything unresolved goes here instead of getting silently decided by the model.

If a section is empty, I delete it. A spec that is longer than the diff it produces is a smell.

Three failure modes nobody warns you about

Spec drift. The code moved, the spec did not, and two weeks later the spec was actively misleading. If you are not going to update it, delete it when the feature ships. A stale spec is worse than no spec because people trust it.

Over-specifying. The first week I wrote specs so detailed they were just the implementation in prose. That is not spec-driven, that is writing the code twice. The spec should constrain the solution space, not draw the whole picture.

Review fatigue. Reviewing a spec, then a plan, then the diff is three review passes. On big changes that is worth it. On medium ones you will start rubber-stamping, and a rubber-stamped spec gives you false confidence. Reserve the full ritual for the changes that deserve it.

The rule I run now

One line, on a sticky note: write a spec when the change is bigger than my head; skip it when it fits in my head. Everything above is just the long version of that sentence. SDD is a real tool in 2026, not a fad, but it is a specific tool for big, expensive, unfamiliar changes. Treat it as universal and you will spend more time writing specs than shipping.