Spec

⏱ 5 min de lectura  ·  📅 Actualizado en 2026

Una spec es una especificación operativa que define qué debe construirse, bajo qué restricciones y cómo se verificará el resultado. En Spec-Driven Development (SDD), la spec funciona como puente entre la intención humana y la ejecución por un agente de IA: convierte una necesidad, historia o hipótesis en instrucciones claras, revisables y testeables.

En desarrollo asistido por IA, una spec no es un documento decorativo ni una formalidad burocrática. Es el artefacto que permite que humanos y agentes compartan una misma interpretación del trabajo.

La spec responde a preguntas que una historia de usuario normalmente no pretende cerrar por completo:

• ¿Qué comportamiento exacto debe producirse?
• ¿Qué queda fuera del alcance?
• ¿Qué restricciones técnicas deben respetarse?
• ¿Qué casos borde deben contemplarse?
• ¿Cómo sabremos que el resultado está bien?
• ¿Qué decisiones no debe tomar la IA por su cuenta?

Por convención interna de Scrum Manager, el término se usa en femenino: una spec, la spec, las specs.

Para qué sirve

La spec sirve para reducir ambigüedad antes de delegar trabajo a una persona, a un equipo o a un agente de IA.

En contextos con IA, su importancia aumenta porque el agente tiende a completar los huecos con decisiones probables. A veces acierta. Otras veces introduce supuestos que el equipo descubre tarde: dependencias innecesarias, criterios de seguridad incompletos, errores de integración, duplicación de código o comportamientos no deseados.

Una buena spec ayuda a:

• alinear a producto, tecnología y negocio;
• convertir intención en comportamiento verificable;
• evitar que la IA invente decisiones críticas;
• facilitar la revisión humana;
• crear tests y criterios de aceptación;
• mantener trazabilidad entre necesidad, implementación y validación;
• reducir retrabajo;
• evitar que un prototipo se confunda con software listo para producción.

Diferencia entre historia de usuario y spec

Una historia de usuario y una spec no compiten. Cumplen funciones distintas.

Artefacto	Función principal	Pregunta que responde
Historia de usuario	Comunicar una necesidad desde la perspectiva del usuario.	¿Para quién construimos esto y por qué importa?
Spec	Definir comportamiento, límites, restricciones y verificación.	¿Qué debe producirse exactamente y cómo sabremos que está bien?

La historia de usuario mantiene el foco en valor, usuario y conversación. La spec traduce esa intención a un formato más preciso, especialmente útil cuando parte del trabajo será ejecutado por IA.

Ejemplo:

Historia de usuario	Spec
“Como usuario, quiero recibir una notificación cuando se modifique un documento asignado para enterarme de cambios relevantes.”	Define canales permitidos, preferencias de usuario, eventos que disparan notificación, frecuencia máxima, plantillas, errores, permisos, pruebas y criterios de aceptación.

La historia abre la conversación. La spec prepara la ejecución.

Qué debe contener una buena spec

Una spec no necesita ser larga, pero sí suficientemente clara. Su contenido depende del tipo de trabajo, pero suele incluir:

Elemento	Función
Objetivo	Explica qué se quiere conseguir y por qué.
Contexto	Sitúa la tarea dentro del producto, usuario, sistema o problema.
Alcance	Define qué entra y qué no entra.
Comportamiento esperado	Describe cómo debe actuar el sistema.
Criterios de aceptación	Indican cómo se comprobará que el resultado cumple lo esperado.
Casos borde	Cubren situaciones límite, errores, datos inválidos o excepciones.
Restricciones técnicas	Arquitectura, APIs, modelos de datos, seguridad, rendimiento o compatibilidad.
Dependencias	Sistemas, equipos, servicios o decisiones necesarias.
Boundaries	Reglas Always / Ask First / Never.
Evidencia de verificación	Tests, logs, capturas, comandos, resultados o criterios de revisión.

La prueba de calidad de una spec es sencilla: una persona o agente que no estuvo en la conversación original debería poder entender qué se espera, qué no debe tocar y cómo demostrar que ha terminado.

Ejemplo básico

Spec: cambio de email de usuario

Objetivo:
Permitir que un usuario autenticado cambie su email principal sin comprometer la seguridad de la cuenta.

Alcance:
Incluye cambio de email, verificación del nuevo correo y registro de auditoría.
No incluye cambio de contraseña ni gestión de doble factor.

Comportamiento esperado:
- El usuario introduce un nuevo email válido.
- El sistema comprueba que no esté asociado a otra cuenta.
- El sistema envía un enlace de verificación al nuevo email.
- El email principal solo cambia cuando se completa la verificación.
- Se registra el evento en audit_log.

Casos borde:
- Email inválido.
- Email ya usado.
- Token de verificación caducado.
- Usuario no autenticado.
- Servicio de email no disponible.

Always:
- Mantener registro de auditoría.
- No revelar si un email pertenece a otra cuenta.

Ask First:
- Antes de modificar el flujo de autenticación existente.

Never:
- No cambiar el email sin verificación.
- No registrar tokens completos en logs.

