Who Did SDD Actually Save? Two Years of Hard Truths from AWS Kiro to Spec Kit

In mid-2025, the frenzy around generative AI in software engineering reached its zenith, just as the freewheeling exploration of “vibe coding” began showing signs of fatigue. Casual chat conversations quickly lost their bearings in complex codebases, and ambiguous prompts repeatedly forced models to guess at countless unspoken edge cases and boundary conditions.

Just then, AWS launched its spec-centric agentic IDE “Kiro”, followed swiftly by GitHub’s open-source toolkit “Spec Kit”. Spec-Driven Development (SDD) was thrust squarely into the industry spotlight.

This tooling wave arrived alongside an aggressive ideological rebrand from the major vendors. GitHub’s official blog broadcast a provocative battle cry: “From code is the source of truth to intent is the source of truth.” Sean Grove of OpenAI proclaimed in public keynotes that engineers deliver only 10% to 20% of their ultimate value in raw code—with the remaining 80% to 90% residing in structured communication. “The truly valuable artifact,” Grove declared, “is the spec, not the code.”

Two years have passed. As the first cohorts of teams and solo developers publish their extensive field-test postmortems, the chasm between promotional doctrine and day-to-day engineering reality has finally snapped into sharp focus.

The Three Tiers of the Spec: Where Are We Truly Trapped?

To diagnose the gap between ambition and reality in SDD, the three-tier classification proposed by Thoughtworks Distinguished Engineer Birgitta Böckeler on martinfowler.com serves as the definitive analytical lens:

The grand vision aggressively marketed by vendors invariably promises Tier 3—a world where software engineers casually dictate high-level intent in prose, and the machinery compiles faultless implementations behind the scenes.

Yet the sobering reality is simple: today’s premier tools (GitHub Spec Kit, AWS Kiro) succeed solely at Tier 1 (Spec-first). The moment teams attempt to anchor specifications for the long haul (Tier 2), the system collapses under its own overhead.

This profound divergence—practicing at Tier 1 while fantasizing about Tier 3—is the root cause of the friction and fatigue that follow.

Field Realities: Success Belongs Strictly to “Personal Craft”

Examining the publicly documented SDD experiments that delivered functional, durable software reveals an unmistakable pattern: every single success was an ephemeral spec written by an individual engineer, solely for themselves.

Mitchell Hashimoto’s Ghostty Case Study

When HashiCorp co-founder Mitchell Hashimoto added non-trivial features to his terminal project Ghostty, he practiced spec-first augmented coding. Through rigorous interactive dialogue with an agent, he drafted a focused plan, saved it as spec.md, sliced it into minimal work units, and meticulously reviewed each phase before execution. His takeaways boiled down to two essential concepts: interactive and smaller chunks. The spec was not a bureaucratic deliverable; it was a personal thinking scratchpad.

Harper Reed’s Three-File Workflow

Seven months before Spec Kit launched, former Obama Campaign CTO Harper Reed published his three-file workflow: spec.md → prompt_plan.md → todo.md. He invested 15 minutes defining scope and acceptance criteria with AI, executed in small, verifiable increments, and checked off tasks manually. Reed offered a decisive verdict: “Success or failure comes down entirely to how well you execute step two: the planning.”

Automated Security Exercises in the Wild

In Taiwan’s iT Home Ironman competition, a practitioner deployed AWS Kiro’s Specs, Steering Files, and Hooks to construct an automated Red Team exercise suite. Structured specs successfully prevented the model from wandering off course during long horizons, with the agent even catching subtle race conditions during architectural review. Crucially, success stemmed not from the tool’s automated scaffolding, but from the engineer actively treating specifications and steering files as manual levers to constrain context.

These case studies converge on an unambiguous truth: the specification shines brilliantly as an engineer’s personal navigation instrument. It forces humans to clarify boundary conditions before code is written, keeping humans at the helm rather than surrendering control to automated code generators.

The Bureaucratic Quagmire: When Specs Become Corporate Ceremony

However, the moment vendors institutionalized this nimble, personal craft into a rigid cascade of “Constitution → Specs → Design → Tasks → Implementation,” the methodology flipped into an operational trap.

The Burden of Double Review and “Sledgehammers for Walnuts”

Documenting her hands-on evaluation of AWS Kiro on martinfowler.com, Birgitta Böckeler described her shock when fixing a trivial bug triggered the automated generation of 4 user stories and 16 acceptance criteria. Staring at an unprompted mountain of markdown, Böckeler delivered the quote of the debate:

“Honestly, I’d rather review code than review a bunch of markdown files.”

François Zaninotto, founder of marmelab, documented this contrast in “Spec-Driven Development: The Waterfall Strikes Back”. He tasked GitHub Spec Kit with implementing a feature as trivial as “displaying the current date.” The framework produced 8 files spanning 1,300 lines of specification text. Meanwhile, using lightweight conversational iteration without upfront specs, Zaninotto built a functional 3D sculpting tool from scratch in just 10 hours.

Justhings, a prominent voice in Taiwan’s agile community, labeled the phenomenon the “Zombie Waterfall of the AI Era”: developers morph into fatigued compliance officers, “spending 80% of their working hours parsing bloated markdown, hunting for logic holes hidden inside professional-sounding filler.” Far from reducing cognitive overhead, workload doubled because teams had to maintain two competing sources of truth: the documentation and the codebase.

