TDD con IA: escribir pruebas con Claude Code usando rojo-verde-refactor (2026)

¿Qué es TDD con IA?

TDD (Desarrollo Guiado por Pruebas) es una forma de escribir código en la que primero escribes la prueba —dejas que falle— y luego escribes solo el código justo para que pase, y por último lo limpias (refactorizas) sin volver a poner la prueba en rojo. Ese es el TDD "clásico", y lleva años entre nosotros. "TDD con IA" simplemente significa que dejas que Claude Code (o un asistente de IA parecido) haga las dos tareas: escribir las pruebas y escribir la implementación que las satisface, mientras tú sigues al mando de definir los requisitos y verificar el resultado.

La diferencia central frente a "pedirle a la IA que programe y luego que añada pruebas" es el orden. En TDD, la prueba que escribes primero es una especificación ejecutable: describe la entrada, la salida y los casos límite exactos antes de que exista una sola línea de código real. Entonces Claude Code escribe código para poner esa prueba en verde, en lugar de escribir lo que le dé la gana y corregir su propia tarea.

Si todavía no te sientes cómodo trabajando en un proceso codo a codo con la IA, lee primero qué es el vibe coding y en qué se diferencia de un flujo de trabajo disciplinado para ver dónde encaja el TDD en el panorama general. El TDD es una de las disciplinas que evitan que el vibe coding se convierta en un montón de código que nadie puede controlar.

¿Por qué el TDD encaja tan bien con Claude Code?

Claude Code da lo mejor de sí cuando la "definición de terminado" es algo ejecutable y que se verifica solo, y una prueba es justo eso. Cuando dices "haz que esta función funcione correctamente", la IA tiene que adivinar qué quieres decir. Cuando dices "haz que estas 8 pruebas pasen", tiene un objetivo binario claro: rojo o verde, sin zona gris en la que pueda "suponer que ya terminó".

Tres razones hacen que esta dupla encaje:

• Una prueba es una especificación y una red de seguridad al mismo tiempo. Describe el requisito y, a la vez, atrapa la rotura en el instante en que la IA cambia otra cosa por error. En una base de código que la IA edita constantemente, esa red de seguridad es lo que te libra del "arreglo una cosa, rompo otras tres".
• Un ciclo de retroalimentación muy ajustado. Escribe la prueba -> ejecuta -> lee el error -> corrige hasta que esté en verde. Claude Code puede ejecutar las pruebas en la terminal y leer la salida real, así que itera a lo largo de varias rondas sin que tú copies y pegues los errores a mano.
• Una defensa contra que la IA se salte el requisito. Este es el punto que poca gente dice en voz alta: escribir la prueba primero te obliga (a ti y a la IA) a fijar el requisito antes de programar. Muchos bugs del tipo "técnicamente correcto, pero con la intención equivocada" desaparecen en cuanto el requisito queda congelado en una prueba.

La propia Anthropic incluye el TDD como flujo de trabajo recomendado al trabajar con Claude Code en buenas prácticas de Claude Code (Anthropic, 2025): escribe las pruebas, confirma que fallan y luego escribe código hasta que pasen. Esto no es un truco que alguien se haya inventado: es como la propia creadora de la herramienta sugiere usarla.

El ciclo rojo-verde-refactorizar con Claude Code

Todo el TDD cabe en tres pasos, repetidos para cada pequeña porción de una funcionalidad. Con Claude Code, cada paso se corresponde con un prompt y una expectativa de salida bien clara.

Paso 1 - Rojo: escribe una prueba que falla (todavía sin código)

Le pides a Claude que escriba una prueba para el comportamiento deseado, y solo la prueba. Al ejecutarla tiene que dar rojo, porque la implementación aún no existe.

Write a unit test for validate_email(email) in src/validators.py using pytest.
Cover these cases: valid email, missing @, missing domain, empty string, None.
The test MUST fail because the function does not exist yet. Do NOT write any code for validate_email.

Esperado: un archivo test_validators.py con un puñado de casos, y al ejecutar pytest reporta un ImportError o pruebas en rojo. Aquí el rojo es lo correcto: demuestra que la prueba realmente comprueba algo que todavía no existe.

Paso 2 - Verde: escribe el mínimo de código para que pase

Solo ahora dejas que la IA escriba la implementación, y recalcas lo de "mínimo" para que no le añada funcionalidades de más.

Write the MINIMAL implementation of validate_email so every test in
test_validators.py passes. Run `pytest -q` and paste the real results back to me.
Do not add features beyond what the tests cover.

Esperado: el código justo, y la salida de pytest pasa a verde. Haz que la IA pegue la salida real de la ejecución; no te fíes de un simple "pasa".

Paso 3 - Refactorizar: limpia el código y mantén el verde

Una vez en verde, tienes una red de seguridad para limpiar todo con libertad.

Refactor validate_email for readability (extract the regex into a constant, use clear names).
Do NOT change behavior. Re-run `pytest -q` after editing to prove it is still green.

