Cómo SDD y TDD optimizan el desarrollo con Claude Code
DominicodeSDD + TDD: el combo que convierte a Claude Code en un dev senior
Tiempo estimado de lectura: 4 min
- SDD reduce las decisiones del agente; TDD valida de forma determinista.
- Especificación primero, tests después: contratos claros y criterios ejecutables.
- Aplica cuando hay lógica crítica, APIs públicas y repositorios tipados.
Introducción
SDD + TDD: el combo que convierte a Claude Code en un dev senior. Poca gente lo practica en equipos que prueban agentes, y sin embargo es la diferencia entre recibir código usable o un cajón de sorpresas que rompe en producción.
Claude Code (motor basado en Claude 3.7 Sonnet) puede leer tu repo, ejecutar comandos y escribir código. Genial. También puede inventar abstracciones, tocar capas que no debe y aplicar convenciones que no son las tuyas. La solución no es pedir menos; es pedir mejor: especificación primero, tests después.
Resumen rápido (lectores con prisa)
SDD = especificaciones codificadas (tipos, interfaces, reglas). TDD = tests que hacen las especificaciones ejecutables. Juntos reducen la improvisación del agente y transforman código generado en artefactos verificables y mantenibles.
Por qué SDD + TDD: el combo que convierte a Claude Code en un dev senior
Un modelo de lenguaje es, por naturaleza, probabilístico. Sin restricciones explícitas, el agente construirá “la versión más probable” de tu feature, no la versión correcta para tu sistema. SDD (Specification-Driven Development) fuerza el contrato: tipos, firmas, reglas y límites. TDD (Test-Driven Development) convierte esos contratos en criterios ejecutables: rojo, verde, refactor.
Juntos funcionan así:
- SDD reduce el espacio de decisiones del agente.
- TDD da un criterio determinista para validar el trabajo.
- Claude Code deja de improvisar y se limita a cumplir pruebas que tú definiste.
Referencias útiles: Anthropic (Claude) docs, TDD (Martin Fowler).
Qué debe incluir una SDD práctica para agentes
No es un brief largo: es el mínimo necesario para quitar decisiones al modelo.
- Tipos e interfaces visibles en código
Python: define modelos Pydantic para entradas/salidas. (Pydantic)
- Reglas explícitas de efectos secundarios
“Función pura — sin DB, sin llamadas HTTP” o “Permitido: escribir en tabla payments; Prohibido: llamar a servicios externos”.
- Manejo de errores y contratos de retorno
`Result<T, E>` vs excepciones. Si decides una convención, documenta y hazla código.
- Casos límite documentados
Inputs inválidos, límites numéricos, retries, timeouts, políticas de deduplicación.
Escribe esto en archivos que el agente pueda leer (por ejemplo *.types.ts, *.schema.py, .md con reglas) y no lo dejes solo en un prompt.
El ciclo TDD que hace verificable al agente
Con la spec lista, el flujo TDD para Claude Code es práctico y repetible:
- Fase Roja — Generar tests.
Prompt: claude “Lee payment.types.ts y las reglas en comments. Genera tests en Vitest que cubran todos los casos límite. Ejecuta los tests y reporta fallos.”Resultado esperado: tests fallando (porque no hay implementación).
- Fase Verde — Implementación mínima.
Prompt: claude “Implementa payment.ts respetando los tipos. Ejecuta los tests y corrige hasta que pasen en verde. No cambies firmas ni añadas dependencias externas.”
- Refactor — Mejorar con seguridad.
Prompt: claude “Refactoriza para reducir la complejidad ciclomática, manteniendo todos los tests en verde.”
Herramientas recomendadas para el ciclo: Vitest o Jest, integradas en la terminal que usa Claude Code.
Ejemplo práctico (resumen)
En vez de: “Crea validación de email”, escribe:
types.ts:–interface CreateUser { email: string; name?: string }–type Result = { ok: true; value: T } | { ok: false; error: string }- Comentario en
createUser.ts:// Función pura. Rechaza dominios genéricos (gmail.com, hotmail.com). Retorna Result. No lanza excepciones. - Prompts:
- Genera tests → ejecuta → confirma fallo.
- Implementa hasta pasar tests → refactor.
La diferencia es mínima en tiempo de setup y enorme en predictibilidad.
Cuándo aplicar este enfoque (y cuándo no)
Aplica SDD + TDD cuando:
- Construyes lógica de negocio crítica o APIs públicas.
- Trabajas en repositorios compartidos y tipados.
- Necesitas trazabilidad y responsabilidad en cambios.
No lo apliques para:
- Scripts one-off o hacks exploratorios.
- Prototipos que requieren máxima velocidad de experimentación.
Lo que cambian estas prácticas en tu equipo
La escritura de código se convierte en commodity; el verdadero valor pasa a:
- Diseñar contratos claros.
- Anticipar edge cases.
- Traducir decisiones de producto a reglas verificables.
Claude Code seguirá escribiendo código — pero ahora ese código será verificable y, lo que es más importante, mantenible. Si defines la partitura (SDD) y pones el metrónomo (TDD), el agente tocará afinado.
Fuentes y lectura recomendada
FAQ
- ¿Qué es SDD y en qué se diferencia de un brief tradicional?
- ¿Por qué es necesario TDD cuando uso un agente capaz de ejecutar tests?
- ¿Qué archivos debo incluir en la SDD para que el agente los use?
- ¿Puedo usar este flujo con agentes distintos a Claude Code?
- ¿Qué herramientas recomiendan para ejecutar el ciclo TDD?
- ¿Cómo manejo cambios de contrato sin romper downstream?
- ¿Cuándo NO debo aplicar SDD + TDD?
¿Qué es SDD y en qué se diferencia de un brief tradicional?
SDD (Specification-Driven Development) codifica las decisiones clave —tipos, interfaces, reglas de efectos secundarios— en artefactos que el agente puede leer. Un brief tradicional suele ser texto libre; SDD es código y contrato.
¿Por qué es necesario TDD cuando uso un agente capaz de ejecutar tests?
TDD transforma la especificación en criterios ejecutables (tests). Sin tests, el agente puede producir la solución más probable; con tests, debe producir la solución que pasa los criterios que definiste (rojo → verde → refactor).
¿Qué archivos debo incluir en la SDD para que el agente los use?
Archivos legibles por el agente: *.types.ts, *.schema.py, y .md con reglas y comentarios. Define tipos, modelos y reglas de efectos secundarios en esos archivos.
¿Puedo usar este flujo con agentes distintos a Claude Code?
Sí. El patrón SDD + TDD es aplicable a agentes que puedan leer repositorios y ejecutar comandos. Se basa en contratos verificables y tests automatizados, no en peculiaridades de un motor concreto.
¿Qué herramientas recomiendan para ejecutar el ciclo TDD?
Herramientas recomendadas: Vitest o Jest. Integradas en la terminal del agente para ejecutar fases Roja/Verde/Refactor.
¿Cómo manejo cambios de contrato sin romper downstream?
Versiona tipos y contratos, introduce migraciones y añade tests de compatibilidad. Documenta cambios en la SDD y agrega pruebas que verifiquen compatibilidad hacia atrás cuando sea necesario.
¿Cuándo NO debo aplicar SDD + TDD?
No lo apliques para scripts one-off, hacks exploratorios o prototipos donde la prioridad es iterar rápido sin garantías fuertes.