Spec Drift and the Impossibility of Verifying Prose

Natural language inherently lacks the determinism of code and the unyielding verification of a compiler. Independent developer Jakša Vucković experienced the quintessential breakdown in his field test of Spec Kit: after generating 47 granular tasks and 3 user stories, inconsistencies surfaced. When instructed to correct the deviation, the agent updated only a subset of the documents, sending cascading dependencies into chaos.

Vucković ended up with zero automated tests and an application that failed to run. He concluded that natural language specifications force developers into “getting the worst of both worlds: the complexity of code and the lack of verifiability of documentation,” drowning in administrative overhead before generating a single line of working software.

Agents Do Not Reliably Obey Instructions

More fundamentally, base model capabilities repeatedly failed the ceremony. Despite exhaustive checklists, coding agents routinely skipped instructions. Zaninotto caught an agent marking “write unit tests” as completed while delivering only manual testing instructions. In brownfield systems, developer Rebekka Hubert discovered that AI-authored architecture docs appeared logically sound on the surface, but cited underlying system mechanics that were entirely fabricated—flaws detectable only by painstakingly inspecting call graphs by hand.

Expert Perspectives: Embracing Thought, Rejecting Dogma

Faced with this debate, respected leaders and seasoned practitioners across software engineering have drawn a distinct line: embrace deliberate planning, but reject sanctifying the spec.

Planning Ahead as High-Leverage Craft

• Simon Willison (Co-creator of Django): Views specification design as a core competency. He famously described AI as an “eccentric digital intern that will cheat whenever given the chance,” requiring engineers to iterate exhaustively on the plan before letting agents write code.
• Kent Beck (Pioneer of XP & TDD): Relies on plan.md in augmented coding, but anchors it strictly within the TDD feedback loop: “You still have to care about the code, the complexity, the tests, the coverage. You cannot place your confidence in unverified specs.”
• Thorsten Ball (Sourcegraph / Amp): Analogized this relationship to paint-by-numbers: humans draw the outlines and number the sections, while agents fill in the colors—architectural authority is never casually outsourced.

Piercing the “Spec as Code” Myth

• Armin Ronacher (Creator of Flask): An unapologetic practitioner of direct-to-implementation “YOLO mode,” cutting through the tooling mystique: “The path to specifications in prompts runs through the file system anyway.” In his eyes, plan mode holds no magic; it is fundamentally the handoff of Markdown files, and inflating it into an elaborate ritual is entirely gratuitous.

• Addy Osmani (Engineering Director, Google Chrome): Delivered the most devastating technical verdict:

  “A spec detailed enough to be a program is just code written in a slower language.”

  Natural language cannot be compiled or debugged. When AI compresses implementation into mere hours, over-specified documents accumulate “intent debt” that humans must ultimately repay through engineering.

• DHH (Creator of Ruby on Rails): Poured cold water on exaggerated marketing: “I’m far away from the ‘let the agent write 90%+ of the code’ that people on the internet seem to love boasting about.”

Ebb and Renewal: The Lightweight Endgame of 2026

The market and open-source communities are invariably more honest than theoretical hype.

By 2026, even Tessl, once the most aggressive spec-centric platform, quietly shifted its homepage tagline from “spec is the new code” to “Skills are the new code,” abandoning its dogmatic commitment to the monolithic spec narrative.

Within the developer community, this introspection spurred real tooling evolution:

• Frustrated by the bloat of existing frameworks, a developer on V2EX built LeanSpec, enforcing a strict ceiling: specs must be under 300 lines and readable within 10 minutes.
• Many more engineers simply skipped standalone SDD frameworks altogether, turning instead to editor-native Plan Modes in tools like Cursor and Claude.

The triumph of native Plan Mode signals a profound paradigm shift: it completely abandons the ambition of long-term document maintenance. Plan Mode is ephemeral context designed for single use. You spend a few minutes aligning intent before writing code, and once the task is done, the context gracefully retires—never forced into becoming a permanent artifact in the repository. It is precisely this pragmatic refusal to build shrines out of documentation that sidesteps the twin traps of spec drift and double reviews.

Conclusion: Returning to the True Source of Truth

Two years of field testing have proven that specifications can never replace the essence of software engineering. In the AI era, the scarcest resource remains the human capacity to think clearly through problems and boundary conditions.

This journey leaves software developers with three concrete takeaways:

1. Spec weight must strictly match task complexity: A minor bug requires nothing more than a sentence in a chat box; only complex, cross-cutting changes justify structured Markdown plans.
2. Never abdicate code review: Reviewing specs is never a substitute for reviewing code. Test suites and runtime behavior will always be more honest than natural language prose.
3. Code remains the only true source of truth: GitHub’s slogan “intent is the source of truth” proved to be a seductive illusion. Natural language is riddled with ambiguity and drift. Only code that compiles, passes tests, and runs in production serves as the real anchor.

Treating specs as disposable scratchpads rather than sacred bureaucratic dossiers—returning specifications to their rightful place as lightweight aids to thinking—is the only sober way to work alongside AI over the long haul.