Módulo 8: Proyecto Integrador — Test Suite Completa con TDD

Entrega y Retrospectiva

Entrega y Retrospectiva

Descripción de la cápsula

Esta es la cápsula final del módulo y de la guía. Aquí validas que TaskFlow API cumple todos los criterios de entrega, preparas el repositorio para portfolio, haces una retrospectiva de lo aprendido, y cierras el ciclo: dominas TDD con Claude Code.

Checklist Final del Proyecto

Antes de considerar el proyecto completo, recorre esta lista:

  • La aplicación arranca y todos los endpoints responden correctamente
  • La test suite tiene tests en 3 niveles: unit, integration, E2E
  • Coverage ≥90% en líneas
  • CI pipeline corre en GitHub Actions y pasa
  • README explica setup, cómo correr tests, y tiene badge de CI
  • No hay tests marcados como skip sin justificación
  • El código tiene type hints en funciones públicas
  • Los ciclos TDD están documentados (en commits, en un doc, o en comentarios)

Rúbrica de Evaluación (100 puntos)

Usa esta rúbrica para autoevaluar o para que un revisor evalúe tu entrega.

Funcionalidad (25 puntos)

CriterioPuntosDescripción
App funciona10La API arranca, responde en los endpoints esperados
Auth completo5Register, login, validación de token funcionan
Teams completo5Crear equipo, agregar miembros, listar equipos
Tasks completo5CRUD de tareas, asignación, transiciones de estado

Test Suite (30 puntos)

CriterioPuntosDescripción
Unit tests10Tests de servicios y lógica aislada, bien nombrados
Integration tests10Tests de endpoints con TestClient, auth incluido
E2E tests5Al menos un flujo completo (register → login → team → task)
Coverage ≥90%5pytest-cov reporta ≥90% line coverage

Proceso TDD (20 puntos)

CriterioPuntosDescripción
Ciclos documentados10Evidencia de red-green-refactor por feature
Spec refinement5Al menos un caso donde añadiste tests al descubrir gaps
Tests antes de implementación5Los tests guiaron la implementación, no al revés

CI/CD (15 puntos)

CriterioPuntosDescripción
Pipeline funcional10GitHub Actions corre tests en push/PR
Coverage en CI3Coverage report generado en el workflow
Badge en README2Badge de status de CI visible

Calidad del Código (10 puntos)

CriterioPuntosDescripción
Código limpio4Sin duplicación innecesaria, nombres claros
Type hints3Funciones principales tipadas
Organización3Estructura de carpetas y módulos coherente

Total: 100 puntos. Objetivo mínimo recomendado: 80 puntos para considerar el proyecto completo.

Desglose detallado por categoría

Funcionalidad (25 pts):

  • App funciona (10): La API arranca con uvicorn app.main:app, todos los endpoints responden sin errores 500
  • Auth completo (5): POST /auth/register, POST /auth/login, endpoints protegidos validan token
  • Teams completo (5): POST /teams, POST /teams/{id}/members, GET /teams
  • Tasks completo (5): CRUD completo en /teams/{id}/tasks y /tasks/{id}, asignación y transiciones

Test Suite (30 pts):

  • Unit tests (10): Servicios (AuthService, TeamService, TaskService) y rules tienen tests aislados
  • Integration tests (10): TestClient valida cada endpoint con y sin auth
  • E2E tests (5): Al menos un test que recorre register → login → team → task → complete
  • Coverage ≥90% (5): pytest --cov=app --cov-fail-under=90 pasa

Proceso TDD (20 pts):

  • Ciclos documentados (10): Commits o TDD-LOG.md muestran red → green → refactor
  • Spec refinement (5): Algún test añadido durante implementación al descubrir gap
  • Tests primero (5): Los tests existían antes o en paralelo con la implementación, no después

CI/CD (15 pts):

  • Pipeline funcional (10): .github/workflows/tests.yml corre en push/PR
  • Coverage en CI (3): Job incluye --cov y --cov-report
  • Badge (2): README tiene badge de status

