When Spec-Driven Development Is Overkill: Discover First, Route by Complexity, Plan What Survives

A year into spec-driven development (SDD) tooling, the demos all show the same movie: one command produces a spec, the next a plan, the next a task list, and an agent builds the feature. What the demos never show is the prior question — should this change get the full flow at all?

I asked that question in my own repository because my setup forced me to. On October 29, 2026, I removed OpenSpec from this site and standardized on GitHub Spec Kit. In the process I found three things. Canonical specs were accurate but no longer loaded by anything. Changes had shipped without ever being canonized. And a freshly written policy in my CLAUDE.md sent every non-article feature and tooling change through Spec Kit: no tiers, no exceptions, and no review date.

This article is the framework I landed on. It is a follow-up to two earlier articles. When Is a Prompt Enough, and When Do AI Agents Need More? covered the tiny end of the scale. The Human Part of GitHub Spec Kit: How to Talk to Agents Between Commands covered human judgment inside the flow. This one is about routing before the flow and survival after it.

For the 2026 studies behind the question of when SDD pays off, read After Spec-Driven Development: Articulate Always, Spec Sometimes.

TL;DR

• No, you should not always use spec-driven development. For tiny, exploratory, throwaway, or obvious work, a prompt with a small spec — or plan mode — is the right level. Full SDD there is ceremony.
• Uncertainty is not a spec trigger; it is a discovery trigger. SDD is an execution tool. When you do not yet know what to build, spike or prototype first; write the spec once no remaining unknown would change the shape of the solution.
• After discovery, route by complexity × irreversibility. Complexity is coupling, maintainers, integration surface, and regulation — not lines of code.
• Choose the spec’s lifespan deliberately: spec-first (disposable), spec-anchored (durable, but you pay the update tax), or spec-as-source (only where generation is mature and trusted). As of October 29, 2026, GitHub’s own Spec Kit docs make the same point with post-delivery persistence models — and say none of them is the default.
• Plan promotion into the change’s own tasks. Knowledge survives when it ends up always in the agent’s path — auto-loaded instructions or checks that run every build — or in a lookup store with a real lookup mechanism. In my repository, the promotion that landed was written as tasks, while the archive step that depended on someone remembering fell behind. One repo and a handful of changes make this a case, not a measurement.
• A blanket SDD mandate is a policy with an expiry date. As a timeboxed pilot it is defensible; kept indefinitely without tiers, metrics, or a review date, it becomes the overhead it was meant to prevent.

The Question the Tools Won’t Answer

Tool documentation assumes the answer is yes. GitHub’s position paper puts it at maximum strength: in spec-driven development, “maintaining software means evolving specifications” and code is the last-mile expression of the spec. That is a coherent vision — for the changes where it fits.

Practitioner evidence points the other way for everything else. Nearform’s June 24, 2026 report on real-world failures lists “using SDD for everything” as failure mode 2. For minor tasks, writing specs, generating plans, and validating outputs can eclipse the work itself. The fix is to “match your approach to the complexity of the task”: an exhaustive prompt containing a small spec, or plan mode, for tiny changes; the full SDD flow for medium-large ones.

A January 30, 2026 technical report surveying the field reaches the same shape. It calls spec-driven development overkill for throwaway prototypes, solo short-lived projects, exploratory coding, and simple CRUD with obvious requirements. Its golden rule is to “use the minimum level of specification rigor that removes ambiguity for your context.”

Birgitta Böckeler’s hands-on evaluation is blunter. A small bug through Kiro became four user stories and sixteen acceptance criteria — “a sledgehammer to crack a nut” — and a 3–5 point feature through Spec Kit in 2025 produced so much markdown to review that, in the same time, she thought she could have implemented it with plain AI-assisted coding and felt more in control.

None of this says SDD is a fad. The same sources give it clear wins: complex requirements stakeholders must validate before code, multi-maintainer systems, integration-heavy work, regulated domains needing traceability, and legacy modernization where existing behavior is first captured as a spec. The question was never whether SDD works. It is routing: which changes earn it.

First, Name the Lifespan

The most useful cut in the SDD literature is Böckeler’s, from October 15, 2025, kept in her September 2026 update. It is not about tools; it is about how long a spec is allowed to live and who wins when spec and code disagree:

Two things follow. First, in my reading, almost every tool that calls itself SDD is spec-first in practice, whatever it aspires to. Second, spec-anchored is the only level at which previous specs carry into future sessions, and only while the tax is paid.

GitHub’s current official Spec Kit documentation (read October 29, 2026) adds a second, related question: not just how long the spec matters, but what happens to spec.md, plan.md, and tasks.md after delivery. The persistence doc names three models:

