Spec-Driven Development (SDD) es la práctica de tratar la especificación de un software como el artefacto central del ciclo de desarrollo, no como un documento descartable que se convierte en un PowerPoint y muere. En 2026, con agentes de IA escribiendo cada vez más código, el SDD se volvió la forma más sana de garantizar que lo que se genera corresponde a lo que se pidió, con trazabilidad y validación automatizada.
Esta guía explica qué es el SDD, por qué resurgió en la era de la IA, cuál es la diferencia con BDD y TDD, y cómo adoptarlo sin caer en la burocracia.
Qué cambió para que el SDD se volviera un tema central
Durante décadas, "spec" fue sinónimo de un documento Word olvidado en SharePoint. El código era la fuente de la verdad. Los comentarios y los tests documentaban la intención cuando tenían suerte. El SDD lo invierte: la spec es la fuente de la verdad, descrita en un formato legible por humano y máquina (Markdown estructurado, YAML, JSON Schema, OpenAPI, Gherkin). El código se genera, se valida y se mantiene a partir de ella.
El detonante fue la llegada de los agentes de codificación (Claude Code, Cursor, Copilot Workspace, Aider, herramientas internas con el Claude Agent SDK). Estos agentes funcionan mucho mejor cuando reciben una spec clara, con criterios de aceptación, reglas de negocio y ejemplos, en vez de pedidos vagos como "implementa este endpoint". La consecuencia práctica: los equipos que escriben buenas specs cosechan mejor código, más rápido y con menos retrabajo.
Anatomía de una buena spec
Una spec útil tiene cinco secciones. 1. Contexto y objetivo: qué problema resuelve, para quién, por qué ahora. 2. Comportamiento esperado: descripción del flujo principal y de los casos borde. 3. Contratos: el schema de la entrada, el schema de la salida, el formato de error. 4. Criterios de aceptación: una lista de afirmaciones verificables ("dado X, cuando Y, entonces Z"). 5. No-objetivos: lo que explícitamente está fuera del alcance, para que no se vuelva un proyecto sin fin.
Una spec mala es genérica, sin criterio de aceptación, sin schema, y cabe en cualquier interpretación. Una buena spec es específica, con un schema riguroso, ejemplos concretos y claridad sobre lo que no debe hacer.
SDD vs TDD vs BDD
Las tres disciplinas comparten el mismo gen: escribir la intención antes del código. Las diferencias importan. TDD (Test-Driven Development): escribes el test antes de la implementación. Foco en la verificación granular. Sufre cuando el test es frágil o cuando la intención real no cabe en "este retorno es igual a este". BDD (Behavior-Driven Development): escribes escenarios en lenguaje natural estructurado (Gherkin). Foco en el comportamiento legible por producto. Sufre cuando los escenarios se vuelven un enredo de step definitions. SDD: escribes la spec completa, incluyendo contratos, criterios y ejemplos, antes de cualquier código. Foco en ser una fuente canónica reutilizable por humanos y agentes de IA.
En la práctica, el SDD contiene al BDD (los escenarios se vuelven parte de los criterios de aceptación) y el TDD nace naturalmente de él (cada criterio se vuelve al menos un test).
SDD con agentes de IA
La ganancia más visible del SDD aparece cuando le pides a un agente que implemente una feature. Con una spec rica, el agente genera código que pasa los criterios de aceptación a la primera en la mayoría de los casos. Sin spec, el agente rellena los vacíos con suposiciones, y descubres las suposiciones equivocadas después.
Un flujo maduro tiene tres pasos. Primero, un humano escribe o refina la spec con ayuda del agente (el agente hace preguntas, propone escenarios olvidados, sugiere edge cases). Segundo, el agente implementa la feature a partir de la spec, con tests derivados de los criterios. Tercero, un humano revisa la spec, el código y los tests lado a lado, con diffs comparables.
Herramientas y formatos populares en 2026
El ecosistema creció. OpenAPI / AsyncAPI: estándar de facto para APIs REST y event-driven. JSON Schema: para la validación de payloads y configuración. Gherkin (Cucumber): para escenarios comportamentales. Markdown estructurado con frontmatter: para specs de feature legibles por agentes. Spec Kit de GitHub e iniciativas similares: para estandarizar el formato de spec consumida por copilots. Pydantic / Zod / TypeBox: para generar runtime validators a partir de schemas declarativos.
Antipatrones de SDD
Las cuatro trampas más comunes. 1. Una spec gigantesca y desactualizada: una spec sin dueño y sin ciclo de revisión se vuelve folclore. Trata la spec como código: tiene PR, tiene review, tiene versionado. 2. Una spec genérica sin criterio de aceptación verificable. Si no se puede escribir un test a partir de ella, no es una spec. 3. Una spec solo de producto, sin contratos técnicos. Usa la spec para alinear producto, ingeniería y QA, no solo a una de las partes. 4. Una spec después del código: la documentación retroactiva no tiene el mismo valor. El SDD funciona porque la spec viene antes.
Cuándo el SDD no vale la pena
El SDD no es gratis. Para un script descartable, un one-off de migración, o un spike exploratorio, escribir una spec es un overhead que no retorna. El SDD brilla en el código que va a durar, ser mantenido por más de una persona, ser extendido con agentes, y que tiene criterios de calidad no negociables (APIs públicas, módulos críticos, integraciones con sistemas externos).
SDD en Steply
En Steply, el SDD es práctica estándar en todos los squads que construyen producto con IA. Toda feature empieza con una spec corta, escrita junto con el cliente, que contiene el objetivo, los contratos, los criterios y los no-objetivos. Esa spec se vuelve el briefing del agente, se vuelve la base de los tests, se vuelve el changelog y se vuelve el material de revisión. El efecto compuesto es una entrega más rápida con menos retrabajo, menos discusión de "no era esto lo que pedí", y código más alineado con lo que el negocio necesita.