After Spec-Driven Development: Articulate Always, Spec Sometimes

On October 29, 2026, I reviewed the 2026 empirical work on spec-driven development (SDD), the current Claude Code and Kiro docs, the Spec Kit 1.0.0 release notes, and practitioner post-mortems. Studies and vendor docs are cited inline. The decision ladder is my synthesis. Where it goes past the evidence, I say so.

TL;DR

• Do not stop spec-driven development. Stop defaulting to it. Practitioners studied in 2026 already use SDD selectively: mainly for new features, rarely for small changes or hotfixes (Agarwal et al., 2026).
• The strongest defect claim failed its empirical test. Across 88,052 pull requests in 119 open-source repositories, none of five vendor-derived hypotheses about specs reducing defects or rework held up (Hill, ESEM 2026). That does not prove specs cause defects, since developers spec their hardest work. It does shift the burden of proof. The one protective signal came from repositories with no AI adoption, where specs were associated with less rework. The benefit showed up where no agent reads the file.
• For individuals, the likely active ingredient is articulation. Agarwal et al. propose that the individual benefit may come from clarifying intent before delegation, which any planning practice produces. That mechanism is plausible and untested. Team benefits, they suggest, may depend on SDD becoming a shared process.
• More planning is not always safer. In 21,120 agent trajectories, a bad or incomplete plan hurt more than no plan at all (Liu et al., ASE 2026). Those were agent execution plans. Applying the result to feature specs is my inference.
• Use a ladder: one-sentence diff → build directly; uncertain or multi-file → ephemeral plan; long-lived, multi-agent, team-reviewed, or audited → persisted spec.
• Whatever tier you pick, add a check the agent can run. A passing test, build, or eval does more for trust than another page of prose (Claude Code best practices, accessed October 29, 2026).

The Hype, Briefly

SDD arrived as the disciplined answer to vibe coding: write the specification first (goals, constraints, plan, tasks), review it, and let the agent implement against it. GitHub’s Spec Kit, Amazon’s Kiro, and Fission AI’s OpenSpec all prescribe some version of that sequence. The practice spread fast. Agarwal et al. found spec files in over 73,000 public GitHub repositories, almost all first committed in 2025 or later.

Then the backlash arrived on schedule: “SDD is dead, long live plan mode,” “the spec is dead, long live the paragraph.” Most of that writing is opinion. In 2026, evidence finally showed up, and it is less flattering to both camps than either admits.

If you want the tool-by-tool comparison, see OpenSpec vs GitHub Spec Kit. This article asks the prior question: how much specification does this task deserve at all?

What the 2026 Evidence Actually Says

Three conclusions I would defend:

1. I found no study showing the file causes quality in AI-assisted work. The vendor claim “specs reduce defects” has now faced a large empirical test and failed it. Its only protective signal appeared in repositories without AI. A qualitative study found that its participants could not separate SDD from concurrent model improvements.
2. Practitioners vote with their feet for proportionality. Agarwal’s interviewees skip SDD for small tasks, bugs, scripts, and hotfixes (“there is no time for spec-driven development and the whole flow”), and reach for it on large features and high-stakes changes.
3. Plan quality is a threshold, not a dial. Liu’s result (bad plan worse than none, extra misaligned phases degrading performance) is about execution plans. Extending it to feature specs is my inference. That matches Agarwal’s finding that 77.6% of real specs carry implementation detail (class names, library versions), which decays fastest. A long, wrong, stale spec is not a safety net; it is a second codebase to maintain.

Planning Is Not a Plan

The sharpest practitioner account is Ayman Nadeem’s post-mortem, Plan mode is dead (September 24, 2026). Nadeem built a desktop coding app, Nuanced, around persistent, living specs, and then killed it:

“The spec contained more information without creating more clarity.”

His diagnosis separates two things SDD marketing merges:

• Planning: the collaborative process of surfacing decisions, trade-offs, and unknowns. More valuable than ever.
• A plan: a large AI-generated artifact that buries those decisions in structured prose nobody rereads. “If we needed to generate a shorter representation of the spec to make the spec usable, what was the point of the full document in the first place?”

This is one builder’s experience, not a study. Agarwal et al. offer a mechanism that makes it plausible (Section V-D of the preprint). Suppose the individual benefit of SDD comes from the developer having articulated goals before delegation, a cognitive forcing function. Then plan mode, a design conversation, or any practice that forces thinking should produce the same benefit. The spec file would then be ceremony after the valuable part already happened.

As far as I know, no one has run this experiment yet. Agarwal et al. propose it with the same tasks and three arms: spec written and given to the agent, spec written and withheld, no spec at all. Until someone does, “articulate always” is evidence-adjacent; “persist always” is faith.

The Proportional Ladder

Each rung still traces to a primary source. A companion piece, When Spec-Driven Development Is Overkill, covers how long a spec should live and when to promote its tasks. This article checks each rung against the 2026 evidence.