• flow-back: reflect accepted discoveries into any artifact and reconcile.
• flow-forward: completed feature folders are immutable history; new requirements get a new folder.
• living spec: spec.md stays the contract; plan and tasks are regenerated derivations.

It states plainly that Spec Kit “intentionally leaves teams in control” of this choice, that none is the default, and that teams should document the convention in their constitution or team onboarding notes.

Note what that doc does and does not say. It is not the vendor endorsing routing: the same document insists that all three models “use the same feature delivery process” and that persistence is “not an alternative way to deliver or determine completeness.” GitHub keeps one delivery flow for every feature and leaves lifespan and persistence to you; whether a change gets the flow at all is still your call. Even on persistence alone, a team that has not chosen has not avoided the decision — it has made it by accident. How to Handle Feedback in GitHub Spec Kit Before and After Implementation covers how to choose among the three. For completeness on current behavior, as of October 29, 2026, upstream Spec Kit is at v1.2.5. Its post-implementation /speckit-converge command appends missed work to tasks.md rather than editing code. Its workflow and extension system allows considerably more customization than the 2025 fixed-pipeline description suggests. It is still one core delivery path, which is exactly why the routing decision sits with you.

Discovery → Spec → Delivery

My earlier instinct was to reach for SDD precisely when I knew almost nothing about what I needed to do. The failure-mode evidence says that is backwards, and it is the correction that reorganized this whole framework.

Nearform’s failure mode 1 is “building before understanding the problem”: a team follows the SDD process perfectly, produces a detailed spec and a clean implementation — of the wrong thing. “Spec-driven development amplifies clarity, but it ultimately doesn’t prevent you from building the wrong thing… SDD is an execution tool, not a discovery tool, so use it only after you have a firm grasp of what you’re building.” Their failure mode 3 sharpens it for agentic systems, whose behavior emerges through interaction: details “only become clear when you see the system in action,” so prototype the experience first and formalize later.

Discovery is a solved problem outside SDD; it just is not a spec. For the toolkit — assumption mapping, spikes, premortems, one-way vs two-way doors — see Winning Ambiguous Problems: How to Explore Alternatives, Capture Unknowns, and Still Decide. Spec Kit’s early flow can also host that kind of investigation, as Using GitHub Spec Kit to Investigate Alternatives Before You Build describes, with the hardened spec written only after a direction is approved. The one piece this article needs is the exit criterion, because “explore until comfortable” is how discovery becomes procrastination. James Shore’s spike discipline supplies it: a spike is a small, usually sub-day experiment built to answer one specific question, and “when you have the answer, the spike is discarded.”

The formulation I now use — my synthesis, not a quoted standard — is:

Discovery exits when no remaining unknown would change the shape of the solution. Every other unknown has a named owner or an explicitly accepted assumption.

That gives the sequence its gates:

• Discovery asks what should exist, and is it feasible? Artifacts are disposable: spikes, prototypes, a list of open questions with owners. No formal spec yet.
• Spec asks what exactly will we build, and how will we know it works? Non-goals, acceptance criteria, constraints — frozen enough to execute against. One nuance from Data Dynamics’ June 17, 2026 practitioner case study is worth keeping: clarification is not “for complex features” — it is for features where humans unconsciously assume decisions (retry counts, backoff, failure behavior) that an agent will otherwise invent.
• Delivery asks build it in small, validated increments. Review the spec and the plan before code, because a one-line wrong assumption compounds into architecture and then into dozens of files; verify after, because an implementer reports what it did, not what it skipped.

And one return edge matters: when delivery falsifies an assumption, the loop goes back to discovery, not just to editing the spec. A spec edit can record a new answer; it cannot tell you the question changed. The same loop covers a wrong tier. My rule of thumb, which is my judgment rather than a sourced standard: escalate when plan review surfaces a contract, data, or auth change I did not route for, and demote when spec review costs more than the diff would.

flowchart TD
    A[New change] --> B{Do we know what to build?<br/>No unknown changes the shape}
    B -- No --> D[Discovery<br/>spike / prototype / clarify]
    D --> B
    B -- Yes --> C{Complexity x irreversibility}
    C -- Tiny, reversible --> P[Prompt + small spec<br/>or plan mode]
    C -- Medium-large, complex --> S[Spec-first SDD<br/>full flow]
    C -- Long-lived contract --> L[Spec-anchored<br/>pay the update tax]
    S --> T[Tasks<br/>including promotion tasks]
    L --> T
    P --> V[Deliver + verify]
    T --> V
    V -- Assumption falsified --> D
    V -- Done --> K[Promotion tasks close:<br/>in-path rule / check / ADR-DR /<br/>lookup note / delete]

