Módulo 1: Spec-First Methodology y TDD con AI

Módulo 1: Spec-First Methodology y TDD con AI

Siguiente →

Módulo 1: Spec-First Methodology y TDD con AI

Descripción de la cápsula

Hasta ahora has usado Claude Code para generar código — endpoints, funciones, módulos completos. Y funciona. Pero hay un problema que probablemente ya sentiste: ¿cómo sabes que el código generado es correcto? ¿Que maneja los edge cases? ¿Que no rompe algo que ya funcionaba?

La respuesta no es "revisar el código manualmente" (no escala) ni "confiar en que la AI lo hizo bien" (no es confiable). La respuesta es tests como especificación: defines exactamente qué debe pasar ANTES de pedirle a Claude Code que implemente. Los tests son tu contrato con la AI — si pasan, el código es correcto. Si fallan, Claude Code itera hasta que lo sea.

Este módulo introduce la filosofía que transforma tu relación con Claude Code: dejas de ser "el que pide código" para convertirte en "el que define el comportamiento esperado." Es un cambio de paradigma — y es la base de todo lo que viene en esta guía.

Contexto del Módulo

¿Dónde estamos?

Este es el Módulo 1 de la guía "Testing with Claude Code" — la guía #7 del Claude Code Agentic Development Path.

