tdd-guide

Descripción general de la skill tdd-guide

Para qué sirve tdd-guide

tdd-guide es una skill de Test Driven Development para generar pruebas unitarias, detectar brechas de cobertura, crear fixtures y mocks, y guiar el trabajo red-green-refactor en stacks habituales. Resulta especialmente útil cuando quieres que un asistente de IA haga más que “escribir algunas pruebas”: la skill orienta la conversación hacia el código fuente, los requisitos, el framework objetivo, los informes de cobertura y los criterios de validación.

Usuarios y proyectos para los que encaja mejor

La skill tdd-guide encaja con equipos de ingeniería, desarrolladores independientes y perfiles centrados en QA que trabajan con TypeScript, JavaScript, Python o Java. Es especialmente relevante para flujos de trabajo con Jest, Pytest, JUnit, Vitest y estilos similares a Mocha. Úsala cuando estés agregando pruebas a código existente, empezando una nueva funcionalidad con pruebas primero, mejorando la cobertura hacia un umbral concreto o estandarizando la salida de pruebas en un equipo.

Qué la diferencia de un prompt genérico para pruebas

Un prompt genérico puede producir pruebas plausibles, pero suele pasar por alto convenciones del framework, casos límite, prioridades de cobertura o el propio ciclo de TDD. tdd-guide incluye estructura de flujo de trabajo, entradas de ejemplo, patrones de salida esperados, herramientas de análisis de cobertura, generación de fixtures, adaptación a frameworks y referencias para integración con CI. Por eso resulta más adecuada para trabajo de ingeniería repetible que para experimentar con prompts puntuales.

Cuándo tdd-guide puede no ser suficiente

tdd-guide for Test Driven Development no sustituye la comprensión del comportamiento del dominio. Si no puedes proporcionar resultados esperados, dependencias, reglas de error o detalles del framework, las pruebas generadas pueden quedarse en la superficie. Tampoco garantiza automáticamente que las pruebas compilen en tu repositorio; aun así debes ejecutar tu comando local de pruebas y ajustar imports, archivos de setup, mocks y configuración específica del entorno.

Cómo usar la skill tdd-guide

Instalación de tdd-guide y revisión del repositorio

Instala la skill en un entorno compatible con Claude Skills con:

npx skills add alirezarezvani/claude-skills --skill tdd-guide

Después revisa la carpeta upstream de la skill en engineering-team/skills/tdd-guide. Empieza por SKILL.md para ver las reglas de activación y los flujos de trabajo; luego lee HOW_TO_USE.md para ejemplos de invocación. Si necesitas configuración específica de un framework, revisa references/framework-guide.md; si tu objetivo es aplicar validaciones en build, lee references/ci-integration.md; si quieres mejorar tus hábitos de TDD, consulta references/tdd-best-practices.md.

Entradas que mejoran el uso de tdd-guide

La skill funciona mejor cuando aportas cuatro elementos: el código o requisito de la funcionalidad, el lenguaje, el framework de pruebas y el comportamiento esperado. Las buenas entradas incluyen caminos felices, casos de error, valores límite, dependencias externas y objetivos de cobertura.

Un prompt débil sería: “Write tests for my auth service.”

Un prompt más sólido sería: “Use tdd-guide to generate Jest tests for src/auth/password-validator.ts. Cover valid password, too short password, missing uppercase, missing number, missing special character, and null or empty input. Target 90% branch coverage. Use existing project style: describe, beforeEach, and expect(...).toBe(...).”

Flujo de trabajo práctico con tdd-guide

Para código existente, usa esta secuencia:

1. Pega o referencia el archivo fuente.
2. Especifica language, framework y la convención de nombres para los archivos de prueba.
3. Pide pruebas agrupadas por prioridad: comportamiento P0, casos límite P1, regresiones P2.
4. Ejecuta las pruebas generadas en local.
5. Vuelve a pegar en el asistente los errores de compilación, assertions fallidas o salida de cobertura.
6. Pide a la skill que refine imports, mocks, fixtures y ramas faltantes.

Para una funcionalidad nueva, usa red-green-refactor: primero pide pruebas fallidas a partir de los criterios de aceptación, implementa el código mínimo que las haga pasar y luego solicita mejoras seguras para refactorizar manteniendo las pruebas en verde.

Archivos y scripts útiles para revisar primero

El repositorio contiene archivos de soporte prácticos que conviene leer antes de usarlo en serio:

