Skip to main content

Limits, Trade-offs & What's Realistic

The Question We Should Ask​

A critical analysis by Robert Matsuoka argues that Specification-Driven Development (SDD) serves dual purposes: solving real problems BUT also providing "governance narratives that justify enterprise procurement and enable disconnected valuations."

Fair question. Let's address it honestly.

The Critiques Are Valid​

1. The TDD Parallel Warning​

The concern: Test-Driven Development has <20% adoption after 20 years despite proven benefits. Failed due to timing pressures, cargo cult practices, and adoption barriers.

The similar risk for SDD: The methodology requires complete specifications before implementation—precisely what software has struggled with for 50 years.

Our response: LeanSpec explicitly rejects "complete specifications upfront." Our Context Economy principle (under 300 lines) and Intent Over Implementation approach focus on capturing WHY/WHAT, not exhaustive HOW. We're not asking for waterfall requirements—we're asking for enough intent to align humans and AI.

2. The 70% Automation Myth​

The concern: Real-world METR study found developers took 19% longer with AI despite believing they were 20% faster. The "70% automation" claim is inflated—it's only 27% of total dev work (39% time coding × 70% automation).

Our response: We don't promise automation percentages. LeanSpec is about alignment and intent documentation, not automation claims. Realistic outcome: 10-30% productivity improvement through better human-AI collaboration, not elimination of human work.

3. AI Agents Still Make Mistakes​

The concern: Martin Fowler's experiments showed that despite detailed specs, AI agents still generate unrequested features, change assumptions mid-stream, and claim success when builds fail.

Quote from Fowler: "Because of the non-deterministic nature of this technology, there will always remain a very non-negligible probability that it does things that we don't want."

Our response: We agree. Specs don't eliminate AI unpredictability—they reduce it. The goal isn't autonomous coding; it's better-informed AI suggestions that humans review. Specs provide context that makes AI outputs more aligned with intent.

4. SDD Could Be Transitional​

The concern: "If models become sufficiently deterministic and context-aware, specifications become unnecessary overhead."

Our response: Probably true. If AI gets good enough, you might need less structure. But even then:

  • Human-to-human alignment still needs documentation
  • Specs that capture INTENT (not just implementation) age better
  • Progressive Disclosure means you can use LESS structure as AI improves, not abandon the methodology

We're useful TODAY because AI is unpredictable. If AI improves dramatically, adapt accordingly.

Where Specs ARE Theater​

Let's be specific about when specs become governance theater rather than productive tools:

❌ Theater: Specs as Checkbox Exercise​

  • Symptom: Writing specs to justify budgets without measuring outcomes
  • Example: Enterprise requires specs for procurement, but nobody reads them after approval
  • Result: Wasted effort, no alignment benefit

❌ Theater: Complete Upfront Requirements​

  • Symptom: Requiring exhaustive specifications before any coding (waterfall trap)
  • Example: 2,000-line PRD that tries to specify every edge case before discovery
  • Result: Context overflow, stale docs, AI can't help

❌ Theater: Specs AI Will Ignore Anyway​

  • Symptom: Writing specs AI doesn't read or can't fit in context window
  • Example: Verbose documentation that exceeds token limits
  • Result: Human effort wasted, AI generates code without spec context

❌ Theater: Rigid Process Over Pragmatism​

  • Symptom: Multi-step workflows required for all changes regardless of size
  • Example: Bug fix requires spec → plan → tasks → approval → implementation
  • Result: Process overhead kills velocity

Where Specs ADD Value​

When specs genuinely improve outcomes, not just check compliance boxes:

✅ Value: Team Alignment on Complex Features​

  • Scenario: Multiple developers need coordinated understanding
  • Benefit: Shared source of truth prevents divergent implementations
  • Result: Less rework, faster progress

✅ Value: Intent Preservation​

  • Scenario: Decisions need documentation for future reference
  • Benefit: "Why" is captured, not just "how"
  • Result: Future changes respect original constraints and trade-offs

✅ Value: AI Context Without Overflow​

  • Scenario: Feature is too complex for pure vibe coding
  • Benefit: Spec under 300 lines fits in AI context window
  • Result: AI actually reads and incorporates spec into suggestions

✅ Value: Progressive Refinement​

  • Scenario: Requirements emerge through implementation (Spec-Driven Development style)
  • Benefit: Spec evolves as you learn, maintaining alignment
  • Result: Living documentation that stays relevant

The Theoretical Foundation: Rice's Theorem​

A deeper reason why human involvement is necessary comes from computer science fundamentals.

Rice's Theorem (1951) proves that all non-trivial semantic properties of programs are undecidable—no algorithm can determine whether an arbitrary program has any interesting behavioral characteristic.

What This Means for SDD​

The undecidable question: "Does this program do what the user wants?" (requires understanding undefined intent)

The tractable question: "Does this program satisfy these explicit specifications?" (checking defined requirements)

