The Spec-Driven Development Methodology — The Discipline Behind the Tools

Before we start: if you came for specify commands, the nine phases and the 66-command table, those live in a different article: GitHub Spec Kit — The Complete Guide and the cheat sheet. This one is about the methodology itself — the idea all those tools are implementing, why it works, and when it fails. The tools will churn within a year. The idea won't.

Section1. The failure this methodology answers

Let me describe a situation you've lived.

You tell the agent: "Add a checkout endpoint." It works for three minutes. It returns 14 changed files, a PaymentStrategy interface, an AbstractCheckoutFactory, retry logic with exponential backoff — and all of it works. Clean code. Tests pass.

But you wanted one endpoint that deducts from a balance. There is no payment gateway in the project at all.

The agent wasn't wrong. It did exactly what it was told. The problem is that what it was told was incomplete, and it filled the gaps with the most statistically likely answer — not the most likely-correct-in-your-context answer.

This is not an intelligence problem. It's an underspecification problem. The distance between those two is the whole article.

1.1 Why code alone isn't enough

Code records how. It never records why.

Open a file six months later and find if (retries > 3) throw. The code tells you someone stopped at 3. It does not tell you whether that was a rate limit on a third-party API that was removed a year ago, or a number someone typed while rushing.

Since agents started writing code far faster than we do, that question got sharper: the agent also reads the code, and it also doesn't know the why. And because it generates faster, it generates wrong assumptions faster.

The core observation: the prompt evaporates. The session ends. The code persists — but code has no intent in it. There has to be a third artefact.

Section2. The thesis — separate intent from implementation

Spec-Driven Development asserts one thing, simple enough to be annoying:

Make intent a real artefact: written, reviewed, versioned, and stored next to the code.

That's it. Everything else is implementation detail.

That artefact carries:

And notice the important side effect: the review gate moves earlier. Instead of reviewing a 2,000-line PR with no idea what it was supposed to be, you review one page before a line is written. The argument happens over the spec, not the diff.

Section3. Lineage — this idea is forty years old

The honest thing to say first: nothing here is new. What changed is who reads it.

The only genuinely new part: the reader of the specification is now a machine that will act on it immediately. A design doc used to be read once and forgotten. Now it's injected into the context window every session.

This is exactly why the "isn't this just waterfall?" critique deserves a real answer rather than a dismissal — we'll give it one in section 10.

Section4. The mechanism — why this works on LLMs specifically

Here is the part with actual numbers.

A paper out of Carnegie Mellon — "What Prompts Don't Say: Understanding and Managing Underspecification in LLM Prompts" (Yang et al., arXiv:2505.13360, published in Findings of ACL 2026) — measured precisely the thing we're describing.

The findings:

Those last two rows are the most important — and the most widely misunderstood:

SDD is not "write more detail." SDD is "identify the places where inference will go wrong, specify those, and leave the rest alone."

If your spec is a brain-dump of everything you know, you're not doing SDD — you're smothering the model, and the paper measured that costing up to 19%.

4.1 Why intent decays inside a session

Three mechanisms compound:

1. Context degradation — the longer a session runs, the more the window fills with diffs, build errors and dead ends. The model starts discarding the architectural constraints you set at the beginning to make room.
2. Abstraction bloat — with no written scope, the agent maximises completeness: interfaces, factories, layers nobody asked for (see the checkout example).
3. Asymmetric unwinding cost — the agent edits 30 files in a minute. You need hours to understand, review and revert those 30 files. The speed only runs one way.

Point 3 is the entire economics of this, and section 7 is built on it.

Section5. The maturity ladder — Böckeler's three tiers

The best taxonomy written on this doesn't come from a tool vendor. It's Birgitta Böckeler of Thoughtworks, in "Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl", published 15 October 2025 in the Exploring Gen AI series on Martin Fowler's site.

She splits it into three levels — and the difference between them is not whether you write a spec, but how long it lives and how much authority it has:

And here's what most write-ups get wrong: Kiro and spec-kit are both in the same tier — spec-first. Neither is above the other. Böckeler says of spec-kit that it is "still what I would call spec-first only, not spec-anchored over time", because its authors treat the spec as a living artefact for the lifetime of a change request, not the lifetime of a feature.

Tessl is the only one of the three that aspires to spec-anchored and is exploring spec-as-source.

The practical takeaway: if your project writes a spec and discards it after merge, you are on tier one — and that is not a failing. Tier one is the right tier for most work. What matters is knowing where you are by choice, not by accident.

Section6. Anatomy of a good spec (no tooling required)

A good spec isn't long. A good spec prevents a specific misunderstanding.

6.1 Non-goals do more work than any other section

Remember the checkout example? Three lines would have prevented it:

Non-goals:
-Nopaymentgatewayintegrationatthisstage
-Noretry/backoff—singlecall,failurespropagatetothecaller
-Noabstractionovermultiplepaymentmethods

Those three lines kill 12 of the 14 files.

Why? Because per the CMU paper, the model fills the gap 100% of the time and gets it right 41.1% of the time. A non-goal doesn't give it information — it closes the gap, so there's nothing left to infer.

6.2 Testable acceptance criteria

The difference isn't stylistic. The first lets the agent grade itself wrongly; the second becomes a test.

Section7. The economics — when it pays, and when it's a tax

This is the most important section, and the one most readers skip.

The rule: the cost of writing a spec is roughly fixed. The cost of unwinding a mistake scales with blast radius.

So there's a crossing point. Below it, specs lose. Above it, they win.

Rule of thumb: if finding and fixing the mistake costs less than writing the spec — don't write the spec. That's not laziness, that's engineering.

And watch this trap specifically: exploration. People try to specify something they don't understand yet, produce a spec full of guesses, and the agent builds confidently on the guesses. Explore first with vibe coding, then write the spec once you understand. That order is not optional.

Section8. The evidence — and two studies that disagree

Here's what separates this from every other SDD article: the data is not unanimous, and we should say so.

Take the simplest and most widespread form of SDD: a context file at the repo root — AGENTS.md or CLAUDE.md.

8.1 Study one: the file saves time and money

Lulla et al., "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents" (arXiv:2601.20404, January 2026).

Method: OpenAI Codex across 10 repositories and 124 real pull requests, each task run twice — once with the repo's native context file, once with it removed.

The researchers' explanation: the file stops the agent groping around the repo. It doesn't read files on spec, doesn't try wrong build commands. It goes straight there on the first turn.

⚠️ Honesty note: this paper measured no correctness metric at all. The authors state evaluating correctness was "beyond the scope"; their check was a manual pass over 50 sampled tasks confirming non-trivial diffs. So if anyone tells you "the study proved pass rates held steady" — that claim is not in the paper.

8.2 Study two: the file raises cost, and the benefit is marginal

Gloaguen et al. at ETH Zurich, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" (arXiv:2602.11988, February 2026 — at the MemAgents workshop at ICLR 2026, not the main conference).

Method: a new benchmark, AGENTbench — 138 real Python tasks across 12 repositories, cross-checked against SWE-bench Lite.

8.3 How can both be right?

The answer is in ETH's own trace analysis, and it's the most elegant part of the whole story:

Agents obey context files.

Write "run the tests after every change" and "run the linter", and it does. So it performs more actions, explores deeper, reasons in more steps. The result:

• ✅ Higher discipline and style compliance
• ❌ More tokens
• ❌ And the benchmark can't see the difference, because it measures pass/fail — not "does this match the project's conventions" or "did the linter pass"

So the studies don't contradict each other. The first measured efficiency (time and tokens to get there). The second measured success rate on a metric that is blind to quality.

Conclusion: a context file buys you discipline and consistency, not capability. If you expect it to make the model smarter, it won't. If you expect it to make the model predictable, that's exactly what it does.

Section9. Configuration smells — 91% of files have one

If the context file matters this much, how well do people actually write them?

A study from the Federal University of Minas Gerais (UFMG) in Brazil — "Configuration Smells in AGENTS.md Files" (arXiv:2606.15828, June 2026) — examined 100 top-starred repositories (39 AGENTS.md and 61 CLAUDE.md files).

Result: 91% of them carry at least one configuration smell.

Note Lint Leakage in particular: at 62% it's both the most common and the easiest to fix. Any rule your tooling already enforces — delete it from the file. Its home is CI, not the prompt.

9.1 The layered context model

The fix isn't "write a better file". It's splitting it across three layers:

On size: Anthropic officially recommends keeping CLAUDE.md under 200 lines, verbatim: "Longer files consume more context and reduce adherence." That's a recommendation, not a cap — the file loads in full however long it is. Codex, by contrast, has a real ceiling: project_doc_max_bytes defaults to 32 KiB, applies to the combined size of all instruction files, is configurable, and truncates the overflow silently.

9.2 And a rule that beats all of this: turn prose into hooks

This line in a context file:

Alwaysruntestsandthelinterbeforecommitting

is followed probabilistically. Sometimes.

The same rule as a hook firing after every file edit runs 100% of the time, costs no context tokens, and doesn't depend on the model's mood.

The rule: anything that can become a hook or a CI check — don't write it in the context file. The context file is for what can't be automated.

Section10. Failure modes of the methodology itself

Anyone selling you a methodology without telling you when it fails is selling you something else.

10.1 "This is just waterfall with an AI doing the typing"

This is the most common critique, and it is a serious one. The argument: writing a complete design before any code repeats waterfall's original failure — making your largest architectural commitment at the moment you know least.

