Spec-First + TDD: el combo que hace que Claude Code no rompa nada
Tiempo estimado de lectura: 4 min
- Spec-First transforma requisitos en contratos ejecutables que eliminan ambigüedades.
- TDD convierte esos contratos en tests que fallan primero (Red) y obligan a implementar hasta pasar (Green).
- El flujo reduce suposiciones del agente, evita happy-paths y deuda técnica silenciosa.
- Requiere versionar specs y tests junto a la implementación para trazabilidad y control.
Spec-First + TDD: el combo que hace que Claude Code no rompa nada. Díselo a cualquier equipo que delega implementaciones críticas a un agente y observarás tres problemas: suposiciones, happy-paths y deuda técnica que aparece en silencio. Este patrón invierte el orden habitual: especificación primero, tests que fallan después, implementación solo para pasar tests. Resultado: la IA implementa contra contratos ejecutables, no contra intuiciones.
Resumen rápido (lectores con prisa)
Spec-First convierte requisitos en contratos ejecutables. TDD transforma esos contratos en tests rojos que deben pasar. El agente implementa únicamente para lograr que pnpm test devuelva exit code 0. Menos ambigüedad, más trazabilidad, menos regresiones.
Spec-First + TDD: qué es y por qué lo necesitas con Claude Code
Claude Code y otros agentes son excelentes generadores de código, pero su entrenamiento los empuja a soluciones “plausibles”, no necesariamente correctas para tu dominio. La solución no es prompts más largos; es cambiar el flujo de trabajo.
Spec-First + TDD combina:
- Spec-First: transformar requisitos en un contrato preciso y ejecutable (feature-spec.md).
- TDD: traducir ese contrato a tests que inicialmente fallan (Red).
- Implementación: conceder al agente la tarea de alcanzar el verde (Green) ejecutando y corrigiendo hasta que
pnpm testdevuelva exit code 0.
Links útiles: Claude Code docs y Vitest para ejemplos de runners.
Flujo operativo paso a paso
1) Escribir la especificación (Spec)
La especificación no es un texto largo: es un contrato. Define funciones, inputs, outputs, errores y reglas inmutables.
Ejemplo (feature-spec.md):
Feature: applyDiscount(order, coupon)
Función: applyDiscount(order, coupon)
Inputs:
- order: { id, subtotal, userId, items[] }
- coupon: { code, type: 'percentage'|'fixed', value, minOrder, expiresAt }
Reglas:
- Si coupon.expiresAt < now -> DiscountExpiredError
- Si order.subtotal < coupon.minOrder -> OrderBelowMinimumError
- total = max(0, subtotal - discount)
Si necesitas respuesta HTTP o formatos JSON exactos, escríbelos. Nada queda implícito.
2) Generar esqueletos de tests que fallen (Red)
Pide a Claude que genere solo los tests: archivos Vitest/Jest que describan las aserciones exactas. Estos tests deben fallar inicialmente porque la implementación aún no existe.
Ejemplo breve (applyDiscount.test.ts):
import { applyDiscount } from './applyDiscount'
import { DiscountExpiredError } from './errors'
it('lanza DiscountExpiredError si el cupón expiró', () => {
expect(() => applyDiscount(orderExpired, couponExpired)).toThrow(DiscountExpiredError)
})
Ejecuta pnpm test localmente o desde el agente. Verás rojo: eso es correcto. Tienes un contrato ejecutable.
3) Implementación: el agente repara hasta verde
Autoriza a Claude a escribir el código con una instrucción clara:
“Implementa applyDiscount() conforme a feature-spec.md. Ejecuta pnpm test y corrige hasta que todos los tests pasen. No modifiques los tests.”
El agente iterará: escribir, ejecutar, leer errores, corregir. Termina cuando el runner devuelve 0. Esa condición objetiva sustituye la “autovalidación” del modelo.
Beneficios reales y medibles
- Trazabilidad: cada cambio está ligado a un test derivado de una especificación humana.
- Determinismo: el criterio de finalización es el estado del test runner, no el juicio subjetivo del agente.
- Menos regresiones: CI bloqueará commits que rompan contratos; el agente ya trabaja para pasar esa barrera.
- Refactor seguro: optimizar sin romper es posible porque la suite revisa invariantes.
Métricas a monitorear: porcentaje de PRs que pasan en la primera ejecución de CI, número de reverts por errores de negocio, tiempo medio para retomar trabajo en sesiones de agente.
Cuándo aplicar este combo (y cuándo no)
Aplica Spec-First + TDD cuando:
- La lógica tiene invariantes críticas: facturación, pagos, permisos.
- La feature afecta múltiples consumidores del API.
- Vas a delegar implementación a sesiones autónomas del agente.
No lo uses para:
- Prototipos visuales donde la iteración UX prima.
- Scripts puntuales o migraciones one-off.
- Cambios triviales donde crear tests cuesta más que la implementación.
Buenas prácticas y guardrails
- Versiona feature-spec.md junto con la PR que implementa la feature.
- No permitas que el agente modifique tests sin revisión humana.
- Mantén artefactos pequeños: especificaciones por feature, no documentos gigantes.
- Incluye en CLAUDE.md la referencia a specs y al contrato de proyecto para que Claude cargue el contexto inicial: esto reduce fricción y errores de interpretación (ver docs).
Spec-First + TDD no es un ritual: es control. Si quieres que Claude Code deje de ser creativo y empiece a ser fiable, escribe contratos ejecutables primero, exige tests rojos y permite que la IA solo implemente para pasar tests. El resultado no es menos velocidad: es menos correcciones, menos deuda y más confianza en el código que llega a producción.
Dominicode Labs
Para equipos que automatizan con agentes y workflows, un laboratorio de pruebas y plantillas de specs acelera la adopción. Consulta Dominicode Labs como continuación lógica para crear artefactos y plantillas reutilizables.
FAQ
¿Qué diferencia hay entre Spec-First y documentación normal?
Spec-First es un contrato ejecutable que define funciones, inputs, outputs y errores de forma precisa. La documentación normal puede ser descriptiva; la spec exige reglas inmutables y formatos exactos que pueden traducirse a tests automatizados.
¿Por qué obligar a que los tests fallen primero?
Forzar tests rojos crea un criterio objetivo: la implementación debe satisfacer el contrato verificable. Evita que el agente implemente “por intuición” y asegura que el código cumpla casos límites y errores definidos.
¿Qué herramientas usar para ejecutar este flujo?
Usa runners como Vitest o Jest para ejecutar tests. Ejecuta pnpm test en CI y localmente para validar que el agente alcanzó exit code 0.
¿Cómo controlo que el agente no modifique tests?
Políticas de revisión de PR que bloqueen merges si los tests cambian sin aprobación humana y reglas de CI que rechacen cambios en archivos de tests son medidas efectivas. Además, incluye en el proceso de aceptación la verificación de artefactos versionados.
¿Este enfoque añade mucha sobrecarga?
Hay una inversión inicial: escribir specs y tests. Esa sobrecarga se compensa con menos rework, menos regresiones y mayor velocidad a largo plazo cuando los agentes trabajan contra contratos claros.
¿Qué métricas son más útiles para medir éxito?
Métricas recomendadas: porcentaje de PRs que pasan en la primera ejecución de CI, número de reverts por errores de negocio y tiempo medio para retomar trabajo en sesiones de agente.
