tdd

Visión general de la skill tdd

La skill tdd es una guía específica para trabajar con desarrollo guiado por pruebas siguiendo un bucle estricto de red-green-refactor, no un prompt genérico de “escribe algunos tests”. Encaja especialmente bien para desarrolladores que quieren ayuda de IA para crear funcionalidades o corregir bugs manteniendo los tests vinculados al comportamiento a través de interfaces públicas, y no a detalles internos de implementación.

Para qué sirve tdd

Usa tdd para Test Driven Development cuando quieras que el modelo:

• planifique una funcionalidad en pequeños cortes verticales
• escriba un único test fallido cada vez
• implemente solo el código mínimo necesario para pasar
• refactorice con seguridad después de estar en verde
• evite tests frágiles que se rompen con refactors inocuos

Quién saca más partido a tdd

La skill tdd encaja mejor si ya cuentas con:

• una base de código con tests ejecutables
• una API pública, endpoint, comando o flujo de usuario claro sobre el que trabajar
• permiso para modificar tanto los tests como el código de producción
• preferencia por tests de estilo integración en lugar de depender mucho de mocks

Resulta especialmente útil en servicios backend, librerías, lógica de dominio y flujos de aplicación donde el comportamiento puede ejercitarse a través de una interfaz real.

Qué hace diferente a esta skill tdd

Su principal diferencia es su postura clara y exigente sobre la calidad de los tests:

• probar comportamiento, no internals
• priorizar tests de estilo integración
• usar mocks solo en los límites del sistema
• evitar el “corte horizontal”, es decir, escribir primero todos los tests y después todo el código
• usar TDD para dar forma a mejores interfaces, no solo para aumentar cobertura

Eso hace que el uso de tdd sea más disciplinado que un prompt corriente que simplemente le pide a una IA “escribe tests e implementación”.

Qué puede dificultar su adopción

Esta skill encaja peor si tu entorno no puede ejecutar tests, si tu código no tiene puntos de entrada públicos estables o si tu equipo prefiere sobre todo tests unitarios cargados de snapshots o de mocks. También da por hecho que estás dispuesto a iterar en pasos pequeños, en vez de generar una funcionalidad completa de una sola vez.

Cómo usar la skill tdd

Instala tdd en tu entorno de skills

Si estás usando el sistema de Skills del repositorio, un patrón de instalación habitual es:

npx skills add mattpocock/skills --skill tdd

Después, invoca tdd al pedirle al modelo que implemente o repare un comportamiento siguiendo un flujo test-first.

Lee primero estos archivos antes de usar tdd intensivamente

La forma más rápida de entender esta skill es leer en este orden:

1. SKILL.md
2. tests.md
3. mocking.md
4. interface-design.md
5. refactoring.md
6. deep-modules.md

Ese orden importa. SKILL.md explica la filosofía operativa, mientras que los archivos de apoyo aterrizan qué significan en la práctica unos “buenos tests” y un “buen diseño”.

Ten claro el flujo central que espera tdd

La skill está construida alrededor de un ciclo muy ajustado:

1. elegir un comportamiento pequeño
2. escribir un test fallido a través de una interfaz pública
3. implementar el código mínimo para pasarlo
4. refactorizar manteniendo los tests en verde
5. repetir con el siguiente corte más pequeño

Si pides una funcionalidad entera de una sola vez, pierdes gran parte del valor del uso de tdd.

Empieza por un comportamiento, no por una idea de implementación

Input sólido:

• “Add checkout support for expired cards. Public entrypoint is checkout(cart, paymentMethod). Existing test file is checkout.test.ts. Keep using integration-style tests.”

Input débil:

• “Create classes for payment orchestration and add unit tests for each method.”

El primer prompt le da a la skill un objetivo de comportamiento. El segundo la empuja hacia especulación sobre el diseño interno y hacia tests frágiles.

Dale a la skill la interfaz pública y el comando de tests

Para obtener buenos resultados tanto en la instalación de tdd como en su ejecución, incluye:

• la función, ruta, comando CLI o acción de UI que se va a probar
• dónde viven los tests
• el runner de tests y el comando
• restricciones relevantes, como DB, HTTP o servicios externos
• qué se puede y qué no se puede mockear

Una plantilla de prompt práctica:

Use the tdd skill.

Goal: Add [behavior].
Public interface: [function/route/command].
Test location: [path].
Run tests with: [command].
Boundaries to mock: [external API, clock, filesystem].
Do not mock: [internal modules/classes].
Work in red-green-refactor steps and explain each step briefly.

