Spec-Driven Development

Research Report: De "Prompt and Pray" a desarrollo basado en especificaciones

Marzo 2026

ThoughtworksGitHubArXivAugment CodeAmazon KiroTessl

El Problema — Por qué falla el Vibe Coding

66%de desarrolladores dicen que el código IA es "casi correcto pero no del todo"
+19%más lentos con IA — creyendo ser 20% más rápidos (estudio METR)
El modo dominante de fallo no es que el modelo se equivoque — es que se equivoca porque no sabía algo que el dev asumía como obvio.
Fuentes: Java Code Geeks (Mar 2026) · Stack Overflow Developer Survey 2025 · METR Study (Jul 2025)

¿Qué es SDD? — Definición

Paradigma que usa especificaciones como prompts estructurados para generar código ejecutable.
— Thoughtworks, Dec 2025
De 'code is the source of truth' a 'intent is the source of truth'.
— GitHub Blog, Sep 2025
Fuentes: Thoughtworks (Dec 2025) · GitHub Blog (Sep 2025) · ArXiv 2602.00180 (Feb 2026)

Los 3 Niveles de SDD

LEVEL 1

Spec-First

Markdown requirements → human review → agente implementa.

✦ Mejor punto de entrada. Bajo overhead, alto impacto.

LEVEL 2

Spec-Anchored

Spec + BDD scenarios + API contracts que VALIDAN el código generado.

✦ Para entornos regulados. Build falla si spec diverge.

LEVEL 3

Spec-as-Source

La spec ES el artefacto fuente. El código es output derivado.

✦ Enfoque radical. Tessl lidera esta visión.

Fuente: ArXiv 2602.00180 — "From Code to Contract in the Age of AI" (Feb 2026)

El Workflow — Las 4 Fases

1ResearchSubagentes paralelos investigan contexto, APIs, constraints
→
2Spec CreationRequirements, constraints, integration points, out of scope
→
3RefinementEntrevista: descubrir ambigüedades antes de codear
→
4ImplementationTask delegation + atomic commits. 1 task = 1 subagente
Cada fase DEBE completarse y revisarse antes de pasar a la siguiente. Saltarse fases es "prompt and pray" con pasos extra.
Fuentes: alexop.dev (Feb 2026) · Java Code Geeks (Mar 2026)

Anatomía de una Buena Spec

# Payment Service — Spec v1.2

## User Story
Como usuario autenticado, quiero
procesar pagos con tarjeta para
completar mi compra.

## Acceptance Criteria
- Procesa cobro en <3s (p95)
- Retry automático x2 en timeout
- Idempotency key por transacción

## Constraints — QUÉ NO CONSTRUIR
- NO implementar wallet/saldo
- NO soportar crypto
- NO custom billing UI

## Integration Points
- StripeGateway (existing)
- OrderService.complete()
- AuditLogger.log()

## Non-Functional
- PCI DSS compliance
- Structured logging (JSON)

## Out of Scope
- Refunds (separate spec)
- Multi-currency (Q3)

Secciones clave

  • User Story — El por qué
  • Acceptance Criteria — Medibles, no ambiguos
  • Explicit Constraints — La sección MÁS valiosa
  • Integration Points — Clases existentes con nombre
  • NFRs — Performance, seguridad
  • Out of Scope — Evita scope creep
Decirle al agente qué NO hacer es tan importante como decirle qué hacer.
Fuentes: Java Code Geeks (Mar 2026) · Zencoder SDD Guide

CLAUDE.md / AGENTS.md — La Constitución

CLAUDE.md

Project constitution. Reglas que el agente sigue SIEMPRE: estilo, arquitectura, prohibiciones.

AGENTS.md

Team standards, architecture decisions, patterns compartidos entre agentes.

Skills

Workflows reutilizables. Encapsulan procedimientos complejos en instrucciones atómicas.

Hooks

Gates automatizados: pre-commit lint, test suite, format check.

Ejemplo AGENTS.md

# AGENTS.md

## Architecture
- Hexagonal architecture
- No direct DB access from handlers
- All errors as typed Result<T,E>

## Conventions
- Tests: colocated *.test.ts
- Commits: conventional commits
- NEVER use `any` type
- NEVER add deps without asking

## Pre-commit Hook
npm run lint && npm test
Claude Code ha absorbido nativamente gran parte del tooling SDD.
— Panaversity / Agent Factory, 2026
Fuente: Panaversity (2026) · Anthropic Claude Code docs

Prompt Patterns Clave

1. PARALLEL RESEARCH 
"spin up multiple subagents for your research task"

5 agentes, cada uno investiga un aspecto diferente en paralelo.

2. SPEC-FIRST 
"your goal is to write a report/document"