Key insight: Specifications don't "solve" undecidability—they provide the semantic grounding that makes verification tractable. Humans define what "correct" means; AI generates implementations and tests within those constraints.

Why AI Can't Replace Human Specs​

Rice's Theorem explains why:

  1. Semantic properties are undecidable - AI can't algorithmically determine what you want
  2. Specs provide grounding - Humans translate intent into checkable assertions
  3. AI amplifies, doesn't replace - AI generates code/tests from human-provided specs
  4. Testing is sampling, not proof - Even with specs, we build confidence through heuristic testing, not mathematical certainty

From the Rice's Theorem article:

"Understanding that complete test automation is mathematically impossible doesn't leave us helpless—it guides us toward more effective strategies. The key insight is that we can dramatically improve testing effectiveness by combining formal specifications with AI-driven test generation."

This is exactly LeanSpec's philosophy: Humans provide intent (specs), AI amplifies scale (implementation), both work within theoretical constraints.

How LeanSpec Differs From The Critique​

The Hyperdev article critiques SDD frameworks like Tessl ($125M, delivered only beta registry) and rigid methodologies. Here's where LeanSpec positions differently:

We're NOT:​

  • ❌ Promising 70% automation or autonomous coding
  • ❌ Selling a $125M platform or $10B IDE
  • ❌ Requiring rigid 5-step workflows before any code
  • ❌ Claiming specs eliminate AI unpredictability
  • ❌ Demanding complete upfront specifications

We ARE:​

  • ✅ Free, open-source tooling (no venture capital, no valuation hype)
  • ✅ Pragmatic about when specs help vs hurt (explicit "when NOT to use specs" guidance)
  • ✅ Tool-agnostic (works with any editor, any AI assistant)
  • ✅ Addressing real pain: team alignment, context rot, decision documentation
  • ✅ Starting minimal, adding structure only when you feel pain (Progressive Disclosure)

The Positioning Difference​

From the article: "SDD functions as quality control theater... but the methodology also provides governance narratives that justify enterprise procurement and enable disconnected valuations—it's both solution and symptom."

LeanSpec's stance: We're the "solution" part without the "symptom" part:

  • Specs enhance judgment, they don't replace understanding your codebase
  • Structure that grows with your team (solo → enterprise)
  • No promises of revolutionizing software creation—just pragmatic documentation

Surviving The Correction​

The Hyperdev article predicts AI bubble correction in 18-24 months. Here's why LeanSpec is positioned differently:

Survivors Share These Traits​

Per the article, survivors will be tools that "enhance rather than replace core capabilities."

That's us:

  • Specs don't replace coding judgment—they enhance human-AI alignment
  • No autonomous coding claims—just better-informed suggestions
  • Free tooling with no valuation to justify
  • Works within theoretical constraints (Rice's Theorem), not against them

What Kills Companies in Corrections​

  • Burning capital on "technical potential" rather than paying customers
  • Promising automation that exceeds what's theoretically possible
  • Rigid processes that don't adapt to reality
  • Disconnected valuations from actual utility

LeanSpec avoids these:

  • Open source, no capital burn
  • Honest about limits (no 70% automation promises)
  • Progressive disclosure (adapt to team needs)
  • Free to use, value measured in productivity not valuation

The Honest Assessment​

Specs CAN be theater. When they're:

  • Required for procurement but nobody reads them
  • Exhaustive upfront requirements that exceed context limits
  • Rigid processes applied to trivial changes
  • Documentation that stays static while code evolves

Specs ADD value when:

  • Team needs alignment on complex features
  • Intent must persist beyond conversations
  • Decisions need documentation for future reference
  • Specs fit in AI context windows and actually inform implementation
  • Structure adapts progressively to team needs

LeanSpec's philosophy:

  • Be honest about limitations (Rice's Theorem proves complete automation is impossible)
  • Start simple, add complexity only when pain is felt (Progressive Disclosure)
  • Keep specs short enough to actually use (<300 lines, Context Economy)
  • Focus on intent that ages well (Intent Over Implementation)
  • Work with AI's strengths, acknowledge its weaknesses

The Question You Should Ask​

Not: "Should I use SDD?"

But: "Does formalizing intent into a spec add value for this specific work?"

Answer YES when:

  • Feature is complex enough that vibe coding causes misalignment
  • Team needs shared understanding
  • AI needs structured context to help effectively
  • Decisions should be documented for future maintainers

Answer NO when:

  • Change is trivial and obvious
  • You're still exploring and discovering requirements
  • Overhead exceeds benefit
  • Prototype that won't be maintained

LeanSpec gives you the tools to say YES efficiently when it matters.

Further Reading​

The bottom line: We're not selling a revolution. We're offering pragmatic tools for a real problem—keeping humans and AI aligned through lightweight, maintainable specs. If that's theater, it's the kind that actually improves the show.