Usa cortes verticales, no cortes horizontales

Una de las ideas más útiles de este repositorio es evitar escribir en bloque todos los tests por adelantado. Aquí, un buen uso de tdd implica:

• elegir un escenario real
• conseguir que pase
• dejar que ese resultado informe el siguiente escenario

Eso reduce abstracciones imaginadas y suele producir una API mejor planteada.

Prioriza tests de estilo integración en tdd

El repositorio favorece claramente los tests que recorren caminos reales del código a través de APIs públicas. En la práctica, eso significa:

• llamar a funciones exportadas en lugar de helpers privados
• probar route handlers a través de su interfaz soportada
• verificar resultados observables, no el orden de llamadas internas
• nombrar los tests por capacidad, por ejemplo “user can checkout with valid cart”

Si un refactor cambia los internals pero el comportamiento sigue siendo el mismo, un buen test normalmente debería seguir en verde.

Usa mocks solo en los límites del sistema

La skill tdd no está en contra de los mocks; está en contra de mockear tu propia implementación. Haz mock de:

• pasarelas de pago
• proveedores de email
• tiempo/aleatoriedad
• a veces bases de datos o filesystem, según tu setup de tests

No hagas mock de:

• tus propios módulos
• colaboradores internos
• métodos privados
• wrappers finos que controlas tú

Solo esta pauta suele cambiar la calidad de salida más que la mayoría de ajustes de prompt.

Da forma al código para que sea testeable antes de escribir demasiado

Los archivos de apoyo insisten en una idea importante: mejores interfaces hacen que TDD resulte más fácil. Pídele al modelo que priorice código que:

• reciba dependencias en vez de crearlas internamente
• devuelva resultados en vez de mutar estado oculto
• mantenga pequeña la superficie pública

Si tu diseño actual complica los tests, dile al modelo que primero proponga una interfaz pública más pequeña y más fácil de probar.

Un ejemplo de prompt sólido para tdd

Use the tdd skill to add password reset token expiry.

Context:
- Node + TypeScript
- Public API: `requestPasswordReset(email)` and `resetPassword(token, newPassword)`
- Tests: `src/auth/password-reset.test.ts`
- Run with: `pnpm test password-reset`
- Mock only email sending and time
- Do not mock repository code or internal services

Please:
1. choose the smallest failing behavior first
2. write integration-style tests through public APIs
3. implement minimum code to pass
4. refactor after green
5. avoid asserting internal call counts unless at an external boundary

Funciona bien porque le da a la skill un objetivo claro, una política de límites y una ruta real de ejecución.

Fíjate en las principales señales de calidad de salida

Un buen resultado de la guía tdd con esta skill suele incluir:

• tests nombrados en torno a comportamiento visible para el usuario
• un escenario pequeño cada vez
• implementación mínima en cada paso
• notas de refactor después del verde
• poca o ninguna dependencia de estructuras privadas

Un mal resultado suele incluir:

• muchos mocks para código interno
• aserciones sobre orden de llamadas
• suites gigantes de tests como primer paso
• abstracciones especulativas antes de que pase ningún comportamiento

FAQ de la skill tdd

¿tdd sirve solo para funcionalidades nuevas?

No. La skill tdd también encaja muy bien en corrección de bugs. En muchas bases de código maduras, el mejor primer paso es un test de regresión en rojo que reproduzca el fallo a través de la interfaz pública, seguido de un arreglo mínimo y luego limpieza.

¿Esta skill tdd es adecuada para principiantes?

Sí, siempre que ya sepas ejecutar los tests de tu proyecto. La guía es opinada, pero simple: prueba comportamiento, mantén los cortes pequeños y evita aserciones ligadas a detalles de implementación. Quienes estén empezando desde cero quizá sigan necesitando ayuda para entender la arquitectura del proyecto y su tooling de tests.

¿En qué se diferencia tdd de pedirle a una IA que escriba tests?

Los prompts corrientes suelen generar tests orientados a cobertura o demasiado cargados de mocks. La skill tdd empuja al modelo hacia:

• especificaciones de comportamiento
• refactors más seguros
• interfaces más limpias
• pasos iterativos más pequeños

Eso cambia tanto los tests como el diseño de producción.

¿Cuándo no debería usar tdd?

Omite o limita tdd para Test Driven Development cuando:

• el comportamiento todavía no puede ejercitarse de forma útil
• el entorno es demasiado difícil de ejecutar durante la iteración
• estás haciendo spikes exploratorios y desechables
• la tarea es sobre todo mecánica, como renombrados o actualización de dependencias

