Spec-driven development: de una idea al código con personas y agentes de IA

Imagina que le dices a un técnico:

"Arréglame el aire acondicionado."

El técnico podría hacerlo. Pero antes necesita saber qué pasa: ¿no enciende?, ¿enfría poco?, ¿hace ruido?, ¿pierde agua?, ¿qué modelo es?, ¿hay un presupuesto máximo?

En software pasa lo mismo.

Cuando alguien dice "haz una página de reservas" o "ponle login con Google", parece que dio una instrucción clara. En realidad, dio el inicio de una conversación. Faltan reglas, excepciones y una definición de "listo".

Spec-driven development (SDD) es una forma de ordenar esa conversación antes de escribir código.

Idea clave

Antes de construir, escribe qué debe hacer el sistema, qué no debe hacer y cómo sabrás que funciona.

No necesitas documentos gigantes. Necesitas menos suposiciones.

Primero: ¿qué significa ese nombre?

"Spec" viene de specification, o especificación. Y driven development es desarrollo guiado; definido completo sería: desarrolla basado o guiado en las especificaciones.

Una especificación es una lista clara de acuerdos sobre una función. No es código. Tampoco es una novela técnica. Es una respuesta corta y concreta a preguntas como estas:

• ¿Qué problema resolvemos?
• ¿Para quién?
• ¿Qué debería pasar cuando todo sale bien?
• ¿Qué pasa si algo falla?
• ¿Qué no vamos a construir ahora?
• ¿Cómo comprobamos que quedó bien?

Mira esta diferencia.

Pedido sin especificación

Haz que los clientes puedan pedir una reparación desde la web.

Pedido con especificación

Un cliente puede enviar una solicitud de reparación.

Debe indicar nombre, teléfono, zona y descripción del problema.
La solicitud se guarda con estado "pendiente".
El cliente recibe un número de solicitud en pantalla.
No se aceptan pagos ni fotos en esta primera versión.
Si falla el guardado, no se debe mostrar un mensaje de éxito.

El segundo pedido deja mucho menos espacio para interpretar mal.

¿Por qué nació esta forma de trabajar?

No apareció de la nada con la inteligencia artificial.

Desde hace mucho tiempo, los equipos de software usan requisitos, historias de usuario, casos de uso, contratos de API y pruebas de aceptación. Todos buscan lo mismo: ponerse de acuerdo sobre el resultado antes de construirlo.

La IA hizo que esa disciplina volviera a ser urgente.

Un agente puede crear archivos, pantallas, endpoints y pruebas muy rápido. Eso es útil. También significa que puede construir una idea equivocada a gran velocidad si la instrucción es vaga.

Piensa en un agente como un técnico muy rápido que nunca se cansa. Si le dices "arregla esto", tomará decisiones por su cuenta. Si le das una lista clara de síntomas, límites y resultado esperado, tendrá muchas más posibilidades de acertar.

Herramientas modernas para agentes, como Kiro y GitHub Spec Kit, organizan este proceso en tres pasos sencillos:

1. Requisitos: qué debe ocurrir.
2. Diseño: cómo podría construirse.
3. Tareas: qué se hará paso a paso.

No es magia. Es una buena conversación puesta por escrito.

¿Para qué sirve?

Spec-driven development es útil cuando equivocarse cuesta más que explicar bien el pedido.

Por ejemplo, algunos casos de la vida real podrían ser:

Caso 1: dinero

Si cambias pagos, suscripciones, facturas o descuentos, una decisión pequeña puede afectar dinero real.

Ejemplo:

Permitir cancelar una suscripción.

Antes de programar, hay que aclarar:

• ¿Se cancela hoy o al terminar el mes ya pagado?
• ¿Hay reembolso?
• ¿Se pierde acceso de inmediato?
• ¿Qué pasa si Stripe o el proveedor de pagos falla?

Caso 2: datos de clientes

Si se guardan teléfonos, direcciones, documentos o información personal, necesitas definir quién puede verla y cuánto tiempo se conserva.

Caso 3: servicios conectados

Si tu sistema habla con correo, WhatsApp, Google, Cloudflare o un proveedor de pagos, debes decidir qué hacer cuando el otro servicio no responde.

Caso 4: agentes de IA