Criterios de aceptación:
- Given un usuario autenticado
  When solicita cambiar su email por uno válido y no usado
  Then recibe un correo de verificación
  And el email principal no cambia hasta verificarlo.

Specs en formato Given/When/Then

Una forma práctica de escribir partes de una spec es usar escenarios tipo Given/When/Then.

Given [contexto o estado inicial]
And [condiciones adicionales]
When [acción o evento]
Then [resultado esperado verificable]
And [comportamientos adicionales]

Este formato ayuda porque cada “Then” puede convertirse en una prueba verificable. También fuerza concreción: “el sistema funciona correctamente” no es un resultado comprobable; “el servidor responde HTTP 200 y devuelve un token con expiración de 24 horas” sí lo es.

El formato Given/When/Then no es obligatorio para toda spec, pero es muy útil para comportamiento funcional, criterios de aceptación y casos borde.

Qué no es una spec

Una spec no es:

• una historia de usuario más larga;
• un prompt improvisado;
• una documentación escrita después de construir;
• un contrato cerrado contra cualquier cambio;
• una lista infinita de requisitos;
• una explicación genérica de la idea;
• una colección de deseos sin criterios verificables.

La spec precede a la implementación. Si se escribe después, puede ser documentación útil, pero no cumple la función propia de Spec-Driven Development.

Spec y prompt

Una spec no es lo mismo que un prompt.

Concepto	Función
Spec	Define qué debe construirse, con qué límites y cómo se verificará.
Prompt	Instrucción operativa que se entrega al modelo o agente para ejecutar una tarea.

El prompt puede usar la spec como base. Por ejemplo: “implementa la tarea 2 de esta spec respetando los boundaries y actualiza los tests”. Pero si la spec no existe, el prompt suele cargar con demasiadas responsabilidades: contexto, intención, arquitectura, límites, criterios y verificación.

En trabajos simples puede bastar con un buen prompt. En trabajos de producción, la spec reduce el riesgo.

Spec y Spec-Driven Development

En Spec-Driven Development (SDD), la spec es el artefacto central. El equipo no salta directamente del deseo al código generado por IA. Primero define la especificación, la revisa y solo después la usa para guiar la implementación.

Esto cambia la relación con el agente de IA. En vibe coding, el agente funciona como interlocutor conversacional: se le pide, se prueba, se corrige y se vuelve a pedir. En SDD, el agente trabaja contra una spec: tiene un contrato de comportamiento, límites y verificación.

La spec convierte al agente en ejecutor controlado, no en decisor implícito.

Niveles de uso de una spec

No todas las specs tienen el mismo peso en el sistema de trabajo.

Nivel	Uso de la spec	Ejemplo
Spec-first	Se escribe antes de implementar y puede descartarse al terminar.	Una tarea concreta de sprint.
Spec-anchored	Se conserva como documentación viva de la funcionalidad.	Un módulo que seguirá evolucionando.
Spec-as-source	La spec se convierte en artefacto principal; el código se genera o regenera desde ella.	Contextos avanzados con herramientas maduras y alta disciplina.

La mayoría de equipos deberían empezar por spec-first o spec-anchored. Saltar a spec-as-source demasiado pronto puede crear rigidez y falsas expectativas.

Specs vivas

Una spec viva evoluciona con el producto. No queda congelada después de la primera implementación.

Puede cambiar cuando:

• se descubre un caso borde nuevo;
• cambia una regla de negocio;
• se detecta una ambigüedad;
• se modifica una API;
• aparece una restricción técnica;
• se aprende algo en producción;
• una retrospectiva identifica un fallo de definición;
• un test revela un comportamiento no especificado.

Mantener specs vivas exige disciplina. Si la spec y el producto divergen, la spec pierde valor como fuente de verdad.

Specs en proyectos brownfield y greenfield

En un proyecto greenfield, la spec ayuda a evitar que la IA tome decisiones fundacionales sin revisión: arquitectura, dependencias, seguridad, modelo de datos o patrones de testing.

En un proyecto brownfield, la spec es aún más crítica. El agente debe respetar lo existente: contratos públicos, deuda técnica, patrones del repositorio, migraciones, tests, integraciones y comportamientos que quizá no estén bien documentados.

En brownfield, una buena spec debería incluir más contexto y más boundaries. No basta con decir qué se quiere añadir. Hay que decir qué no debe romperse.

Specs y Definition of Ready para IA

En equipos con IA, una tarea no debería asignarse a un agente solo porque parece automatizable. Debe estar preparada.

Una Definition of Ready para IA puede exigir que:

• la spec esté completa y revisada;
• el agente tenga acceso al contexto necesario;
• los criterios de aceptación sean verificables;
• las restricciones técnicas estén claras;
• existan boundaries Always / Ask First / Never;
• se haya estimado el tiempo de revisión humana;
• haya una persona responsable de validar el output.

Si falta la spec o está demasiado ambigua, el agente producirá rápido, pero el equipo pagará después en revisión y retrabajo.

Specs y Definition of Done

La spec también ayuda a comprobar si algo está terminado.

La Definition of Done define criterios generales de calidad. La spec define criterios específicos de la funcionalidad o tarea. Ambas se complementan.