The honest answer: the critique holds when the batch is large, and collapses when it's small.

The difference isn't whether a spec exists — it's slice size. A spec for one feature with an hours-long horizon is a feedback loop. A spec for a whole quarter is genuine waterfall. And if your spec never changes during implementation, that is not evidence it was good — it's usually evidence nobody is reading it.

10.2 Spec rot — the dangerous one

Code changes under production pressure; the spec doesn't. Two months later the spec is documented fiction, and the agent is building on the fiction.

The only cure that works: update the spec in the same PR as the code. Not a follow-up ticket, not "we'll sync it later". Same PR or nothing.

And you can enforce it mechanically:

10.3 The rest

Section11. SDD with zero tooling — start today

You don't need to install anything. The minimum working version:

Operating rules:

1. AGENTS.md = principles + off-limits. Under 200 lines. No linter rules in it.
2. specs/<feature>.md = problem, scope, non-goals, acceptance criteria, open questions.
3. docs/adr/ = the decisions you will forget. Context, alternatives, consequences.
4. The PR references the spec — and edits it in the same PR.
5. Any automatable rule → hook or CI, not prose.

Tools give you scaffolding, phase discipline and agent integration. They don't give you the idea — the idea is above.

Section12. The tool landscape, mid-2026 (deliberately brief)

Three corrections you'll find wrong in 90% of write-ups:

1. Kiro uses EARS, not Gherkin. They're different notations. EARS is WHEN [event] THEN [system] SHALL [response], plus IF/THEN, WHILE and WHERE patterns. Gherkin is Given/When/Then and is a separate thing entirely.
2. Spec Kit's commands are all namespaced /speckit. — it's /speckit.specify, not /specify. Official install is uv tool install specify-cli. And npx github-spec-kit init is not a real command — no such npm package exists.
3. Tessl has pivoted. The framework launched in September 2025 with the spec-as-source model is still closed beta, and the site today sells an agent-enablement platform for skills — the old concept docs 404. So any claim about Tessl's spec-as-source needs a date stamp on it.

Section13. What should you measure?

If you're not measuring, you're performing ceremony, not engineering.

The second one is my favourite: if your spec never changes during implementation, nobody is reading it.

Section14. Conclusion — the durable idea

Let's be honest about the state of the evidence:

• ✅ Confident: ambiguity makes model behaviour fragile — 41.1% correct inference, and twice the regression risk on any update (CMU).
• ✅ Confident: a context file measurably cuts time and tokens (28.64% and 16.58% — Lulla).
• ⚠️ Not confident: that this converts into a higher success rate — ETH found only +4% for a +20% cost.
• ⚠️ Caution: the famous productivity numbers are far weaker than they're quoted. Copilot's 55% faster came from a 2022 experiment on one toy task (an HTTP server in JavaScript) with 70 developers completing, and a very wide confidence interval of [21%, 89%]. METR's 19% slower (2025, 16 developers, 246 tasks) was itself walked back in a February 2026 update that METR described as providing "only very weak evidence".

So what does all of it mean?

Don't sell SDD as a promise of productivity. Sell it as a promise of control.

The one thing every piece of evidence agrees on is that specs reduce variance: work becomes more predictable, the agent respects boundaries more consistently, and review happens before the cost compounds.

And the idea that will outlive Spec Kit, Kiro and Tessl, whatever becomes of them:

Intent deserves to be an artefact.

Nobody executes well — not a junior, not a contractor, not a model — until someone writes down what "correct" means.

SectionSources

Every figure in this article was checked against its primary source:

• Böckeler, B. — Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl (martinfowler.com, 15 Oct 2025) — the three-tier taxonomy
• Yang, C. et al. (CMU) — What Prompts Don't Say — arXiv:2505.13360 / Findings of ACL 2026
• Lulla, J. et al. — On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents — arXiv:2601.20404
• Gloaguen, T. et al. (ETH Zurich) — Evaluating AGENTS.md — arXiv:2602.11988 (MemAgents workshop @ ICLR 2026)
• dos Santos et al. (UFMG) — Configuration Smells in AGENTS.md Files — arXiv:2606.15828
• Becker, J., Rush, N., Barnes, B., Rein, D. (METR) — arXiv:2507.09089, and the 24 February 2026 update
• Peng, S., Kalliamvakou, E., Cihon, P., Demirer, M. — The Impact of AI on Developer Productivity — arXiv:2302.06590
• Piskala, D. B. — Spec-Driven Development: From Code to Contract — arXiv:2602.00180
• ContextBench (Nanjing University + UCL) and SWE-ContextBench — arXiv:2602.08316
• AGENTS.md — agents.md, and the Agentic AI Foundation announcement (Linux Foundation, 9 December 2025)