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” was wearing thin. Casual chat sessions quickly lost their bearings in complex codebases, and ambiguous prompts repeatedly forced models to guess at countless unspoken edge cases and boundary conditions.

Against that backdrop, 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 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 wave of teams and solo developers publish their field-test postmortems, the chasm between promotional doctrine and day-to-day engineering reality has finally come into clear focus.

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

For diagnosing 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 rested on 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

Just over six months before Spec Kit launched, former Obama Campaign CTO Harper Reed published his three-file workflow: spec.md → prompt_plan.md → todo.md. He spent 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 over 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 is enormously powerful as an engineer’s personal navigation instrument. It forces engineers 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 as a rigid cascade of “Constitution → Specs → Design → Tasks → Implementation,” the methodology turned 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 a lament that would be widely quoted:

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

François Zaninotto, founder of marmelab, documented an even starker experiment in “Spec-Driven Development: The Waterfall Strikes Back”. One developer 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.

As a counterpoint, Zaninotto built a 3D sculpting tool in about 10 hours, iterating conversationally without any upfront spec.

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, it doubled the workload 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 binding constraints of a compiler. Independent developer Jakša Vucković experienced a quintessential breakdown in his field test of Spec Kit: after the spec generated 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 the intricate web of cross-document dependencies out of control.

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 directly, base model capabilities repeatedly failed to live up to the ceremony. Despite exhaustive checklists, coding agents routinely skipped instructions. Zaninotto caught an agent marking the “verify implementation” task as completed while delivering only manual testing instructions. In brownfield experiments, developer Rebekka Hubert discovered that AI-authored contract docs appeared logically sound on the surface, but cited underlying system mechanics that were entirely wrong—flaws detectable only by manually tracing call graphs.

Expert Perspectives: Embracing Thought, Rejecting Dogma

Faced with this debate, respected leaders and seasoned practitioners across software engineering have drawn a clear 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 (“in augmented coding you care about the code, its complexity, the tests, & their coverage”); confidence comes from passing tests, not from unverified specs.
• Thorsten Ball (Co-founder of Amp): Analogizes 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.

Puncturing 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 (then a Director at Google): Delivers the most devastating technical judgment:

  “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): Pours cold water on exaggerated marketing: “I’m nowhere close to the claims of having agents write 90%+ of the code, as I see some boast about online.”

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, had swapped its homepage tagline twice within a matter of months—from “You make the spec, AI codes & maintains” to “Skills are the new code,” then to “Build your software factory, one skill at a time”—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, championing specs that stay under 300 lines and can be read in 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. It asks for a few minutes of intent alignment before coding, 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 substitute for the core work of software engineering. In the AI era, the scarcest resource remains the human capacity to think clearly about problems and their boundary conditions.

This exploration leaves software developers with three concrete takeaways:

1. Spec weight must scale with 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 abandon 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.