Aun así, puedes volver a TDD cuando el punto de entrada público esté más claro.

¿tdd exige usar solo tests de integración?

No de forma estricta, pero su sesgo está claramente del lado de los tests de estilo integración a través de interfaces reales. El objetivo no es que los tests sean lo más grandes posible; es probar comportamiento en un punto estable. Los tests pequeños y enfocados también encajan si se mantienen en la interfaz pública y evitan acoplarse a internals.

¿Qué lenguajes o frameworks encajan con esta skill?

Las ideas son, en general, independientes del lenguaje. Los ejemplos se inclinan hacia TypeScript y JavaScript, pero los principios de diseño aplican igual en ecosistemas como Python, Java, Go, Ruby y similares, siempre que puedas definir interfaces públicas claras y límites de test bien delimitados.

Cómo mejorar la skill tdd

Dale a tdd un primer corte más pequeño

La manera más fácil de mejorar los resultados de tdd es reducir el primer paso. En vez de “build user invitations”, empieza con “user with valid email can request an invitation”. Los cortes pequeños reducen la arquitectura alucinada y producen tests más limpios.

Define reglas de límites explícitas

Muchas salidas pobres vienen de una política de mocking poco clara. Dile al modelo exactamente:

• qué sistemas externos se pueden mockear
• qué módulos internos deben permanecer reales
• si hay una test DB disponible
• si el tiempo debe inyectarse o congelarse

Eso ayuda a que la skill se mantenga alineada con la filosofía del repositorio.

Pide nombres de tests basados en la interfaz pública

Si quieres mejores tests, pide nombres que describan resultados:

• bueno: user can checkout with valid cart
• más débil: checkout calls payment service

Solo esa instrucción suele evitar que los tests deriven hacia detalles de implementación.

Haz visible el ciclo red-green-refactor

Si la primera respuesta vuelve como un bloque completo de implementación, pídele al modelo que la reestructure:

• mostrar el primer test fallido
• mostrar el código mínimo para pasarlo
• explicar el refactor por separado
• detenerse tras un corte si hace falta

La skill tdd funciona mejor cuando el bucle es visible, no cuando se da por supuesto.

Mejora el diseño cuando los tests se sienten forzados

Si al modelo le cuesta escribir tests limpios, el problema suele estar en el diseño de la interfaz, no en la sintaxis del test. Pídele que revise el diseño hacia:

• dependency injection
• inputs y outputs explícitos
• superficies públicas más pequeñas
• menos efectos secundarios

Aquí es donde interface-design.md y deep-modules.md aportan especial valor.

Usa el refactor como una pasada de calidad aparte

Después de algunos cortes en verde, pide explícitamente una revisión de refactor usando las pistas del repositorio:

• duplicación
• métodos largos
• módulos superficiales
• feature envy
• primitive obsession

Así evitas que el uso de tdd se quede en “los tests pasan” y mejoras la mantenibilidad sin cambiar comportamiento.

Corrige pronto los fallos habituales

Si baja la calidad de salida, estas suelen ser las causas:

• se genera demasiado código antes del primer test fallido
• se mockean en exceso colaboradores internos
• los tests verifican detalles de implementación
• la funcionalidad pedida es demasiado grande para un solo ciclo
• la interfaz pública no está clara o cambia en cada paso

Cuando ocurra, reinicia con un comportamiento, un punto de entrada, un test fallido.

Usa los archivos del repositorio como ayuda para decidir

Para obtener mejores resultados, vincula tu problema con la documentación de apoyo:

• tests.md cuando el estilo de tests sea flojo
• mocking.md cuando no estén claros los límites
• interface-design.md cuando los puntos de entrada resulten incómodos
• refactoring.md después de llegar a verde
• deep-modules.md cuando la forma de la API se esté volviendo demasiado amplia

Ese recorrido de lectura aporta mucho más valor que limitarse a hojear SKILL.md.

Itera afinando restricciones, no repitiendo el mismo prompt

Si la primera salida es mediocre, no digas simplemente “try again”. Mejora la siguiente ronda con restricciones concretas:

• apuntar a un solo comportamiento
• preservar la API pública actual
• no mockear módulos internos
• preferir una test DB frente a mocks del repositorio
• detenerse después del primer ciclo red-green-refactor

Ese tipo de iteración mejora de forma consistente la calidad de la guía tdd mucho más que pedir “más detalle”.