Esperado: código más limpio, pruebas aún completamente en verde. Si una prueba se pone en rojo durante una refactorización, es una señal de que acabas de cambiar el comportamiento sin querer: corrígelo de inmediato.

Una sesión real test-first con Claude Code (paso a paso)

Eso es la teoría; aquí va una sesión real con una funcionalidad pequeña: una función parse_price("1.299.000d") que devuelve el entero 1299000. Es lógica pura, con entrada/salida claras: terreno ideal para TDD.

Paso 1 - pide una prueba en rojo. Abro Claude Code en la carpeta del proyecto y escribo:

Write pytest for parse_price(s) in src/pricing.py:
- "1.299.000d" -> 1299000
- "50.000 d" -> 50000
- "0d" -> 0
- a string with no digits -> raise ValueError
Write only the test. The function does not exist yet, so the test must fail.

Paso 2 - pide el mínimo de código para pasar a verde. Tras confirmar que las pruebas están en rojo como se esperaba:

Write the minimal implementation of parse_price so all 4 tests pass.
Run `pytest -q` and paste the output. Do not handle cases outside the tests.

Claude escribe una función que quita los caracteres que no son dígitos, hace el cast a int y lanza ValueError cuando está vacía. Ejecuta las pruebas por sí mismo y devuelve un resultado en verde.

Paso 3 - refactoriza. Le digo a Claude que extraiga la lógica de extracción de dígitos a un helper y añada un docstring, y que vuelva a ejecutar las pruebas para probar que el comportamiento no cambió. Siguen las 4 en verde. La sesión entera lleva unos minutos, y lo clave es que nunca tuve que aceptar el "ya está" a ciegas: cada afirmación venía con la salida real de pytest adjunta.

Cómo FORZAR a Claude Code a escribir las pruebas PRIMERO (para que no programe antes)

Este es el mayor quebradero de cabeza y la razón por la que muchos equipos abandonan el TDD a los pocos días: Claude Code, como la mayoría de los asistentes de IA, tiende a lanzarse directo a la implementación y solo añadir pruebas para aparentar. Está entrenado para "resolver el problema" y, para él, escribir código se parece más a resolver el problema que escribir una prueba. Tres mecanismos fuerzan la cuestión de forma eficaz:

1. Prompts separados por fases. No metas "escribe la función X y una prueba para ella" en una sola frase: eso es una invitación a que la IA programe antes. Sepáralo con firmeza: el paso Rojo dice solo "escribe una prueba que FALLE para X, NO escribas código todavía", y pasas al Verde solo cuando la prueba esté en rojo. Poner "no escribas código todavía" en mayúsculas o negrita mejora notablemente el cumplimiento.

2. Una regla test-first en CLAUDE.md. Este es el enfoque más duradero: escribe la regla una vez y aplícala en cada sesión. Añade este bloque al archivo CLAUDE.md de tu proyecto:

## TDD rules (mandatory)
- Always write tests BEFORE the implementation for any new logic/function.
- Order: (1) write a failing test, (2) run `pytest -q` to confirm red,
 (3) write the minimal code to pass, (4) refactor while staying green.
- Do NOT write any implementation during the Red step.
- Do NOT edit tests just to make existing code pass.
- After every change, run the REAL tests and paste the output; never claim "it passes" on faith.

Si nunca has configurado este archivo, mira la guía para escribir un CLAUDE.md sólido (forzando el test-first): es el interruptor de encendido/apagado de la disciplina en todo el proyecto.

3. Una compuerta de fase con un subagent. La jugada avanzada: usa un subagent dedicado a escribir pruebas y no le muestres el plan de implementación. Cuando el "escritor de pruebas" no sabe cómo se verá el código, las pruebas se ciñen al comportamiento deseado y no al código que piensas escribir, lo que evita pruebas moldeadas a medida para "ponerlo en verde". La forma de organizar varios agentes por fases está en el flujo brainstorm -> plan -> cook -> ship.

Errores comunes en el TDD con IA (antipatrones)

El TDD con IA falla de formas muy predecibles. Detéctalas pronto para no engañarte creyendo que estás "haciendo TDD":

De todos, la brecha de verificación es la más peligrosa porque es silenciosa. Cuando te atascas en una prueba que se queda en rojo o la IA empieza a dar vueltas, no dejes que "lo ponga en verde" aflojando la prueba: cambia a una depuración metódica (mira depurar con IA) y comprueba la calidad del cambio con una ronda de revisión de código con IA antes de hacer commit.

Automatizar el TDD: hooks y skills que imponen la compuerta de fase

La disciplina manual se descuida con facilidad. Dos formas de automatizar para que la compuerta de fase no dependa de tu memoria:

Hooks que ejecutan las pruebas automáticamente. Claude Code admite hooks que se ejecutan después de cada edición de archivo. Configuras un hook para ejecutar pytest -q (o npm test, vitest run) después de cada edición; si una prueba da rojo, el hook lo marca de inmediato, así que la IA tiene que corregirlo antes de seguir. Esto convierte "acuérdate de ejecutar las pruebas" en "no puedes olvidarte de ejecutar las pruebas".

