# Spec-Driven Development: Spec Kit, Kiro, and What Sticks

*Published 2026-07-24 · Dmitry Shirokov · shirokoff.ca/blog/spec-driven-development*

The third rebuild made the point. A team asked their coding agent for a bulk-import feature, got a clean implementation in an afternoon, and found it deduplicated on the wrong key. Rebuilt. Version two rejected the whole file on one bad row, which nobody had said it shouldn't. Rebuilt again. They spent more time discovering what they wanted than all three implementations took. **When implementation gets cheap, the expensive mistake becomes building the wrong thing precisely** — and the requirement that would have prevented it lived in a Slack thread and a discarded prompt.

## What SDD claims

**The specification is the durable, version-controlled, reviewed artifact; code is its output, traceable back to the requirement that caused it.**

| | What's durable | Review catches | Failure mode |
|---|---|---|---|
| **Prompt-driven** | The code; the prompt is discarded | Whatever a reviewer spots in a big diff | Nobody can say what was intended, so nobody can say if it's wrong |
| **Classical up-front spec** | A document, written once | Everything, before anything is real | Code and spec diverge within a sprint |
| **Spec-driven** | The spec, *continuously* | **Intent, before implementation is paid for** | Spec drift, if the loop back is never closed |

*Continuously* is the load-bearing word. A spec written once and abandoned is waterfall with extra steps.

## The artifact chain

| Stage | Spec Kit | Kiro | What it's for |
|---|---|---|---|
| Standing rules | `constitution` | Steering files | Principles the agent must not violate |
| What & why | `/speckit.specify` | Requirements, **EARS** acceptance criteria | Testable intent, no technology in it |
| How | `/speckit.plan` | Design: interfaces, schemas, data flow | The architecture review while it's cheap |
| Breakdown | `/speckit.tasks` | Tasks | Resumable, checkable units |
| Build | `/speckit.implement` | Implementation traced to requirements | The part everyone thought was hard |

**Spec Kit** is GitHub's open-source, tool-agnostic toolkit (CLI + slash commands across Claude Code, Copilot, Cursor, Gemini CLI, Codex and more). **Kiro** is AWS's agentic IDE, GA since March 2026 and the replacement for Amazon Q Developer; its use of **EARS** — *"When \<trigger\>, the system shall \<response\>"* — is the most underrated idea here, because it makes acceptance criteria mechanically testable. You can also run the pattern with no toolkit: a spec template, `AGENTS.md`, and your existing ADRs.

## What genuinely works

**Review moves to where it's cheap** — two minutes on a paragraph of intent catches "wrong dedupe key"; forty minutes on 800 lines catches formatting. **The plan step kills bad architecture while it's still an opinion**, before anyone is defending their afternoon. **Standing rules are the highest-leverage file in the repo** — build/test commands, conventions, off-limits directories, settled patterns, applied to every generated change; `AGENTS.md` has become the cross-tool convention for this. **Tasks make agent work resumable** and survive a context window ending.

## What is ceremony

**Small changes** — a spec, plan and tasks for a two-line fix costs more than the fix. **Generated specs nobody reads** — if the human doesn't argue with it, you've added latency and removed nothing; the value is in the disagreement. **Exploratory work** — specifying what you don't yet know is pretending you do; prototype, discard, *then* spec. **EARS everywhere** — excellent for defined behaviour, terrible for experience and design intent.

## What the evidence supports

Treat the big community numbers (large rework reductions, delivery multiples) as uncontrolled self-reports. Two real findings shape the positioning: METR's mid-2025 randomized trial found experienced open-source developers **~19% slower** on real tasks in familiar codebases with AI tools — while estimating they'd been ~20% faster. **That perception gap means your team's impression that this is working is not evidence that it's working.** And DORA's 2025 report found AI acts as an **amplifier** of existing strengths and dysfunctions. Together: SDD earns its cost in unfamiliar codebases, high-consequence work, multiple stakeholders, and changes big enough that being wrong is expensive — not for a senior engineer editing code they know.

## Adopt the idea, not the tool

Two files and one habit: `AGENTS.md` with standing rules, a spec template, and the rule that anything above a threshold size gets a human-reviewed spec first. In the template, two sections do most of the work — **Open questions** (where ambiguity becomes visible before someone codes past it; both of that team's rebuilds were listed questions) and **Decisions**, which *links* to ADRs rather than restating them.

Distinctions worth keeping straight: **ADD** = what we're building overall; **ADR** = one decision, immutable; **spec** = one feature, updated when it changes; **standing rules** = how this repo is built, applied by machine on every change. The last is new, and the one I'd add first even if you adopt nothing else.

## Three ways it goes wrong

**Spec drift, worse than no spec** — the document now describes a system you don't have, and the next agent "fixes" the code to match. Rule: if the change makes the spec wrong, the PR updates the spec, and review rejects it if it doesn't. **The agent writes the spec and the human approves it** — you've automated the one step whose purpose was human judgment; let it draft, but acceptance criteria and open questions need a person who'll be blamed if they're wrong. **Specifying the solution instead of the problem** — implementation detail in a spec forecloses better designs and turns planning into transcription.

## When to use it

Two-line fix in familiar code → just make it. Multi-stakeholder feature → **full SDD**. Unfamiliar codebase → **the plan step especially**. Exploratory → prototype, then spec. Regulated or high-consequence → full SDD, and keep the spec as traceability evidence. Any repo with no standing rules → **write `AGENTS.md` first**, highest return of anything here.

*Related: [Architecture Definition Documents, ADRs and runbooks](https://shirokoff.ca/blog/architecture-definition-documents) · [The agent harness](https://shirokoff.ca/blog/agent-harness-design) · [The Ralph loop](https://shirokoff.ca/blog/ralph-wiggum-loop-agentic-coding) · [Estimating AI projects](https://shirokoff.ca/blog/estimating-ai-projects) · [MCP vs Agent Skills](https://shirokoff.ca/blog/mcp-vs-agent-skills)*