Lo que ya sabes (guías #1-6 del path):

  • ✅ Usar Claude Code para generar código
  • ✅ Prompt engineering para obtener outputs de calidad
  • ✅ Manejar contexto y archivos con Claude Code
  • ✅ Orquestar tareas complejas con el agente
  • ✅ Trabajar con PRDs, planes y TODOs
  • ✅ Debug y code review con Claude Code

Lo que falta: Un método para verificar que lo que Claude Code genera es correcto. Eso es exactamente lo que esta guía te da.

¿Hacia dónde vamos?

Esta guía tiene 3 fases:

Phase 1: Fundamentos TDD con AI (Módulos 1-3)
→ Spec-first, unit tests, integration/E2E

Phase 2: Workflows de Testing (Módulos 4-6)
→ TDD completo, coverage, mocking, validation loops

Phase 3: CI y Proyecto (Módulos 7-8)
→ GitHub Actions, proyecto integrador TDD-complete

Este primer módulo establece la filosofía que sostiene todo lo demás. Sin entender por qué TDD cambia radicalmente con AI, los módulos técnicos serían solo "cómo escribir tests" — algo que ya existe en mil tutoriales. Lo que hace esta guía diferente es el contexto: tests como especificación para un agente AI.

Objetivo Profesional

Entender que en agentic development, los tests no son "verificación posterior" — son especificación previa. Son el lenguaje más preciso para comunicarle a Claude Code qué construir.

Al final de este módulo podrás:

  • ✅ Explicar por qué TDD importa más con AI que sin AI — y convencer a tu equipo de adoptarlo
  • ✅ Aplicar spec-first methodology: definir comportamiento como tests ANTES de implementar
  • ✅ Ejecutar tu primer ciclo spec→implement→validate con Claude Code
  • ✅ Diferenciar test-first de test-after y explicar por qué test-first produce resultados más confiables con AI
  • ✅ Identificar las características de un buen test-spec: determinista, independiente, claro, con un solo motivo de fallo

Progresión del Módulo

Mapa del Módulo

CápsulaTemaQué aprenderás
02Por qué TDD importa más con AIEl problema de velocidad sin validación — cómo AI amplifica tanto código bueno como bugs
03Spec-First Methodology (Tweag)La inversión de control: tú defines "qué debe pasar" (tests), Claude Code implementa "cómo"
04Anatomía de un buen test-specQué hace que un test sea una buena especificación: determinista, independiente, claro
05Primer ciclo spec→implement con Claude CodeHands-on: escribes tests, Claude Code implementa, validas — tu primer ciclo completo
06Proyecto: Spec-first mini-appAplicar todo: defines una calculator con tests como spec, Claude Code la implementa

Flujo de aprendizaje

El módulo sigue una progresión deliberada: problema → filosofía → técnica → práctica → proyecto.

Primero entenderás el problema (cápsula 02): por qué generar código sin tests es deuda técnica acelerada cuando la AI produce código a velocidad sin precedentes. Sin este contexto, el TDD se siente como burocracia innecesaria.

Luego conocerás la filosofía (cápsula 03): spec-first methodology, basada en el trabajo de Tweag con LLMs. La idea central es una inversión de control — dejas de decirle a Claude Code "implementa esto" para decirle "aquí están los tests que definen qué debe pasar — implementa para que pasen."

Después dominarás la técnica (cápsula 04): qué hace que un test sea una buena especificación. No cualquier test sirve como spec — necesitas tests que sean deterministas, independientes, con un solo motivo de fallo, y que documenten comportamiento, no implementación.

En la cápsula 05 pondrás todo en práctica: tu primer ciclo spec→implement→validate con Claude Code. Escribirás tests simples, los darás como contexto a Claude Code, y verás cómo implementa exactamente lo que definiste. Este es el momento "aha" del módulo.

Finalmente, en el proyecto (cápsula 06) construirás una mini-app completa usando spec-first: defines tests para una calculator (suma, resta, multiplicación, división, edge cases) y Claude Code implementa. El foco no es la calculator — es experimentar el workflow completo.

Conexión con Proyecto

Proyecto de este módulo: Spec-first mini-app

Construirás una calculator app donde todo empieza con tests:

  1. Defines tests para add(a, b), subtract(a, b), multiply(a, b), divide(a, b)
  2. Agregas tests para edge cases: división por cero, inputs negativos, floats
  3. Das los tests como contexto a Claude Code
  4. Claude Code implementa la lógica
  5. Ejecutas los tests y validas

Es deliberadamente simple en implementación pero rico en workflow. El objetivo es que experimentes el ciclo spec→implement→validate, no que construyas algo complejo.

Conexión con proyecto final (Módulo 8)

El proyecto final de la guía es una aplicación completa construida 100% con TDD + Claude Code — API REST con autenticación, CRUD, y business logic. Cada feature de esa aplicación se construye exactamente como la calculator de este módulo: tests primero, Claude Code implementa, validas. La diferencia es la escala, no el proceso.

Lo que aprendes aquí es el patrón fundamental que se repite en toda la guía:

Define test → Da contexto a Claude Code → Claude implementa → Tests validan → Siguiente test

Conceptos Clave del Módulo

Test-Driven Development (TDD)

Metodología donde escribes tests antes de escribir la implementación. El ciclo clásico es:

  1. Red: Escribes un test que falla (porque la implementación no existe)
  2. Green: Escribes la implementación mínima para que el test pase
  3. Refactor: Mejoras el código sin romper tests

En TDD clásico, tú haces los tres pasos. En agentic TDD, tú haces el paso 1 (escribes el test) y Claude Code hace los pasos 2-3 (implementa y refactoriza).

Spec-First

Filosofía donde los tests son la especificación del sistema. En vez de documentar requisitos en lenguaje natural (ambiguo), los documentas como tests (precisos, ejecutables, verificables). Basada en el trabajo de Tweag con desarrollo asistido por LLMs.

Validation Loop

Ciclo automático donde Claude Code ejecuta tests → identifica fallos → corrige → re-ejecuta. Este loop es lo que hace agentic TDD fundamentalmente diferente de TDD manual: la AI se auto-corrige usando test output como feedback.

Límites: Qué NO Se Hará en Este Módulo

  • ❌ pytest avanzado — Se cubre en Módulo 2 (unit tests con Claude Code). Aquí solo usarás lo mínimo necesario para escribir un test
  • ❌ Integration y E2E tests — Se cubre en Módulo 3. Este módulo se enfoca exclusivamente en la filosofía y primer ciclo
  • ❌ Coverage y métricas — Se cubre en Módulo 5. Aquí no medirás coverage, solo experimentarás el workflow
  • ❌ Historia del TDD — No necesitas conocer a Kent Beck ni la evolución del TDD. Lo que necesitas es entender la inversión de control con AI
  • ❌ Comparación de testing frameworks — Solo usamos pytest. No hay debate unittest vs nose vs robot framework
  • ❌ CI/CD — Se cubre en Módulo 7. Aquí los tests corren localmente

¿Por qué estos límites? Este módulo es filosófico y práctico al mismo tiempo. Necesitas entender el "por qué" antes de profundizar en el "cómo." Los módulos siguientes te dan toda la técnica — pero sin esta base conceptual, la técnica se aplica mecánicamente sin entender su valor.

Evidencia de Éxito

Al terminar este módulo, sabrás que tuviste éxito si:

  • ✅ Puedes explicar en una frase por qué TDD importa más con AI: "La velocidad de generación amplifica tanto código bueno como bugs — los tests son el filtro"
  • ✅ Puedes describir la inversión de control: tú defines "qué debe pasar" (tests), Claude Code implementa "cómo"
  • ✅ Ejecutaste al menos un ciclo completo spec→implement→validate con Claude Code — escribiste un test, Claude Code generó la implementación, y el test pasó
  • ✅ Puedes evaluar un test como spec: ¿es determinista? ¿independiente? ¿tiene un solo motivo de fallo?
  • ✅ Completaste el mini-proyecto: calculator con tests como spec y Claude Code como implementador

Lo que Cambiarás Después de Este Módulo

Antes de este módulo, tu workflow con Claude Code probablemente era:

Tú: "Implementa una función que calcule descuentos"
Claude Code: [genera código]
Tú: [revisa visualmente] "Se ve bien" → push

Después de este módulo, tu workflow será:

Tú: [escribe test] test_discount_10_percent → expects 90
Tú: [escribe test] test_discount_zero → expects original price
Tú: [escribe test] test_discount_negative → expects ValueError
Tú: "Implementa para que estos tests pasen"
Claude Code: [genera código]
Tú: pytest → ✅ All tests pass → push

La diferencia: En el segundo workflow, no necesitas confiar en tu review visual. Los tests son tu red de seguridad — automática, precisa, y reproducible.

Resumen

  • ✅ Este módulo establece la filosofía spec-first: tests como especificación para un agente AI
  • ✅ TDD cambia radicalmente cuando el implementador es Claude Code — tú defines "qué", la AI implementa "cómo"
  • ✅ El módulo progresa de problema → filosofía → técnica → práctica → proyecto
  • ✅ El proyecto es una calculator app construida con spec-first: tests primero, Claude Code implementa
  • ✅ Solo se usa pytest básico — la técnica avanzada viene en módulos posteriores
  • ✅ Todo lo que aprendes aquí es el patrón fundamental que se repite en toda la guía

Próxima cápsula: Por qué TDD importa más con AI — el problema de velocidad sin validación.

Recursos Adicionales

  1. Tweag: Test-Driven Development with LLMs - La metodología spec-first en la que se basa este módulo
  2. pytest Documentation - Documentación oficial de pytest (referencia, no necesitas leerla completa ahora)
  3. Martin Fowler: Test-Driven Development - Introducción al TDD clásico por Martin Fowler
  4. Anthropic: Claude Code Documentation - Documentación oficial de Claude Code
  5. Kent Beck: TDD by Example - El libro que originó TDD (referencia histórica, no prerequisito)
  6. The Pragmatic Programmer: Test-First - Perspectiva pragmática sobre testing

Módulo 1 — Testing with Claude Code Guide Spec-first: tests como especificación, no como verificación

Siguiente →Por Qué TDD Importa Más con AI que Sin AI