Match the Rigor to the (Post-Discovery) Complexity

Complexity is not size. The factors that raise the spec level are coupling to other systems, number of maintainers, integration surface, regulatory or traceability needs, and whatever novelty survives discovery. Irreversibility is the second axis: if one revert cannot undo the change (a data migration, a published API contract, a permission boundary), treat it as a one-way door, whatever its size. A twenty-line authorization change is high-complexity. A two-thousand-line mechanical rename is low-complexity but high-blast-radius; it wants a plan and automated checks, not a product requirements document. For the rigor-by-blast-radius calibration inside a chosen flow, see The Human Part of GitHub Spec Kit: How to Talk to Agents Between Commands. For the tiny tier in full, see When Is a Prompt Enough, and When Do AI Agents Need More?. For the rungs between a prompt and the full flow, see After Spec-Driven Development: Articulate Always, Spec Sometimes. The routing I use:

What does the full flow cost when you misapply it? Honest answer: the measurement base is thin. The one published head-to-head I found (one chat-app feature, two runs, GPT-5.2/Codex, March 18, 2026) had the heavier Spec Kit pipeline using roughly twice the tokens of OpenSpec. Its limits are real: a single task, no comparison against using no spec, and no wall-clock data. Treat it as a directional smell (heavier pipelines cost more context), not as proof that tiering saves money. As of October 2026, I found no published measured tiered-vs-uniform comparison, and I have not run one either. That is why this routing table is a recommendation, not a finding.

Qualitative team evidence does exist. Thoughtworks’ Technology Radar (GitHub Spec Kit, Assess, April 2026) reports teams, mostly in brownfield environments, finding that a useful constitution helps agents operate within the intended architectural boundaries. It also reports two recurring costs. The first is instruction bloat that grows into context rot; one team addressed it by extracting reusable guidance into skills and keeping instructions lean. The second is overly verbose markdown that increased cognitive load; customizing templates and limiting generated files helped address some of these issues. Note the shape of the first fix: less in the always-loaded context, more loaded on demand. That pattern returns in the next section, because it is the whole game.

Promotion: Plan What Survives, in the Change’s Own Tasks

Here is the finding I did not expect, from retiring OpenSpec in this repository.

OpenSpec is the spec-anchored tool in this story: /opsx:sync merges a change’s ADDED/MODIFIED/REMOVED delta specs into a canonical openspec/specs/ library, and /opsx:archive closes the completed change into that canon. (The mechanics are in OpenSpec vs GitHub Spec Kit: A Side-by-Side Review of Spec-Driven Development.) If any setup should have carried previous specs into future sessions, it was this one. Checking the archive against reality:

• Of my two completed OpenSpec changes, one was archived; the other (all tasks checked) never was.
• Two further changes shipped behavior while their verification tasks were still open, including the Spanish-i18n change. A fifth change, the audio-summary pipeline, had no tasks checked at all. OpenSpec was removed with all three still unfinished.
• The three canonical specs were accurate — I spot-checked a sample of their requirements against src/ and they still hold — but their Purpose fields still say “TBD,” and since October 29, 2026 nothing loads them at all.

That is not a story about skipping the archival tax. It is canon lag: in a spec-anchored tool, shipped behavior stays outside the canon until the change is verified and archived. Whenever verification lags — which, in my experience, is whenever a team is busy — the canon describes the system as of the last tidy moment, not as it is. Archiving is a step that can fall behind; a step that can fall behind, will.

What actually carried knowledge forward from those same changes? The pieces that needed no archive step, because they sit in the agent’s path by default. The unarchived Spanish change required that a stray flat file under content/articles/ must fail the build instead of being silently skipped. That rule lives in CLAUDE.md as prose, auto-loaded into every session, and as scripts/check-content-layout.mjs, which runs on every build. Its translatedFrom rule took the same route into instructions plus check-translation. Böckeler’s 2026 harness-engineering model gives this vocabulary. Auto-loaded instructions are guides: feedforward controls that steer before the agent acts. Tests, linters, and checks are sensors: feedback controls that let it self-correct after. The strongest promotion converts a prose guide into a computational sensor; the weakest leaves knowledge in a folder a future session must happen to open.

So the rule I now apply to every spec fragment at close-out is a single question:

Must this be in the agent’s path by default, or is lookup-on-demand enough?

