Spec-Driven Development: The GSD Way

Every developer has the same origin story for their worst project. You open your editor, start typing, get halfway through, realize the data model is wrong, tear it apart, rebuild it, then discover the API you designed doesn't actually support the main use case. Two days gone. The feature should have taken four hours.

I used to do this constantly. Then I started writing specs first, and the rework dropped to almost zero. Not because specs are magic -- they're not. But because spending twenty minutes thinking about what you're building before you build it turns out to be ridiculously effective, especially when your executor is an AI coding agent that takes your spec literally.

This post covers GSD (Get Shit Done), a spec-first workflow I use for solo development with AI agents. It's not a framework or a product -- it's a set of conventions that make AI-assisted development predictable instead of chaotic.

What is GSD?

GSD is a methodology built around one idea: specs are prompts. When you're working with an AI coding agent, the quality of your spec directly determines the quality of the output. A vague spec produces vague code. A precise spec produces precise code.

The core loop is simple:

Plan means writing a spec -- not a vague todo list, but a structured document with objectives, tasks, file paths, and verification criteria. Execute means handing that spec to an AI agent (or doing it yourself). Ship means deploying. Learn means looking at what went well or sideways and folding that back into your next spec.

The key insight: most of the value comes from the Plan step. If you get the spec right, execution is almost mechanical. The AI agent reads the spec, follows the tasks, verifies against the criteria, and commits. You review the output instead of babysitting every keystroke.

The Spec-Driven Core

Here's the thing about specs that people get wrong: they think a spec is documentation. It's not. Documentation describes what was built. A spec describes what will be built, in enough detail that someone (or something) can build it without asking clarifying questions.

When your executor is an AI agent, the spec IS the code. Not literally -- the agent still writes the implementation. But the spec is the authoritative source of truth for what the code should do. The agent translates your spec into an implementation the same way a compiler translates source code into machine instructions.

This changes the economics of planning. In traditional development, specs have diminishing returns because the person writing the spec is also the person writing the code -- they already know what they mean. But when you're handing off to an AI agent, every ambiguity in your spec becomes a coin flip in the implementation. Precise specs eliminate coin flips.

The ad-hoc path looks shorter on paper. In practice, those "hit problem → rewrite" cycles eat more time than writing the spec ever would. The spec-driven path has a higher upfront cost and a dramatically lower total cost.

Anatomy of a Good Spec

Not all specs are created equal. A spec that says "add authentication" is barely better than no spec at all. A good spec is executable -- it contains enough detail that an agent (or a developer) can complete the work without making judgment calls about intent.

Here's what makes a spec executable:

Objective -- What you're building and why. Not just "add auth" but "add JWT authentication so users can access protected API routes." The "why" matters because it helps the executor make good decisions when edge cases arise.

Tasks with file paths -- Each task specifies what to do and where. Not "create the auth module" but "create src/middleware/auth.ts with JWT verification using the jose library." File paths eliminate ambiguity about project structure.

Verification criteria -- How you know it's done. Automated checks that can run without human judgment: "all tests pass," "build succeeds," "endpoint returns 200 with valid token." If your verification requires someone to eyeball it, it's not verification -- it's a hope.

Must-haves derived goal-backward -- Start from the goal and work backward to figure out what has to be true for the goal to be met.

This goal-backward approach catches missing pieces before you start building. If you can't trace a path from every truth to an artifact to a wiring step, something is missing from your plan. Better to discover that gap at spec time than at 2 AM when the deploy fails.

The Workflow in Practice

A real GSD workflow goes through several phases before code gets written. Each phase narrows uncertainty so the execution phase has fewer surprises.

The discuss phase is where you figure out what you actually want. Not "I need search" but "I need client-side full-text search over blog posts, using an index generated at build time, with fuzzy matching." That level of clarity emerges from conversation, not from staring at a blank spec template.

The research phase is where the AI agent explores your codebase to understand what already exists. Maybe you already have a utility that parses blog frontmatter. Maybe your build pipeline has a hook where index generation could slot in. This research feeds directly into a better spec.

The plan phase produces the spec. By this point, you've discussed the requirements, researched the constraints, and you're writing a plan grounded in your actual codebase rather than wishful thinking.

The execute phase is where the spec pays off. The AI agent picks up each task, knows exactly which files to create or modify, and has clear verification criteria. No guessing, no "what did you mean by this?"

Why This Beats Winging It

Beyond the obvious "less rework" benefit, spec-driven development has some structural advantages that compound over time.

Context efficiency. AI agents have limited context windows. A clear spec gives the agent exactly what it needs -- objective, file paths, verification criteria -- without burning tokens on ambiguity resolution. I've watched the same feature take 3 agent turns with a good spec versus 12 turns with a vague one.

Parallel execution. Independent specs can run simultaneously. If your feature has three independent pieces -- a database migration, an API endpoint, and a UI component -- you can write three specs and have three agents execute them in parallel.

Wave 1 runs three plans at the same time because they don't depend on each other. Wave 2 waits until Wave 1 finishes, then wires everything together. This wave-based execution is only possible when your plans are explicit about their dependencies.

Verification is built in, not bolted on. Every spec includes verification criteria that run automatically after execution. You don't have to remember to test -- the spec defines what "done" means, and the agent checks it before marking the task complete.

Reproducibility. A spec is a record of what was intended. When something breaks six months later, you can read the spec to understand the original design intent, not just the code that was produced. This is especially valuable when the code was written by an AI agent -- the spec captures the reasoning that the generated code doesn't.

Making It Work

If you're thinking about adopting spec-driven development, here's the practical advice: start small. Don't try to spec out your entire application architecture on day one. Pick one feature. Write a spec for it. Hand it to an AI agent. See what happens.

The first few specs will be too vague. You'll discover that "implement the search feature" is not a spec -- it's a wish. But you'll notice exactly where the agent gets confused, and those confusion points become the things you learn to specify better next time.

After a few iterations, something clicks. You start thinking in specs naturally. The twenty minutes you spend writing a plan stops feeling like overhead and starts feeling like the most productive part of your day. Because it is.

That project you rewrote three times? It's the project where you didn't write a spec. The one that shipped on the first try? That's the one where you spent twenty minutes thinking before you typed a single line of code.

Specs aren't overhead. They're leverage.