flowchart TD
    A[New task] --> F{Will this outlive the session?<br/>Other agents, teammates,<br/>approval or audit ahead?}
    F -->|No| B{Can you describe<br/>the diff in one sentence?}
    B -->|Yes| C[Tier 0: Build directly<br/>prompt + check to run]
    B -->|No| D{Uncertain approach,<br/>multi-file, or unfamiliar code?}
    D -->|Yes, one session| E[Tier 1: Plan mode<br/>explore, plan, iterate, implement]
    D -->|No / well understood| C
    E --> G[Implement<br/>plan or intent as guide]
    F -->|Yes| H[Tier 2: Persist an intent contract<br/>goal + acceptance criteria in git]
    H --> I{Any one of high complexity,<br/>team gates, regulated or brownfield risk?}
    I -->|Yes| J[Tier 3: Full SDD<br/>Spec Kit / Kiro / OpenSpec workflow]
    I -->|No| G

Tier 0: Direct. My one-sentence heuristic: if you can describe the diff in one sentence (a typo, a log line, a rename), no plan artifact earns its review cost. Per Nadeem, the review burden can exceed the task. The live Claude Code best practices (accessed October 29, 2026) supports this more directly. In most cases, “your first plain prompt in a fresh session already does the right thing.” So add only what Claude cannot see in the repo, plus a check to run. Its “What you can stop doing” table says it flatly about context files: “Claude reads the repo itself. Only write down what isn’t in there.”

Tier 1: Ephemeral plan. Plan mode in Claude Code, Cursor, or Kiro: the agent explores read-only, you iterate on a short plan, then implement in the same session. Kiro’s documentation puts this at tasks needing roughly 15–60 minutes of implementation: long enough to benefit from planning, short enough that formal specs are overkill. The plan dies with the session, and that is fine, because its job was to make you think.

Tier 2: Persisted intent. When a second agent, a teammate, a reviewer, or future-you must reconstruct why without you in the room, the artifact earns its keep. Multiple sessions or agents building against one intent also qualify, because chat history will not survive. This is the one-page intent contract below, which replaces the full spec/plan/tasks stack.

Tier 3: Full SDD. Kiro reserves Feature Specs (persisted requirements.md, design.md, and tasks.md, with approval gates) for “high complexity, team collaboration, audit trail.” Spec Kit’s README (accessed October 29, 2026) describes a loop that repeats “until convergence reports Converged.” Its 1.0.0 release shipped August 21, 2026. Reading its composability as a delivery harness is my inference: ThoughtWorks’ harness write-up never mentions Spec Kit. Governed, team-scale work is still where heavy process belongs. For the mechanics, see why Spec Kit’s skills are worth studying.

Vendors already show the ladder. Amazon ships it explicitly, and Anthropic’s current guidance covers its two ends: direct prompting by default, and a SPEC.md worth checking a diff against when the work warrants one. “Spec vs plan” is a false binary; both vendors’ guidance covers more than one rung.

Implementation: The One-Page Intent Contract

For Tier 2 work (most shared features), replace the spec stack with a single page the agent interviews you to produce. Anthropic documents this pattern directly. It asks Claude to interview you until it could write the spec, save it, and start a fresh session to build from it. Implementation then begins with clean context and a written definition of done.

# INTENT: <feature name>

## Why (2-3 sentences, human-owned)
What problem, for whom, and what happens if we do nothing.

## What "done" means (acceptance criteria)
- [ ] <observable behavior, testable>
- [ ] <edge case that must not regress>
- [ ] <explicit non-goal: what we are NOT building>

## Constraints Claude cannot see in the repo
- <decision made in a meeting, deploy quirk, external contract>

## Check to run
`pnpm test <path>` + `pnpm tsc --noEmit` — paste output as evidence.

Run it like this:

I want to add rate limiting to the public API but haven't thought it
through yet. Interview me until you could write the intent contract:
per-user vs per-key, over-limit behavior, what is out of scope.
Write it to INTENT.md. Do not implement yet.

Then, in a fresh session:

Implement INTENT.md. For each acceptance criterion, write or name the
test that proves it. Run the check in the contract, paste the output,
and keep going until it passes. If a criterion is ambiguous, stop and
ask instead of guessing.

Why this works:

• The interview does the forcing. That is Agarwal’s cognitive-forcing mechanism.
• The acceptance criteria give a reviewer, human or fresh subagent, something to check the diff against. That is Claude Code’s “review against your spec” pattern.
• The named check turns “looks done” into pass/fail evidence. Anthropic calls that the difference between a session you watch and one you walk away from.

Leave out file layout, component structure, and library choice. Current models can usually read those from the repo, and writing them down is the fastest-decaying part of a spec (Agarwal Finding 1).

When Full SDD Still Earns Its Ceremony

Persist the full stack when any one of these holds:

• Multiple humans must approve before code exists: product, architecture, compliance. The spec is the review surface.
• Audit or regulation requires a traceable line from requirement to implementation.
• Brownfield constraints are invisible in the code: cross-service contracts, migration order, invariants documented only in earlier specs. Agarwal’s participants reported exactly this failure: behavior that satisfied the immediate task while violating a constraint in an earlier spec.
• The cost of building the wrong thing dwarfs the planning cost. SDD shifts spend from rework to planning (Agarwal Finding 9: tokens, time, cognitive load). That trade pays off only for large, expensive-to-reverse work.