• In-path, prose: invariants and high-frequency conventions → CLAUDE.md / constitution. This budget is scarce: it loads every session, and instruction bloat is the Radar’s documented failure mode. Extract detail into skills loaded on demand.
• In-path, executable: anything mechanically checkable → a script, test, or CI gate. Prefer this over prose whenever the rule can be made deterministic; a check cannot be skimmed past.
• Decision record: architecturally significant choices → ADR (platform) or DR (feature-scoped). One promotion target among several — not, as I once assumed, the universal durable asset. (For ADR enforcement patterns, see Architecture Governance for AI Code Generation.)
• Lookup: behavior detail that matters only when touching that feature → a maintained note with a named lookup mechanism (an index, a skill that routes to it, a checklist reference). Lookup without a mechanism is a write-only archive; that is what my canonical specs became the day the tool was removed.
• Delete: everything else. The spec did its job as scaffolding. Deleting it is what prevents the next agent from trusting stale prose over running code.

None of this is a new step to remember. My own earlier writing already prescribed promotion as part of the definition of done for agentic workspaces: “archive spec and promote ADRs before closing the initiative” (Agentic Workspaces: Submodules, Skills, Knowledge, and Spec-Driven Delivery). The Spanish change illustrates the mechanism from the positive side. It is one change, so a case rather than proof. Its promotion worked because the CLAUDE.md update and the three check scripts were literally tasks 1.4, 1.5, 2.6, and 7.0 of the change itself. Promotion planned as tasks ships; promotion left as a virtuous intention becomes canon lag. Write the promotion tasks when you write the other tasks, while you still know which fragments matter.

The Mandate Trap

Everything above also answers the team question: was mandating Spec Kit for all development — as I suspect many teams did in 2025–26, and as my own CLAUDE.md did on October 29, 2026 — a wrong decision made too early?

Separate the decision from the policy. As a decision, under 2025’s uncertainty — a semantically diffused term, tools changing monthly, agents needing some guardrails — a uniform mandate run as a timeboxed learning pilot was defensible: shared language, consistent review surface, less decision fatigue. Laura Tacho told Birgitta Böckeler in May 2026 that she sees “a wide array” of practices all called spec-driven development, with “not a lot of standardization”; waiting for the field to settle was also a cost.

As a policy kept indefinitely, it fails on the evidence above. It applies failure mode 2 by decree. It pays spec-anchored ceremony without collecting spec-anchored benefits. The sharpest tell is a missing review date and missing metrics: with neither, nothing can ever falsify the policy. The mistake was never starting early. It is mandating without a scheduled re-evaluation.

The fix is demotion, not removal. Spec Kit becomes the default for medium-large work (where its constitution, clarify, and converge gates earn their keep). Lower tiers are explicit, an ADR/DR rule applies at any tier, and the review date is measured in cycle time, review burden, and rework. Teams get to keep the shared language; tiny work stops paying the tax; and the policy itself becomes, like a good spec, revisable on evidence.

The Routing Policy, Paste-Ready

This is the worked example: the tiered rule I am replacing this repository’s flat mandate with. It is one repo’s policy, offered as a starting point, not a standard.

## Spec-Driven Changes (tiered)

Route the change BEFORE starting. When in doubt between two tiers, take the lower one and note why.

- **Discovery** — unknown or emergent behavior: spike, prototype, or explore.
  No spec yet. Exit when no remaining unknown would change the shape of the
  solution; park the rest as named assumptions with owners.
- **Tiny, known, reversible** — one area, no contract/data/auth change:
  prompt or plan mode; truth is the diff plus tests. No spec folder.
- **Medium-large, complex, cross-cutting, or hard to reverse**: full SDD flow
  (specify -> clarify -> plan -> tasks -> analyze -> implement -> converge).
  Tasks MUST include promotion tasks (next bullet).
- **Promotion (planned as tasks, part of definition of done)** — for each
  durable fragment of the spec, decide its home while writing tasks:
  in-path rule (CLAUDE.md/constitution) / executable check or test /
  ADR (platform) or DR (feature) / lookup note with a named lookup mechanism /
  delete as scaffolding. "We will document it later" is not a home.
- **Architecturally significant at any tier**: record the decision (ADR/DR).
- **Spec lifespan**: default spec-first (mark historical or delete after
  delivery). Claim spec-anchored only for named long-lived contracts, and
  name who pays the update tax. Persistence model: <flow-back | flow-forward
  | living spec> for this repo.
- **Policy review date: <YYYY-MM-DD>** (or after N spec'd features, whichever
  first). Review against cycle time, review burden, and rework. Adjust the
  tiers; do not just renew.

What I’m Changing in My Own Setup

