Spec-Driven Development, Six Months In

What SDD actually is, why it beats one-shot prompting, and how the two main open-source toolkits — Spec Kit and OpenSpec — put it to work.

What it is

Spec-driven development means you write down what should be built, agree on it, and only then let the agent write code. The spec is a file in the repository, versioned alongside the source, and it is the thing you review. Code becomes the output of an agreed document rather than the document of record.

The alternative most people start with is one prompt and a hope. That works until it does not, and when it does not there is nothing to fix: the intent lived in a prompt you have already thrown away, so the only move left is to rewrite it and try again. Every attempt starts from the same fog, and nothing accumulates in between.

A spec is a small file. Three sections carry most of the weight.

## Invariants
- A session is never mutated after it reaches a
  terminal state. Terminal states are listed below,
  and the list is exhaustive.
- Every state change writes an audit row in the same
  transaction. No exceptions, including retries.

## Out of scope
- Partial refunds. Do not add a code path for them.
- Currency conversion. Assume single currency.

## Open question
- Expiry: wall clock or last activity? Decided
  last activity — see decision log below.

Invariants are the constraints an agent violates most readily. The out-of-scope list removes more work than anything else in the file, because unnamed adjacent features get built anyway, helpfully and at length. Open questions, once resolved, become the decision log that is the only part anyone reads months later.

What you get for it

The cost is real and worth stating plainly: specs go stale, and a stale spec is worse than no spec, because it is confidently wrong about a system you are about to change. The only thing that prevents it is editing the spec in the same commit as the behaviour it describes.

Spec Kit

GitHub’s toolkit. A CLI that scaffolds the project, plus slash commands that take one line of intent through spec, plan, and task list before any code is written. Each phase writes a markdown artifact the next phase reads, so the agent is never working from just a prompt. It supports 30-plus coding agents, and you pick yours at init.

$ uv tool install specify-cli
$ specify init my-project --integration claude
$ specify check   # verify the agent tooling is found

Then you launch your agent in that directory and stay inside the commands. Everything below happens in the agent’s chat, not the terminal.

OpenSpec

Lighter, and organised around changes rather than phases. Each change gets a folder holding a proposal, spec deltas, a design note, and a task list; the deltas mark what is added, modified, or removed, so you review the change to the spec rather than rereading all of it. Archiving folds the change back into the living spec.

The project has two halves, and the docs are emphatic about it because it trips up nearly everyone once: openspec commands run in the terminal, /opsx: commands run in your assistant’s chat.

$ npm install -g @fission-ai/openspec@latest
$ cd your-project && openspec init
# init installs the /opsx: commands into your AI tool

Two terminal steps to set up, then you live in chat. There is also a setup prompt you can paste into your assistant and have it do the install for you.

You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
      ✓ proposal.md
      ✓ specs/ui/spec.md
      ✓ design.md
      ✓ tasks.md
      Ready for implementation.

Which one

Neither is required to work this way. The spec above is plain markdown and nothing stops you writing it by hand. What the tools give you is a workflow before you have one of your own, and the choice between them is really a choice about how much structure you want holding you to it.