• assets/sample_input_python.json y assets/sample_input_typescript.json muestran el nivel de entrada estructurada que mejora la calidad de la salida.
• assets/expected_output.json muestra el tipo de resumen de pruebas, cobertura y calidad que la skill está diseñada para producir.
• scripts/test_generator.py da soporte a patrones de generación de pruebas.
• scripts/coverage_analyzer.py es relevante cuando tienes datos de cobertura en LCOV, JSON o XML.
• scripts/fixture_generator.py, framework_adapter.py y tdd_workflow.py indican cómo la skill entiende los mocks, las convenciones de framework y las fases de TDD.

FAQ de la skill tdd-guide

¿tdd-guide es buena para principiantes?

Sí, si la persona principiante tiene una funcionalidad o función concreta que probar. La skill tdd-guide puede enseñar el ritmo de red, green y refactor mientras produce ejemplos utilizables. Aun así, quienes empiezan deberían ejecutar todas las pruebas generadas y leer los fallos. El valor de aprendizaje viene de comparar el comportamiento esperado, las assertions generadas y la implementación real.

¿Qué frameworks soporta mejor tdd-guide?

El mejor encaje está en Jest, Pytest, JUnit y Vitest, con Mocha también mencionado en la descripción de la skill. La referencia de frameworks incluida cubre patrones de TypeScript/JavaScript, Python y Java. Si usas un framework menos común, proporciona un archivo de prueba de ejemplo de tu repositorio para que la skill pueda reproducir imports, nomenclatura, hooks de setup y estilo de assertions.

¿Puede analizar informes de cobertura?

Sí. tdd-guide está diseñada para trabajar con informes de cobertura como LCOV, JSON y XML. Para obtener mejores resultados, pega los archivos y ramas sin cubrir que sean relevantes, no solo un porcentaje. Un prompt como “coverage is 65%” aporta menos que compartir coverage/lcov.info, rangos de líneas sin cubrir y los archivos fuente asociados a esas brechas.

¿Cuándo no debería usar tdd-guide?

No la uses como única puerta de calidad para comportamientos críticos de seguridad, financieros, médicos o sujetos a cumplimiento normativo. Puede ayudar a redactar pruebas y exponer brechas, pero no puede confirmar la corrección de negocio sin reglas autorizadas. También encaja mal cuando no se puede compartir la base de código, no hay comportamiento público definido o el proyecto depende mucho de entornos de integración ocultos.

Cómo mejorar la skill tdd-guide

Mejora los resultados de tdd-guide con mejores prompts

La forma más rápida de mejorar la salida de tdd-guide es proporcionar comportamiento, no solo código. Incluye ejemplos de entradas válidas, entradas inválidas, excepciones esperadas, valores límite y cualquier convención de pruebas existente. Si se necesitan mocks, nombra la dependencia y define qué debe simularse frente a qué debe ejecutarse de verdad.

Añadidos útiles al prompt incluyen:

• “Do not mock the pure calculation function.”
• “Mock the payment gateway and assert it is called once.”
• “Use parameterized Pytest cases for boundary values.”
• “Prefer behavior-focused test names over implementation names.”

Corrige fallos comunes después de la primera salida

Los problemas habituales son imports incorrectos, exceso de mocks, assertions frágiles sobre la implementación, manejo async faltante y pruebas que mejoran la cobertura de líneas sin aumentar la confianza. Después del primer resultado, pega el fallo de la prueba o el error de compilación y pide una corrección puntual. Por ejemplo: “These Jest tests fail because the service constructor requires a repository dependency. Revise using a typed mock and keep the same behavioral coverage.”

Usa datos de cobertura para priorizar el trabajo con tdd-guide

Si tu objetivo es mejorar la cobertura, pide a la skill que ordene las brechas por riesgo en lugar de generar pruebas para cada línea sin cubrir. Prioriza condicionales no probados, ramas de error, métodos públicos y reglas de negocio antes que getters triviales o ramas defensivas. El flujo de cobertura del repositorio admite priorización P0/P1/P2, que es más útil que perseguir solo un porcentaje bruto.

Itera hacia una práctica de TDD mantenible

El mejor uso de tdd-guide es iterativo. Primero pide pruebas fallidas a partir de los requisitos, luego solicita la forma mínima de implementación y después pide sugerencias de refactorización que mantengan las pruebas estables. Mantén al asistente centrado en el comportamiento observable: entradas, salidas, efectos secundarios, excepciones y límites de integración. Así obtendrás pruebas que sigan siendo útiles cuando cambie la implementación.