Fuerza artefacto escrito antes de tocar código.

3. INTERVIEW 
"use ask_user_question before we implement"

Surfaces ambiguities. Descubre lo que no sabías que no sabías.

4. TASK DELEGATION 
"use task tool, each task by subagent, commit after each"

Context isolation + atomic commits. Cada task es reversible.

5. ROLE ASSIGNMENT 
"you are the main agent, subagents are your devs"

Establece jerarquía y expectativas de coordinación.

Fuente: alexop.dev — "SDD with Claude Code in Action" (Feb 2026)

Ecosistema de Herramientas (2026)

Open Source

GitHub Spec Kit

/specify → /plan → /tasks → implement. Compatible con Copilot, Claude, Gemini.

AWS

Amazon Kiro

Requirements → Design → Tasks. SDD workflow integrado. Ideal para ecosistemas AWS.

Commercial

Tessl

Framework + Registry. Spec-as-Source. "Single source of truth for skills and context."

Nativo

Claude Code

CLAUDE.md + Subagents + Tasks + Hooks. Sin framework externo necesario.

Open Source

CC-SDD

Cross-tool: 8 agentes, workflow unificado. Claude, Cursor, Gemini, Codex, Copilot, Windsurf.

JetBrains

Junie

IntelliJ-native. JVM-aware, lee Spring beans y Maven deps directamente.

Fuentes: GitHub Blog (Sep 2025) · Amazon Kiro docs · Tessl blog (Sep 2025) · Anthropic docs

SDD vs Todo lo Demás

TDDBDDVibe CodingSDD
Artefacto primarioUnit testsGiven/When/ThenPrompt naturalSpecs ejecutables
ScopeFunción individualComportamiento cross-functionalApp completaContratos arquitecturales
ValidaciónTest suiteDoc referenciadaReview manual (si acaso)Build falla si spec diverge
Gobernanza IANingunaNingunaNingunaConstitutional constraints
VersionableSí (código)ParcialNoSí (spec = artefacto)
RecuperabilidadRe-run testsRe-check docsEmpezar de ceroSpec como checkpoint
Fuentes: Augment Code (2026) · Thoughtworks (Dec 2025)

Caso Real — IndexedDB Migration

Migración SQLite → IndexedDB completada en un solo día con SDD + Claude Code

5

Subagentes paralelos investigando Jazz framework

14

Tasks ejecutadas, 14 commits atómicos

15+

Archivos modificados con consistencia

143k

tokens contexto principal (de 200k)

La spec actúa como punto de recuperación. Cuando una sesión se desvía, no pierdes todo.
Fuente: alexop.dev — "SDD with Claude Code in Action" (Feb 2026)

Cuándo Sí y Cuándo No

✅ Usar SDD

  • Refactors multi-archivo
  • Features nuevos en codebases existentes
  • Migraciones de datos o frameworks
  • Coordinación multi-equipo
  • Cualquier cambio que tarda más de 1 sesión
Si tarda más de 1 sesión, necesita spec.

❌ NO necesitas SDD

  • Quick fixes y bugfixes simples
  • Prototipos exploratorios
  • Cambios de configuración
  • Scripts one-off

⚠️ Thoughtworks advierte: workflows SDD demasiado rígidos y opinionados no escalan. La flexibilidad es clave.

Fuentes: Thoughtworks (Dec 2025) · alexop.dev (Feb 2026)

Datos y Estadísticas Clave

66%

devs frustrados con código IA "casi correcto"

Stack Overflow 2025

+19%

más lentos con IA vs sin IA

METR Study 2025

+41%

más complejidad en código IA vs manual

Estudio académico

+30%

más warnings en análisis estático con IA

Análisis estático

9.8-42.1%

código vulnerable generado por LLMs

Security research

20-45%

ganancia productividad con IA bien usada

McKinsey 2025

€35M

multas EU AI Act (o 7% facturación global)

EU AI Act

Fuentes: Stack Overflow 2025 · METR (Jul 2025) · McKinsey Technology Trends 2025 · EU AI Act

Conclusiones

1

SDD no es nuevo — es BDD/DDD evolucionado para la era IA

2

Las specs ejecutables son el diferenciador real vs solo "escribir mejor el prompt"

3

"Explicit Constraints" (qué NO hacer) es la sección más valiosa de una spec

4

El ecosistema está madurando rápido: GitHub, AWS, Tessl, Anthropic

5

Level 1 (Spec-First) es el punto de entrada correcto para la mayoría

6

"Intent is the new source of truth"

7

No todo necesita SDD — saber cuándo usarlo es tan importante como saber cómo

Fuentes: Síntesis del autor basada en todas las fuentes citadas

Fuentes y Referencias

— Fin del Research Report —