Spec-Driven Development

The plan-then-execute pattern hints at something bigger. Taken seriously, "write the plan first" becomes a full, tool-independent workflow: spec-driven development. It's the durable evolution of "Plan mode" — and it scales far past a single prompt.

The idea

📜 Write the specification first. Make the spec the source of truth. Have the agent implement against it — and verify the code back against it.

Instead of describing a feature in a throwaway chat message and hoping the agent guessed right, you produce a durable artifact — a spec — that says what to build and how you'll know it's done. The agent builds to that spec; you review against that spec.

Why it works so well with agents

• 🎯 Removes ambiguity up front. Most bad AI output traces to an underspecified request. A spec forces the decisions before code exists, when they're cheap to change.
• 🔍 Turns review into spec-checking. Reviewing 400 lines of AI diff line-by-line is exhausting and error-prone. Reviewing "does this satisfy the spec?" is faster and catches the errors that matter — the semantic ones. (This is the heart of Verifying AI Output.)
• 🔁 It's re-runnable. If the implementation is wrong, you fix the spec and regenerate — rather than patching a mystery diff.
• 👥 It's shareable. A spec is reviewable by teammates who'd never read the raw diff.

A lightweight flow

1. Draft the spec. Goal, acceptance criteria, constraints, out-of-scope. Often you co-write it with the AI ("ask me clarifying questions, then draft a spec").
2. Review & approve the spec — this is where you spend your judgment, before any code.
3. Agent implements against the spec — feed the spec in as context; let it build.
4. Verify the implementation against the spec — does each acceptance criterion hold? Tests pass?
5. Iterate on the spec, not the diff — when something's off, update the spec and regenerate.

Guard against spec–code drift

The main failure mode: the code evolves, the spec doesn't (or vice versa), and they quietly diverge. Defenses:

• ✍️ Keep the spec in the repo, versioned alongside the code (a specs/ folder, or a design doc per feature).
• 🔗 Reference the spec from the PR; update it in the same change when behavior changes.
• ✅ Encode acceptance criteria as tests where possible — an executable spec can't silently drift from the code.

Tooling — one example, not a requirement

The workflow is tool-agnostic — you can do it with a Markdown file and any agent. If you want structure, GitHub Spec Kit is one open, model-agnostic toolkit for spec-driven development worth knowing. Treat it as an example of the pattern, not the pattern itself — the discipline (spec first, implement against it, verify against it) is what's durable.

Bottom line: for anything beyond a trivial change, the plan/spec is the work. Get it right and the code is almost a formality the agent fills in; get it wrong and no amount of clever prompting saves you.

Next: how tools get external context and capabilities → MCP Servers.