Si un agente implementará parte del trabajo, una especificación evita que el agente se convierta también en gerente de producto, arquitecto, QA y adivino.

Regla fácil de recordar

Si dos personas pueden entender la tarea de maneras distintas, escribe una especificación.

Una especificación no es el diseño técnico

Esta parte confunde a mucha gente al principio.

Una especificación dice qué resultado quieres.

Una persona puede descargar sus datos desde su perfil.

Un diseño técnico dice cómo planeas lograrlo.

El sistema prepara un archivo CSV, lo guarda por 24 horas y envía un enlace al usuario.

Los dos son importantes. Pero no son lo mismo.

¿Por qué separarlos? Porque el resultado puede seguir siendo correcto aunque cambie la solución técnica. Hoy podrías crear un CSV. Mañana quizá necesites JSON o un archivo ZIP. La promesa principal sigue siendo: "la persona puede descargar sus datos".

Vamos con un ejemplo completo

Usaremos un caso cercano de un cliente que tengo: una página para que los clientes de Eddy Reparaciones pidan ayuda.

La petición inicial

Haz un formulario para solicitudes de reparación.

No está mal. Solo está incompleta.

Un agente podría crear una pantalla bonita y aun así dejar preguntas sin responder:

• ¿Qué campos son obligatorios?
• ¿Dónde se guardan las solicitudes?
• ¿Qué ve el cliente al terminar?
• ¿Puede enviar la misma solicitud dos veces?
• ¿Vamos a cobrar desde ahí?

La especificación

# Solicitud de reparación desde la web

## Objetivo
Permitir que un cliente envíe una solicitud de reparación desde el sitio web de Eddy Reparaciones.

## Datos que pedimos
- Nombre completo.
- Teléfono.
- Sector o dirección.
- Tipo de reparación.
- Descripción del problema.
- Horario preferido.

## Reglas
- Todos los campos son obligatorios, excepto detalles adicionales.
- El teléfono debe tener al menos 7 dígitos.
- Al enviar, el cliente ve una confirmación y un número de solicitud.
- La solicitud se guarda con fecha y estado inicial "pendiente".
- Un doble clic rápido no debe crear dos solicitudes iguales.

## Si algo sale mal
- Si falta un dato, se indica el campo que falta.
- Si no se puede guardar la solicitud, no se muestra una confirmación falsa.

## No vamos a hacer esto todavía
- Cobros en línea.
- Panel completo para técnicos.
- Adjuntar fotos o videos.
- Agenda automática.

## Cómo sabremos que funciona
- [ ] Una solicitud válida se guarda una sola vez.
- [ ] El cliente recibe un número de solicitud.
- [ ] Datos inválidos no se guardan.
- [ ] Si la base de datos falla, el cliente ve un error real.

¿Notas algo? Esta especificación no dice si usaremos React, PHP, Python, una base de datos específica o una API concreta. Eso viene después.

Primero acordamos qué debe pasar.

El momento "ajá": una especificación también es una lista de pruebas

Cada regla importante debería poder comprobarse.

Por ejemplo:

Si una frase no se puede probar, suele ser una señal de que todavía está demasiado abierta.

Por ejemplo:

El formulario debe ser fácil de usar.

Es buena intención, pero nadie puede verificarla sin concretar un poco más.

Podrías reemplazarla por esto:

- Los campos obligatorios se ven claramente.
- Cada error aparece junto al campo incorrecto.
- El botón de envío se bloquea mientras se procesa la solicitud.
- El cliente ve una confirmación al terminar.

Ahora sí hay algo que revisar.

Cómo usar una especificación (SDD) con un agente de IA

Aquí viene la parte práctica.

No le des al agente solamente esto:

Haz un formulario de reparaciones.

Dale la especificación y pídele que trabaje por etapas.

Prompt para la primera etapa

Lee la especificación docs/specs/solicitud-reparacion.md.

Todavía no modifiques archivos.

1. Dime qué preguntas siguen abiertas.
2. Propón un diseño técnico mínimo.
3. Divide el trabajo en tareas pequeñas.
4. Relaciona cada criterio de aceptación con una prueba.

No implementes hasta que apruebe el plan.

Este prompt hace algo importante: evita que el agente empiece a construir antes de que tú hayas visto el plan, igualmente podrias poner esto en modo plan con la IA que trabajes claude o codex, etc.