Un cambio generado por IA no debería considerarse terminado solo porque el agente diga que ha cumplido. Debe verificarse contra:

• la spec;
• los criterios de aceptación;
• la Definition of Done;
• tests;
• revisión humana;
• controles de seguridad;
• integración con el sistema real.

La spec como herramienta de conversación

Aunque la spec sea más precisa que una historia de usuario, no debería eliminar la conversación. Al contrario: una buena spec hace visibles las dudas.

Al escribirla, suelen aparecer preguntas como:

• ¿Qué ocurre si el usuario no tiene permisos?
• ¿Qué datos son obligatorios?
• ¿Qué comportamiento esperamos si falla un servicio externo?
• ¿Qué no debe modificar el agente?
• ¿Qué decisión debe tomar el product owner?
• ¿Qué parte requiere validación técnica?
• ¿Qué casos todavía no entendemos?

Estas preguntas son parte del valor de la spec. Si una spec no provoca ninguna conversación, quizá es porque la tarea era simple o porque los supuestos siguen ocultos.

IA y spec

La IA puede ayudar a escribir specs, pero no debe ser la única responsable de definirlas.

Puede apoyar en:

• detectar ambigüedades;
• proponer casos borde;
• convertir historias de usuario en escenarios Given/When/Then;
• identificar dependencias;
• sugerir criterios de aceptación;
• revisar consistencia;
• comparar una spec con la Definition of Done;
• generar borradores de tests.

Pero las decisiones importantes siguen siendo humanas: alcance, valor, prioridades, límites, riesgos aceptables y responsabilidad sobre el resultado.

Una IA puede ayudar a redactar una spec. No puede decidir por sí sola qué riesgo debe asumir el producto.

Calidad de una spec

Una spec de calidad suele ser:

• clara: evita términos vagos;
• suficiente: contiene el contexto necesario;
• acotada: no intenta resolver todo;
• verificable: permite comprobar si el resultado cumple;
• operativa: sirve para ejecutar, revisar y probar;
• viva: puede actualizarse cuando cambia el aprendizaje;
• legible por humanos: no está escrita solo para la herramienta;
• procesable por IA: reduce ambigüedad y decisiones implícitas.

Una spec mala puede ser larga y aun así inútil. Una spec buena puede ser breve si define lo esencial.

Señales de una spec débil

Una spec probablemente necesita trabajo si:

• usa expresiones como “fácil”, “intuitivo”, “rápido” o “adecuado” sin concretar;
• solo describe el happy path;
• no incluye errores ni casos borde;
• no indica qué queda fuera;
• no define criterios de aceptación verificables;
• no menciona restricciones técnicas relevantes;
• permite varias interpretaciones incompatibles;
• no dice cuándo el agente debe pedir aprobación;
• no se puede traducir en tests;
• nadie sabe quién debe validarla.

Buenas prácticas

Para escribir y usar specs:

• Empieza por la intención. No pierdas el vínculo con el problema de usuario.
• Define el alcance negativo. Decir qué no entra evita mucho retrabajo.
• Incluye casos borde. El happy path no basta.
• Usa Given/When/Then cuando ayude a verificar comportamiento.
• Añade boundaries Always / Ask First / Never.
• Separa hechos, decisiones y supuestos.
• Evita specs enormes. Divide si la tarea es demasiado grande.
• Actualiza la spec cuando cambie el aprendizaje.
• Haz que alguien la revise antes de delegarla a IA.
• Conecta la spec con tests y Definition of Done.

Error frecuente

Confundir detalle con calidad. Una spec no mejora por acumular páginas, capturas o instrucciones. Mejora cuando reduce ambigüedad, deja claros los límites y permite verificar el resultado. Una spec enorme pero imprecisa puede ser peor que una breve y bien estructurada.

Recursos

🏦 SDD - Spec Driven Development en equipos ágilesSkill Arena · Scrum Manager

📊 Guía didáctica SDDRecursos · Scrum Manager

Referencias

• Böckeler, Birgitta. (2025). “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl”, MartinFowler.com.
• GitHub. (2025). “Spec-driven development with AI: Get started with a new open source toolkit”, GitHub Blog.
• GitHub. (2025). “Spec Kit”, GitHub.
• Osmani, Addy. (2026). “How to write a good spec for AI agents”, addyosmani.com.
• Scrum Manager. (2026). SDD – Spec Driven Development en equipos ágiles. Scrum Manager.
• Scrum Manager. (2026). Scrum en equipos con IA. Scrum Manager.

Véase también

Spec-Driven Development (SDD) Historia de usuario Criterios de aceptación Happy path Always / Ask First / Never Agente de IA Vibe engineering Brownfield Greenfield

¿Quieres avanzar en agilidad? Puedes buscar convocatorias de cursos y exámenes o ir a tu ritmo haciéndote miembro del Club Agile. Esta membresía incluye recursos exclusivos, aulas e-learning y acceso a Skill Arena: un espacio para practicar y medir tus habilidades ágiles a tu ritmo.

Buscar convocatorias

Club Agile