Skills/subagents con el proceso ya incorporado. En lugar de reescribir la convención test-first para cada proyecto, puedes usar un kit prefabricado.

Acelera con un kit prefabricado: Si prefieres no construir los hooks y las convenciones desde cero, el kit AgentKit para Claude Code (20% de descuento por el enlace) (agentkit.best, la CLI ak, que no hay que confundir con el AgentKit de OpenAI) viene con más de 60 skills y más de 30 workflows para ingenieros, incluido un workflow de revisión de código. Puedes combinarlos con tu bucle rojo-verde-refactorizar para tener una compuerta de fase y una revisión automáticas, sin la configuración manual. Detalles en el análisis del Engineer Kit. El Engineer Kit cuesta actualmente 99 USD (el sitio no menciona ninguna cuota recurrente).

Ya sea que lo construyas tú mismo o que uses un kit, el principio no cambia: quien tiene que ejecutar las pruebas e informar el resultado es la máquina, no la IA autodeclarándose lista.

Cuándo deberías usar TDD con IA y cuándo NO

El TDD con IA no es una bala de plata. Sé realista sobre dónde brilla y dónde estorba:

Úsalo cuando: lógica de negocio, funciones puras (entrada -> salida clara), procesamiento de datos, APIs de backend y, sobre todo, corrección de bugs: escribir una prueba que reproduce el bug (rojo) y luego corregirlo hasta el verde es el flujo de corrección de bugs más ordenado que existe. Es también donde más rinde el TDD cuando usas Claude Code para construir una API de backend, porque el contrato de un endpoint es fácil de congelar en una prueba.

Menos indicado cuando: en la fase de exploración/prototipo, en la que los requisitos aún son difusos (las pruebas que escribas se van a borrar constantemente), en el estilizado de UI y la sensación visual (las pruebas salen caras y no captan "se ve bien/mal"), o en un script de usar y tirar. Cuando el requisito todavía es vago, forzar el test-first solo te frena: prototipa con libertad y, una vez que hayas fijado el comportamiento, vuelve y envuelve con pruebas las partes que merezca la pena conservar.

Preguntas frecuentes (FAQ)

¿El TDD con IA reemplaza al TDD manual?

No reemplaza el principio, solo quién teclea. Sigues teniendo que decidir qué comprueba la prueba y juzgar si es significativa; la IA se encarga de escribir y ejecutar. La disciplina del rojo-verde-refactorizar sigue siendo tuya.

¿Las pruebas que escribe Claude son correctas y completas?

Normalmente correctas en los casos básicos, pero a menudo se le escapan los casos límite (vacío, null, negativos, unicode, errores de red). Lee las pruebas que escribió la IA y pídele que añada casos límite antes de confiar en ellas. La prueba es la especificación, así que te toca a ti aprobar la especificación.

¿Qué framework: pytest, Jest o Vitest?

Usa el que tu proyecto ya use; Claude Code domina pytest (Python), Jest y Vitest (JS/TS). Lo que importa es nombrar el framework de forma explícita en tu prompt o en CLAUDE.md para que la IA no elija uno al azar.

¿Necesito saber escribir pruebas antes de hacer TDD con IA?

Deberías conocer lo básico. No hace falta que seas un crack escribiendo pruebas, pero necesitas lo suficiente para leer y juzgar las pruebas que la IA escribe; de lo contrario, darás el visto bueno a pruebas sin sentido. Toma el TDD como una manera de subir de nivel tus propias habilidades de testing mientras trabajas.

¿Son las pruebas escritas por IA lo bastante fiables para frenar regresiones?

Son fiables bajo dos condiciones: que hayas revisado las pruebas y que las pruebas se hayan ejecutado de verdad (no la IA autodeclarando un aprobado). Añade una capa lint -> unit -> e2e para cubrir la tendencia de la IA a informar "listo" demasiado pronto.

¿Puedo aplicar TDD con IA a un proyecto heredado?

Sí, pero en un orden distinto: para código heredado, primero escribes "pruebas de caracterización" que fijan el comportamiento actual y luego refactorizas con seguridad. Para funcionalidades nuevas añadidas a un proyecto antiguo, sigue siendo test-first como de costumbre.

Conclusión y próximos pasos

El TDD con IA se reduce a un bucle: escribe una prueba en rojo -> deja que Claude Code la ponga en verde -> refactoriza manteniendo el verde, y haz siempre que la máquina ejecute las pruebas de verdad en lugar de fiarte de la palabra de la IA. La clave no es una herramienta más potente, es poder forzar a la IA a escribir primero las pruebas con prompts separados por fases y una regla en CLAUDE.md. Siguiente paso: conecta el TDD con un proceso completo mediante el flujo brainstorm -> plan -> cook -> ship y refuerza los cimientos de tu proceso con vibe coding hecho de la forma correcta.