Prompt para la implementación

Después de aprobar el diseño, puedes darle esto:

Implementa el plan aprobado para la solicitud de reparación.

Reglas:
- Respeta la especificación.
- No agregues pagos, login, panel administrativo ni adjuntos.
- Haz cambios pequeños y explica cada uno.
- Escribe y ejecuta pruebas para cada criterio de aceptación.
- Al terminar, entrega:
  1. archivos modificados,
  2. resultados reales de las pruebas,
  3. criterios que no se pudieron verificar,
  4. instrucciones para probarlo manualmente.

Este promp por igual puedes correrlo con auto mode o manual dentro de la IA que especificas

Ojo

Un agente puede decir "terminé". La especificación y las pruebas son la forma de verificar esa afirmación.

¿Y si trabajo con varios agentes?

También funciona. La especificación actúa como el mapa que todos comparten.

Para la página de solicitudes de Eddy Reparaciones, podrías repartir el trabajo así:

Agente 1: revisa requisitos y detecta dudas.
Agente 2: diseña la interfaz del formulario.
Agente 3: crea el endpoint y el guardado de datos.
Agente 4: escribe pruebas de validación e integración.
Agente 5: revisa que todo cumpla la especificación.

No pongas cinco agentes a construir al mismo tiempo sin una guía. Eso puede producir cinco versiones diferentes de la misma idea.

Primero: especificación. Después: diseño. Luego: tareas separadas.

Cuándo basta una nota corta

No hace falta escribir una especificación para cada cambio mínimo.

Si cambias un título, un color o corriges una falta ortográfica, una descripción breve y una revisión visual pueden ser suficientes.

Usa más detalle cuando el cambio:

• Afecta pagos o dinero.
• Maneja datos personales.
• Da o quita permisos.
• Borra o migra datos.
• Depende de otro servicio.
• Puede romper algo que ya funciona.
• Será implementado por un agente con bastante autonomía.

Piensa en esto como una receta. Para hervir agua no necesitas una receta de tres páginas. Para preparar una cena para veinte personas, sí te conviene saber qué ingredientes compras, en qué orden cocinas y cómo comprobar que no olvidaste algo.

Errores comunes

Escribir demasiado

Una especificación que nadie actualiza es decoración. Empieza pequeño: objetivo, reglas, errores, fuera de alcance y criterios de aceptación.

Decir cómo antes de decir qué

"Usa una cola", "crea tres tablas" o "usa tal librería" pueden ser decisiones correctas. Pero primero define el resultado. Después eliges la herramienta.

Dejar los errores para el final

El camino feliz es fácil: el cliente llena el formulario, el sistema guarda y todos sonríen. Los problemas aparecen cuando falta un dato, se cae una API o alguien pulsa el botón dos veces.

Escribe los errores importantes desde el principio.

Dejar que el agente rellene huecos importantes

Un agente puede tomar decisiones razonables. Eso no significa que sean tus decisiones. Si algo importa para clientes, seguridad, dinero o datos, ponlo en la especificación.

Plantilla reutilizable

Puedes usar esta plantilla de ejemplo para una función, requerimiento, modlo, etc..:

# Nombre de la función

## El problema
¿Qué queremos resolver?

## Quién lo usará
¿Quién usa esta función? ¿Hay roles distintos?

## Qué debe pasar
- ...
- ...

## Qué puede salir mal
- ...
- ...

## Qué NO haremos ahora
- ...

## Cómo comprobaremos que funciona
- [ ] ...
- [ ] ...

## Preguntas pendientes
- ...

La última sección es muy útil. No tienes que saberlo todo antes de comenzar. Pero es mejor escribir "todavía debemos decidir esto" que hacer una suposición escondida.

Resumen en una frase

Spec-driven development significa acordar el comportamiento antes de construirlo, para que las personas y los agentes de IA trabajen con menos adivinanzas y más pruebas.

Una buena especificación no frena el trabajo. Evita que avances rápido en la dirección equivocada.

Referencias

• Kiro Docs: Specs — ejemplo de un flujo de requisitos, diseño y tareas para agentes.
• GitHub Spec Kit — toolkit para definir qué construir antes de delegar trabajo a un agente de código.