Three edits follow from the routing above; as of October 30, 2026 they are drafted, not yet applied, and I am listing them so the policy in this article is one I am accountable to. First, the flat mandate in CLAUDE.md that sends every non-article feature and tooling change through Spec Kit becomes the tiered policy above, with a review date of January 29, 2027 or five Spec Kit features, whichever comes first. Second, the persistence choice gets named in the project constitution, where GitHub’s docs suggest putting it, instead of being left to whichever tool I happen to have installed. My constitution is still an unfilled template, which tells you how seriously I had taken my own setup. Third, the frozen OpenSpec canon stays as a read-only historical record, explicitly lookup-only. The rules that must reach every session live in CLAUDE.md and the build checks — where, in practice, they were already doing the work.

That is the whole argument in miniature. Specs are excellent scaffolding and, at the anchored end, real contracts. But knowledge survives sessions and survives tools in proportion to being in the path — loaded by default, executed every build, or found by a mechanism you actually maintain. Plan for that while the spec is being written, route each change at the rigor it has earned, and let the rest be scaffolding you are allowed to throw away.

Sources

• Birgitta Böckeler, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl,” October 15, 2025: https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html — spec-first/spec-anchored/spec-as-source, the small-bug and 3–5-point-feature overkill observations, spec vs memory bank.
• Birgitta Böckeler, “Understanding Spec-Driven-Development” (author’s updated version), last update September 2026: https://birgitta.info/posts/spec-driven.html — retained lifespans; spec-as-source and the model-driven development parallel.
• Birgitta Böckeler, “Harness engineering for coding agent users,” April 2, 2026: https://martinfowler.com/articles/harness-engineering.html — guides (feedforward) vs sensors (feedback); computational vs inferential controls.
• Alfonso Graziano (Nearform), “Lessons from real-world failures using spec-driven development,” June 24, 2026: https://nearform.com/insights/lessons-from-real-world-failures-using-spec-driven-development/ — failure modes 1–5, including “SDD is an execution tool, not a discovery tool” and “using SDD for everything.”
• Deepak Babu Piskala, “Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants,” January 30, 2026: https://arxiv.org/abs/2602.00180 — the specification spectrum, §VIII when-to-use and overkill list, “minimum level of specification rigor that removes ambiguity.”
• Thoughtworks Technology Podcast, “What is spec-driven development?” (Böckeler with Laura Tacho), May 28, 2026: https://www.thoughtworks.com/insights/podcasts/technology-podcasts/what-is-spec-driven-development — semantic diffusion and the absence of standardization eight months on.
• Thoughtworks Technology Radar, “GitHub Spec Kit” (Assess), April 15, 2026, and Vol. 34 (April 2026): https://www.thoughtworks.com/radar/languages-and-frameworks/github-spec-kit — team reports: useful constitution, instruction bloat/context rot, verbose markdown, template customization.
• GitHub, Spec Kit repository — spec-driven.md (“maintaining software means evolving specifications”), docs/concepts/spec-persistence.md (flow-back/flow-forward/living spec; no default; document the convention in the constitution or team onboarding notes), templates/commands/converge.md, and CHANGELOG.md (v1.2.5, October 28, 2026). Read October 29, 2026: https://github.com/github/spec-kit
• Michael Nygard, “Documenting Architecture Decisions,” November 15, 2011: https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions — ADR scope and format.
• James Shore, “Spike Solutions,” The Art of Agile Development: https://www.jamesshore.com/v2/books/aoad2/spike_solutions — spikes answer one question and are discarded.
• Jamie Telin, “Spec Driven Development Is Wasting Tokens,” March 18, 2026: https://medium.com/it-chronicles/is-your-safe-choice-burning-your-budget-1cfddf8782e4 — single-task token comparison (57,740 OpenSpec vs 120,947 Spec Kit; second run 91,729 vs 181,040); cited with its limits in the text.
• Local evidence (this repository, verified October 29, 2026): docs/legacy-openspec/changes/*/tasks.md (completion and archive states), docs/legacy-openspec/specs/ (three canonical specs), CLAUDE.md (Spec-Driven Changes mandate; article-layout rule), scripts/check-content-layout.mjs, scripts/check-locale-parity.mjs, and scripts/check-translation.mjs (build gates).
• Data Dynamics, “[Spec Kit Part 7] In Practice — Building a Data Quality Monitoring Service with SDD (Retrospective),” June 17, 2026: https://data-dynamics.io/en/blog/spec-kit-case-study — single-project company case study; supplied the clarify observation in the text; treated as anecdote, not data (its own numbers are labeled illustrative by the author).