Calidad (10 pts):

  • Código limpio (4): Sin duplicación, funciones pequeñas, nombres descriptivos
  • Type hints (3): Parámetros y retornos tipados en funciones públicas
  • Organización (3): app/, tests/, estructura coherente

Preparar el Repositorio para Portfolio

Qué hace tu repo destacable

Un proyecto de portfolio no es solo código que funciona. Es código que demuestra habilidades diferenciadoras. TaskFlow API construida con TDD + Claude Code muestra:

  • Capacidad de planificar (spec-first)
  • Dominio de testing en múltiples niveles
  • Integración de CI/CD
  • Uso profesional de AI como herramienta, no como reemplazo del criterio

Cuando un reclutador o revisor técnico abre tu repo, en menos de 30 segundos debe ver: badge verde de CI, estructura clara, README que explica cómo correr y testear. Eso genera confianza antes de leer una línea de código.

README profesional

Tu README debe incluir:

  1. Título y descripción breve

    • Qué es TaskFlow API, qué problema resuelve

  2. Badge de CI

    ![Tests](https://github.com/your-username/taskflow-api/actions/workflows/tests.yml/badge.svg)

  3. Setup e instalación

    ## Setup
```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

  4. Cómo ejecutar la app

    ## Ejecutar
uvicorn app.main:app --reload

  5. Cómo ejecutar tests

    ## Tests
pytest tests/ -v
pytest tests/ --cov=app --cov-report=html  # con coverage

  6. Stack tecnológico

    • Python, FastAPI, pytest, etc.

  7. Contexto TDD (opcional pero valioso)

    • "Este proyecto fue construido con TDD usando Claude Code. Cada feature empezó como un test."
    • Esto diferencia tu repo y muestra dominio del workflow.

Ejemplo de sección de README

## Testing

Este proyecto fue construido 100% con TDD (Test-Driven Development) usando Claude Code.

- **Unit tests:** Servicios y lógica de negocio aislada
- **Integration tests:** Endpoints con FastAPI TestClient
- **E2E tests:** Flujos completos de usuario

Ejecutar tests:
```bash
pytest tests/ -v
pytest tests/ --cov=app --cov-report=html

Coverage objetivo: ≥90%


### Estructura visible

Asegúrate de que la estructura del proyecto sea clara: `app/`, `tests/`, `.github/workflows/`. Un revisor debe entender la arquitectura en segundos.

### Commits y documentación

Si documentaste ciclos TDD en un archivo (ej. `TDD-LOG.md` o en el README), inclúyelo. Los recruiters y revisores valoran ver el proceso, no solo el resultado.

---

## Retrospectiva 4Ls

La retrospectiva 4Ls (Liked, Learned, Lacked, Longed for) ayuda a consolidar el aprendizaje. Responde en primera persona, para ti mismo o para compartir.

### Liked (Lo que te gustó)

- ¿Qué aspecto del proceso TDD con Claude Code disfrutaste más?
- ¿Qué te sorprendió positivamente? (por ejemplo: velocidad de ciclos, calidad de código generado)
- ¿Qué harías de nuevo sin dudarlo?
- ¿Qué parte del flujo spec-first → implement → validate te resultó más natural?

### Learned (Lo que aprendiste)

- ¿Qué concepto o técnica internalizaste mejor?
- ¿Qué cambiaría tu forma de trabajar en futuros proyectos?
- ¿Qué mito sobre TDD o AI se rompió? (ej: "TDD es lento" vs "con AI es más rápido")
- ¿Cómo evolucionó tu criterio sobre cuándo confiar en código generado por AI?
- ¿Qué aprendiste sobre la importancia de tests como especificación vs tests como verificación posterior?

### Lacked (Lo que faltó)

- ¿Qué te hubiera gustado tener (tiempo, recursos, ejemplos)?
- ¿Qué parte del proyecto quedó a medias o poco clara?
- ¿Qué dependencia o herramienta te complicó?
- ¿En qué momento sentiste que necesitabas más guía?
- ¿Qué edge case descubriste tarde y cómo lo manejarías antes la próxima vez?

### Longed for (Lo que esperas a futuro)

- ¿Qué te gustaría explorar después?
- ¿Cómo aplicarías esto en un proyecto real de trabajo?
- ¿Qué guía o tema complementaría lo aprendido?
- ¿Te interesa aplicar TDD a refactoring de código legacy?
- ¿Cómo llevarías estos estándares a un equipo que usa AI para desarrollo?

---

## Qué Viene Después de Esta Guía

Completaste la guía **Testing with Claude Code**. Las siguientes guías de la serie te llevan a territorios adyacentes:

1. **Refactoring & Legacy Code (#8):** Aprenderás a aplicar testing a código existente que no fue escrito con TDD. Código legacy, deuda técnica, y cómo Claude Code te ayuda a agregar tests sin romper producción. La mayoría del código en el mundo no tiene tests; saber cómo añadirlos de forma segura es una habilidad muy demandada.

2. **Claude Code en Equipo (#9):** Estándares de testing para equipos que usan agentic development. Cómo alinear convenciones, reviews de tests generados por AI, documentación compartida, y qué partes del workflow TDD escalan a equipos de múltiples desarrolladores.

3. **Aplicar a tu proyecto:** El workflow que dominaste aquí es transferible. En tu próximo proyecto real, empieza con spec-first, descompón en tests, usa Claude Code para implementar, y mantén CI desde el día uno. No necesitas una app nueva: puedes aplicar TDD incremental a features nuevas en un codebase existente.

4. **Profundizar en testing:** Si quieres ir más allá: mutation testing (¿tus tests realmente detectan bugs?), contract testing para microservicios, performance testing, o testing de aplicaciones con frontend.

---

## Validación Final Antes de Entregar

Recorre este checklist la noche antes de considerar el proyecto cerrado:

- [ ] `uvicorn app.main:app` arranca sin errores
- [ ] `pytest tests/ -v` pasa (0 failed)
- [ ] `pytest tests/ --cov=app --cov-fail-under=90` pasa
- [ ] `git push` dispara el workflow de GitHub Actions
- [ ] El badge en README muestra "passing" (verde)
- [ ] No hay TODOs críticos sin resolver en el código
- [ ] README está completo y sin errores de formato
- [ ] requirements.txt incluye todas las dependencias (incluyendo pytest, pytest-cov)

Si todo marca verde, estás listo.

---

## Celebración: Dominaste TDD con AI

Has construido una aplicación completa usando un workflow que la mayoría de developers aún no practica: TDD asistido por Claude Code. No es solo "usar AI para generar código". Es usar AI como implementador dentro de un sistema de validación que tú controlas. Los tests son el contrato; Claude Code es el ejecutor. Eso es desarrollo profesional con AI.

El repositorio de TaskFlow API es tu evidencia. Muestra que puedes:
- Planificar con spec-first
- Descomponer features en tests
- Ejecutar ciclos red-green-refactor con un agente AI
- Lograr coverage profesional
- Configurar CI que protege cada cambio

Eso es portfolio-worthy. Úsalo.

---

## Resumen Final

- Checklist de entrega y rúbrica de 100 puntos para validar el proyecto
- README con badge de CI, setup, y tests
- Retrospectiva 4Ls para consolidar el aprendizaje
- Próximos pasos: Refactoring & Legacy, Claude Code en Equipo, aplicar a proyectos reales
- Celebración: dominas TDD con AI y tienes un proyecto para demostrarlo

**Fin del Módulo 8 y de la guía Testing with Claude Code.** ¡Felicidades!

---

*Módulo 8, Cápsula 06 — Testing with Claude Code Guide*
← AnteriorMocks, Fixtures y CI Pipeline