📐 Adopta el flujo orientado por especificaciones
Spec-Driven Development significa que la especificación va antes del código y permanece como fuente de la verdad durante toda la ejecución. Una especificación no es un texto genérico: existe para reducir la ambigüedad y transformar la intención en criterios verificables.
Cómo leer: fíjate en los dos extremos. La especificación (a la izquierda, resaltada) y la verificación (a la derecha, en cian) hablan de lo mismo; la segunda solo existe para comprobar la primera. Si no escribiste la spec, la verificación no tiene con qué comparar, y «listo» se convierte en una opinión.
🆕 ¿Nuevo por aquí?
Especificación (spec) es un documento breve que indica qué debe existir y cómo saber que está listo: no es documentación de arquitectura ni un ticket de Jira. Criterio de aceptación es una frase que se puede responder con sí o no mirando el sistema («la respuesta sigue siendo idéntica para los mismos parámetros»). Si la frase depende del gusto («que quede más ordenado»), todavía no es un criterio.
Antes del código
La spec precede al plan
Ambigüedad
Alguien siempre decide
Verificable
Sí/no, no «mejor»
Fuente de la verdad
Vale más que el chat
🧱 Reúne los elementos de una buena especificación
Este es el esqueleto. Cada campo ausente se convierte en una decisión que el agente toma por su cuenta, normalmente la más genérica posible. Úsalo como lista de verificación: si un campo está vacío, pregúntate quién decidirá eso y cuándo.
Problema
¿Qué problema debe resolverse? (no es la solución)
Objetivo
¿Qué resultado debe alcanzarse?
Alcance · Fuera del alcance
Qué forma parte de la tarea — y qué no debe ser modificado.
Entradas · Salidas
Qué datos o eventos entran; qué resultados produce el sistema.
Contratos
Interfaces, formatos y comportamientos que deben conservarse.
Condiciones de error
Qué debe ocurrir cuando algo falle.
Restricciones
Tecnologías, estándares, límites y reglas que debes respetar.
Criterios de aceptación · Pruebas
Cómo verificar que se completó; qué pruebas crear o ejecutar.
Definición de listo
Qué condiciones dan por terminado el trabajo, sin negociación posterior.
💡 Consejo práctico
Empieza guardando este esqueleto como specs/_template.md en el repositorio. Una spec que vive junto al código se lee; una spec que vive en una wiki externa envejece en dos semanas.
Campo vacío
= decisión delegada
Fuera del alcance
Freno de la refactorización
Contrato
Protege a quienes lo consumen
Listo
Cierra la discusión
🎯 Delimita el alcance y los criterios de aceptación
Todo el mundo escribe el alcance positivo. Lo que salva la revisión es el alcance negativo: la lista de lo que no se puede tocar. Sin ella, un agente competente «aprovecha el viaje» y devuelve un diff de cuarenta archivos que nadie revisa bien.
✓ Criterio verificable
- ✓"La respuesta permanece idéntica para los mismos parámetros."
- ✓"Una solicitud duplicada con la misma clave de idempotencia no crea un segundo cargo."
- ✓"Ningún archivo fuera de src/pagamentos/ se modifica."
- ✓"La suite se ejecuta en menos de 90 segundos."
✗ Criterio que no decide nada
- ✗"Dejar el código más limpio."
- ✗"Mejorar el rendimiento."
- ✗"Seguir las buenas prácticas."
- ✗"Mantener la compatibilidad" (sin decir con qué).
Prueba del alcance negativo
Antes de enviar la tarea, responde en una línea cada una:
¿Qué archivos/carpetas NO puede tocar?
¿Qué dependencias NO puede agregar?
¿Qué comportamiento existente NO puede cambiar?
¿Qué tipo de refactorización puede esperar?
Sí/no
El criterio es binario
Alcance negativo
Vale tanto como lo positivo
Diff pequeño
Se puede revisar de verdad
Sin «mejor»
Una comparación vaga no sirve
🔌 Describe contratos, entradas, salidas y errores
Casi toda regresión grave nace de un contrato implícito: alguien sabía que ese campo nunca podía ser nulo, pero eso no estaba escrito en ninguna parte. El agente no adivina lo que todo el equipo olvidó registrar.
🔒 Qué fija un contrato
- •Forma: nombres de campos, tipos, obligatoriedad, formato de fecha, unidad del valor monetario.
- •Comportamiento: ordenamiento, paginación, idempotencia, efectos secundarios.
- •Fallo: qué código de error, qué cuerpo de respuesta, si hay reintentos y con qué espera.
- •Compatibilidad: quién lo usa hoy y qué no puede fallarle a esa persona.
🧭 Condiciones de error que casi siempre faltan
Lo implícito se rompe
Escribe lo obvio
El error es un requisito
El camino adverso tiene spec
Quién lo consume
Haz una lista antes de cambiar
Prueba de contrato
Convierte el acuerdo en una condición obligatoria
🆚 Compara una spec deficiente con una spec completa
El par canónico del taller. Lee ambos y cuenta cuántas decisiones estaban ocultas en la frase breve.
✗ Mala especificación
Crie um sistema de pagamentos.
Medios de pago, duplicados, estados, webhooks, datos sensibles, pruebas, rollback: todo eso lo decidirá quien lo ejecute, de la manera que le parezca razonable en ese momento.
✓ Especificación más completa
Criar um serviço de pagamentos que: - aceite PIX e cartão; - impeça duplicidade por chave de idempotência; - registre todos os estados da transação; - processe webhooks; - realize retentativas; - gere logs estruturados; - preserve compatibilidade com a API atual; - não armazene dados sensíveis de cartão; - inclua testes unitários e de integração; - tenha rollback para migrações; - bloqueie o merge se os testes falharem.
Cada línea cierra una puerta de decisión. Cuanto mejor sea la especificación, menor será la posibilidad de que el agente tome decisiones incompatibles con el sistema.
🧪 Ejercicio copiable — genera la spec con el propio agente
Objetivo: partir de una frase breve sin escribirlo todo desde cero. Pégalo en tu agente, dentro del repositorio real.
Você vai escrever uma ESPECIFICAÇÃO, não código. Não altere nenhum arquivo. Tarefa que eu quero fazer: <descreva em uma frase> Repositório: leia <caminhos relevantes> antes de responder. Produza um documento com estas seções, e nada além delas: problema · objetivo · escopo · fora do escopo · entradas · saídas · contratos · condições de erro · restrições · critérios de aceitação · testes · definição de pronto Regras: - cada critério de aceitação deve ser verificável com sim ou não; - liste explicitamente o que NÃO deve ser alterado; - no final, liste em "PERGUNTAS" tudo que você teve que supor. - não invente regras de negócio: se não achou no código, vai para PERGUNTAS.
Cómo verificar: la sección "PREGUNTAS" es lo más valioso del ejercicio: enumera exactamente las decisiones que el agente habría tomado por su cuenta si le hubieras enviado el prompt breve. Respóndelas, actualiza la spec y solo entonces autoriza la implementación.
Una línea
Oculta diez decisiones
Idempotencia
Requisito, no detalle
PREGUNTAS
Suposiciones a la vista
Spec versionada
Vive en el repositorio
🔗 Convierte cada criterio en una prueba
Aquí la spec deja de ser un documento y se convierte en un mecanismo. Una regla escrita en texto es útil; la misma regla transformada en una prueba automática es mucho más confiable — y es lo que permite delegar la ejecución al agente sin perder el control.
Lee el criterio en voz alta
"Una solicitud duplicada con la misma clave no genera un segundo cargo."
Escribe la prueba que falla hoy
Envía dos veces la misma solicitud y afirma que existe exactamente un cobro. Debe fallar antes de la implementación; de lo contrario, no está probando nada.
Entrégale la prueba al agente como definición de terminado
La tarea deja de ser «implementa idempotencia» y pasa a ser «haz que esta prueba pase sin modificar la propia prueba». Es una condición de parada objetiva: el tema de la ruta 2.
⚠️ Atención
Si el agente puede editar las pruebas libremente, tiene permiso para redefinir qué significa «listo». Trata los archivos de prueba como un área protegida: cambiar una prueba es un cambio de especificación y requiere aprobación humana explícita.
Spec ejecutable
La prueba es la regla viva
Falla primero
Si no, no demuestra nada
Prueba protegida
Cambiar una prueba = cambiar la spec
Autonomía
Viene del verificador
📌 Resumen del módulo
Próxima ruta:
Ruta 2 - Harness Engineering: el sistema que rodea al modelo (herramientas, contexto, permisos, límites).