Skip to content

2. Spec-Driven Development

Spec-Driven Development has a coding agent write the decision down before the code, and the tools that practise it can write far more than a feature needs. After this chapter you can say what a spec and Spec-Driven Development are, name what Spec Kit and OpenSpec got right, and say where the cost of writing one decision in many places begins.

The problem

An agent given a task and nothing else decides what you did not, in the middle of the build. The first answer is to write the decision before the code, in a file the agent reads. The second problem arrives with the first answer: every file written is a file someone reviews and keeps true, and a tool can write so much that the spec becomes the work.

What a spec is

Birgitta Böckeler, of Thoughtworks, compared three tools that call themselves spec-driven and wrote down what the term means.1 A spec, in her definition, is "a structured, behavior-oriented artifact [...] written in natural language that expresses software functionality and serves as guidance to AI coding agents."1 Spec-Driven Development (SDD) "means writing a “spec” before writing code with AI (“documentation first”). The spec becomes the source of truth for the human and the AI."1

Note. Behaviour, here, is what the software does as its user sees it: in this situation, this happens. "A member with an overdue book is refused, with the message 'Return your overdue books first'" is behaviour; "add a column to the loans table" is not, it is how. Written this way, each line can be checked by a test or by a person, and that is why the page of a focus-kit delivery has a section named Behaviour.

Two tools

Spec Kit, from GitHub, is a toolkit of processes for coding agents; its Spec-Driven Development process writes a constitution once per project, then a specification, a plan and a list of tasks for each feature before the code.2 OpenSpec, from Fission AI, "adds a lightweight spec layer so you agree on what to build before any code is written"; its propose command writes one folder per change, with a proposal, specs, a design and tasks.3

I gave both tools, and focus-kit, the method Part II teaches, the same small feature: a booking may be cancelled up to 24 hours before it starts, and a later cancellation is refused with a message that says why.4 Each stopped before writing code.

What they got right

The decision is written before the code, in files the agent reads. A decision that lives only in the conversation is lost when the session ends. All three tools stopped with the feature decided in files inside the project, where a fresh session finds them.

Some decisions are written once per project. Spec Kit's constitution holds the rules every feature follows, such as "keep it simple" or "every rule has a test", and each feature's plan checks itself against it.4 A rule that holds for the whole project is decided once and not argued again feature by feature.

The tool asks before it writes. OpenSpec read the code before it wrote the change, found that the feature assumed something the code did not have, and stopped with a question: it offered two options, recommended one, and wrote the change only after the answer.4 Spec Kit, on its default path, met the same gap and asked nothing; it wrote its own answer under "Assumptions" in the spec, where you find it only by reading the spec.4 A question costs one turn before the code; a guess costs a review, or a user who meets it.

Where the cost of many places begins

For the same feature, Spec Kit wrote 8 files and 756 lines.4 OpenSpec wrote 6 files and 180 lines.4 focus-kit wrote 1 page of 82 lines.4 Every one of those files is something a person reviews before the code is written.

The feature holds one rule about time: up to 24 hours before. Spec Kit restates it in each of its 8 files, OpenSpec in 4 of its 6, focus-kit on its one page.4 The three decide the same thing. The difference is how many other files say it again: a rule restated in a file is read again in that file in review, and when it changes, it changes in every file that restates it, or it disagrees with itself in the ones that were missed. Böckeler found the same with Spec Kit: its files "were repetitive, both with each other, and with the code that already existed", and "very verbose and tedious to review."1

One page is enough because most of what those files repeat, the product, its vocabulary, its rules and the decisions already taken, is the same for every feature. focus-kit writes that part once per project, in documents kept up to date, so the page of a feature holds only what is new about it. The cost is to write those documents and keep them true; the return is one page per feature, read and reviewed in one sitting, in place of a folder. The counts say what each tool writes before the code; they do not say which one builds better software, and one feature on one day is not a benchmark.

What the team gains

A person has to read everything written before the code, because a decision nobody read is a decision nobody checked. A person's attention does not grow with the number of lines: the more there is to read, the less attention each part gets. So the gain is writing less. That is why focus-kit writes one page per feature, which the team reads whole and with attention, reviews and keeps true, where a folder of files gets skimmed. The process I ran on OpenSpec, on Ninjobs, my own product, produced 37,228 lines of spec for four screens (every line under the tool's folder, counted with wc -l), and none of the core flow existed yet. The causes were my choices as much as the tool, and chapter 6 tells them; the count is what a spec costs when it becomes the work. After the move to one page per delivery, the product opened to the public, and a later count found 93 finished pages holding 22,650 lines in all.

Key points

  • A spec is a written, behaviour-oriented description of what the software must do, in natural language, that guides a coding agent; Spec-Driven Development writes it before the code.
  • Spec Kit and OpenSpec got three things right: the decision written before the code, project-wide rules written once, and, in OpenSpec, a question asked before writing.
  • One rule restated in many files is read many times and changed in many places; for the same feature Spec Kit and OpenSpec wrote a folder of files where focus-kit wrote one page.
  • A lighter page per feature is paid for with documents written once per project.

  1. Birgitta Böckeler, "Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl", 2025. https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html ↩↩↩↩

  2. GitHub, "Spec Kit", accessed 2026-09-30. https://github.com/github/spec-kit ↩

  3. Fission AI, "OpenSpec", accessed 2026-09-30. https://github.com/Fission-AI/OpenSpec ↩

  4. J.C. Ködel, "One Page at a Time", the record of the run of the three tools on one feature, 2026-09, in the book's repository. https://github.com/JCKodel/focus-kit-book/tree/main/work/done/spec-driven-run ↩↩↩↩↩↩↩↩