Budget for three known failure modes:

• Implementation drift: the agent departs from the spec.
• Spec decay: the spec goes stale as code changes. In Agarwal’s repository sample, 81.5% of spec files have a single recorded commit.
• Verification debt: the same agent writes the spec, code, and tests, so one misunderstanding propagates to all three.

The mitigations I would use: human-owned acceptance criteria even when agents draft everything else, acceptance criteria compiled into tests the agent must pass, and a reviewer that did not write the code.

Around Every Tier: The Harness

The other 2026 shift is that the durable investment moved around the task. ThoughtWorks’ harness engineering write-up (September 29, 2026) frames it as Agent = Model + Harness. Guides steer before action (context files, constraints, AGENTS.md/CLAUDE.md). Sensors verify after action (tests, linters, CI, review agents). Selective human gates sit between them.

That layer is tier-independent and compounds. It holds a short context file that records only what the agent cannot find by reading the repo, plus a check command in that file. Add a hook (a script that runs automatically at a fixed point in the agent’s workflow) for rules that admit no exceptions. A spec is per-change and decays. A harness is per-repository, and every failure it catches improves it. If you have an hour to invest, the harness repays it on every task; the spec repays it on one.

For the broader scaffolding question (when a prompt suffices and when agents need tools, evals, and workflow around them), see When Is a Prompt Enough?.

Run Your Own Experiment

The article’s central claim is that, for individual work, articulation is the likely driver, and persistence is situational. Your team can test it in two weeks with a design adapted from Agarwal’s proposal:

Rotate comparable medium features across arms. Record: total tokens, elapsed time, review rounds, defects or rework within a week, and, for arms B and C, whether anyone later needed the missing artifact and could not reconstruct the intent. If B ≈ A on quality and beats it on cost, persistence is ceremony for work like yours. If A wins on handoff and audit pain, you have measured where your Tier 3 boundary should sit. Either result is worth more than this article.

Decision Checklist

Before your next feature, thirty seconds:

1. One-sentence diff? → Build directly, with a check to run.
2. Uncertain, multi-file, unfamiliar? → Plan mode, iterate, implement, let it expire.
3. Someone else (human or agent) must rebuild the why later? → One-page intent contract in git.
4. Team gates, audit, invisible brownfield constraints, or expensive-to-reverse work? → Full SDD, human-owned acceptance criteria, tests compiled from them.
5. Any tier: can the agent run a pass/fail check without you? If not, write that first. It outranks another page of spec.

The methodology wars will continue; the vendors will ship new rungs and new acronyms. The evidence from 2026 supports a quieter conclusion: think before you delegate, write down only what must outlive the thinking, and make the result checkable. Articulate always. Spec sometimes.

Sources

• Agarwal, Singhal, Macvean, Vasilescu, Breaux, Spec-Driven Development as Prescribed and as Practiced — arXiv preprint, August 25, 2026. Selective use, spec decay/drift, planning costs, articulation (cognitive-forcing) hypothesis and the given-vs-withheld experiment proposal.
• Hill, Does Spec-Driven Development Reduce Defects? An Empirical Test of Industry Claims Across 119 Open-Source Repositories — ESEM Software Engineering in Practice track, ESEIW 2026, presented October 9, 2026. 88,052 PRs; no vendor hypothesis supported; sole protective signal in repositories with no AI adoption (less rework, p = 0.014); confounding by indication noted by the author.
• Liu, Dehghan, Ganhotra, Hirzel, Jabbarvand, From Plan to Action: How Well Do Agents Follow the Plan? — ASE 2026. 21,120 trajectories; standard plan helps, bad plan worse than no plan, reminders help. Scope: agent execution plans, not feature specs.
• Anthropic, Best practices for Claude Code — live page accessed October 29, 2026 (rewritten; it no longer covers plan mode). What it actually says: a plain prompt in a fresh session usually does the right thing by default; “Interview me until you could write the spec, then write it to SPEC.md”; once SPEC.md exists, build from it in a fresh session; the reviewer checks the diff against SPEC.md. Framing: “tell Claude what it can’t see, give it a check to run, and enforce the rules that can’t have exceptions.”
• Amazon Kiro, Plan mode and Feature Specs — accessed October 29, 2026. Plan vs spec tiers, 15–60 minute guidance, approval gates for high complexity/team/audit.
• Nadeem, Plan mode is dead — September 24, 2026. Practitioner post-mortem (n=1); “more information without creating more clarity”; planning ≠ plan.
• GitHub, Spec Kit README — accessed October 29, 2026. For the flow: lists /speckit-converge and “Repeat implement and converge until convergence reports Converged.”
• GitHub, Spec Kit v1.0.0 release — August 21, 2026. Cited only for the release date; the release page does not describe the Converge flow.
• Reddy Nandyala & Pani, ThoughtWorks, Engineering the harness — September 29, 2026. Agent = Model + Harness; guides, sensors, selective human gates.