Módulo 8: Proyecto Integrador — Migración de Proyecto Legacy Real
Execution: Refactoring, Modernización y Testing
Execution: Refactoring, Modernización y Testing
Descripción de la cápsula
Esta es la cápsula de ejecución. Con el plan listo (cápsula 03) y la safety net en su lugar, ejecutas las Phases 2 y 3 del migration plan: refactoring de estructura y modernización de código. Cada cambio está respaldado por tests. Cada phase tiene checkpoint.
Esta es la cápsula donde la disciplina importa más que la velocidad. La tentación de "hacer todo más rápido" combinando cambios o saltando tests es alta — pero es exactamente lo que distingue un proyecto que termina en 3 horas con éxito de uno que termina en 8 horas con incidents. Aplicas todo lo aprendido en M04 (refactoring multi-file), M05 (migration cuando aplique), y M07 (modernización incremental) — pero ahora bajo la presión de un proyecto integrador real.
Al terminar la cápsula, vas a tener un codebase estructuralmente refactorizado y modernizado, con tests verdes en cada commit, y un git history limpio que documenta cada paso. La cápsula 05 toma este resultado y produce la documentación profesional.
Por Qué Disciplina > Velocidad en Esta Cápsula
Sin disciplina:
→ "Voy a combinar Phase 2 y Phase 3 para ahorrar tiempo"
→ Cambias estructura + modernizas + actualizas dependencies
→ Tests fallan: ¿qué causó qué? Imposible saber
→ Debugging se vuelve combinatorio
→ Tiempo total: 6-8 horas
Con disciplina:
→ Phase 2 commits separados → tests verdes → continuar
→ Phase 3 con un tipo de cambio por commit
→ Si algo falla, sabes exactamente qué
→ Rollback al commit anterior, intentar de otra forma
→ Tiempo total: 2.5-3 horas
La paradoja: ir más despacio (disciplinado) llega antes porque eliminas el debugging combinatorio. Esta es la lección central del Módulo 7 (cápsula 04: incremental vs big bang) aplicada al proyecto integrador.
Phase 2: Refactoring de Estructura
Ejecutando con Claude Code
Sigue tu migration plan. Ejemplo de secuencia típica:
Paso 1: Extract Service Layer
> "Extrae la lógica de negocio de los route handlers
a un service layer. Crea src/services/ con un service
por dominio. Los routes solo deben llamar al service
y retornar la respuesta. Ejecuta tests después."
Paso 2: Move Modules
> "Reorganiza la estructura de directorios según el plan:
- Utils a src/utils/
- Models a src/models/
- Validators a src/validators/
Actualiza todos los imports. Ejecuta tests."
Paso 3: Rename para Consistencia
> "Renombra funciones y archivos que no siguen las
convenciones del proyecto. Aplica snake_case
consistente. Ejecuta tests."
Checkpoint Phase 2:
> "Ejecuta TODOS los tests. Verifica que la estructura
está mejorada pero el comportamiento es idéntico."
Si tests pasan → continuar a Phase 3. Si tests fallan → debug y fix antes de continuar.
Phase 3: Modernización
Ejecutando incrementalmente
Paso 1: Dead Code
> "Elimina dead code: imports no usados, funciones
nunca llamadas, variables no referenciadas.
Ejecuta tests."
Paso 2: Syntax
> "Moderniza syntax: f-strings, isinstance(),
iteración directa (no range(len)).
Ejecuta tests."
Paso 3: Patterns
> "Moderniza patterns: context managers para open(),
specific exceptions para bare except.
Ejecuta tests."
Paso 4: Type Hints
> "Agrega type hints a todas las funciones públicas.
Ejecuta tests."
Paso 5: Dependencies (si aplica)
> "Actualiza dependencias deprecated.
Ejecuta tests."
Checkpoint Phase 3:
> "Ejecuta TODOS los tests. Produce un diff summary
mostrando qué cambió en terms de líneas, archivos,
y estructura."
El Ritmo de Ejecución
Para CADA paso:
1. Anunciar qué vas a hacer
2. Ejecutar el cambio con Claude Code
3. Ejecutar tests
4. Si green → commit + siguiente paso
5. Si red → debug + fix → commit + siguiente paso
6. NUNCA avanzar con tests failing
Tracking Progress
Mantén un checklist en tiempo real:
## Execution Checklist
### Phase 2: Refactoring
- [x] Extract service layer (tests: ✅)
- [x] Move modules (tests: ✅)
- [x] Rename consistency (tests: ✅)
- [x] Phase 2 checkpoint (all tests: ✅)
### Phase 3: Modernization
- [x] Dead code removal (tests: ✅)
- [x] Syntax modernization (tests: ✅)
- [ ] Pattern modernization (tests: )
- [ ] Type hints (tests: )
- [ ] Phase 3 checkpoint (all tests: )Qué Hacer Cuando Algo Falla
El test falló después del refactoring
> "El test test_create_order falla después de extraer
OrderService. El error es: AttributeError 'dict' object
has no attribute 'total'. ¿Qué cambió en la interfaz?"
El refactoring causó un import circular
> "Mover user_validator.py a validators/ creó un import
circular con user_service.py. ¿Cómo resuelvo esto?"
Un paso tomó más de lo estimado
Ajusta el plan. Si Phase 2 tomó 90 min en vez de 60, reduce scope de Phase 3 para mantenerte en el tiempo total estimado.
Trampas Comunes en la Ejecución
Cinco errores que aparecen específicamente al ejecutar el proyecto integrador. Anticípalos.
1. "Combinar pasos para ir más rápido"
Síntoma: Hiciste extract + move + rename + dead code en un solo commit "para terminar rápido". Tests fallan. No sabes qué cambio rompió qué.
Por qué pasa: El instinto humano de "consolidar trabajo". Pero combinar cambios pierde la atomicidad que hace debug rápido.
Cómo corregir: Un tipo de cambio por commit. Sin excepciones. La cápsula 04 del Módulo 7 desarrolla por qué incremental gana — esto es esa lección aplicada.
2. "Saltar tests entre pasos para no perder ritmo"
Síntoma: Hiciste 3 cambios sin correr tests entre ellos. El cuarto cambio falla. Los tests revelan que el problema es del cambio 1, no del 4.
Por qué pasa: Confianza en que "los cambios chicos no rompen tests". Pero los tests son baratos — son la única señal objetiva de "el comportamiento se preservó".
Cómo corregir: Tests después de cada commit. Si el ciclo "test → commit → test → commit" se vuelve tedioso, automatízalo con un git hook.
3. "Arreglar un bug encontrado durante la migración"
Síntoma: Mientras refactorizas, descubres que calculate_tax tiene un edge case mal manejado desde hace meses. Lo "arreglas" mientras tocas el archivo.
Por qué pasa: Optimismo: "ya estoy aquí, lo arreglo de paso". Pero ahora la migración mezcla refactoring + bug fix. ¿Cómo verificas que los tests siguen capturando comportamiento? No puedes — porque el comportamiento cambió.
Cómo corregir: Documenta el bug en HANDOFF.md como "issue found, not addressed". El bug fix es otro proyecto, no este. Esta disciplina es lo que separa migración (preserva) de rewrite (cambia).
4. "Sesión de Claude Code de 3+ horas"
Síntoma: Vas en hora 3 con la misma sesión. Claude Code empieza a olvidar archivos, generar código inconsistente, repetir preguntas.
Por qué pasa: Context pressure (Módulo 6, cápsula 02). Las sesiones largas acumulan context que diluye lo importante.
Cómo corregir: Sesiones de máximo 1 hora por phase. Entre phases, empieza nueva sesión cargando solo CLAUDE.md + los archivos relevantes para la phase siguiente. Es contraintuitivo pero más rápido.
5. "Modificar el plan en medio de la ejecución sin documentarlo"
Síntoma: El plan decía "extraer 3 services". A mitad encontraste razón para extraer solo 2. Cambiaste sin documentar. Después no sabes si fuiste fiel al plan o no.
Por qué pasa: Adapción legítima al descubrir información nueva — pero sin trazabilidad.
Cómo corregir: Cualquier cambio al plan se documenta en MIGRATION_PLAN.md con razón. "Phase 2 ajustada: 2 services en lugar de 3 porque PaymentService y RefundService comparten 80% de lógica — se extrae como uno solo." Trazabilidad protege la integridad del proceso.
Conexión con Siguiente Cápsula
La cápsula 05 (Entrega) toma el proyecto refactorizado + modernizado y produce la documentación final: Architecture Map "After", CHANGE_LOG, HANDOFF.md, y métricas before/after.
Importante: el CHANGE_LOG.md no se escribe al final — se va construyendo durante esta cápsula. Cada commit que haces es una entrada del log. Si dejas la documentación para la cápsula 05, vas a olvidar detalles importantes.
Documentación incremental durante ejecución
# CHANGE_LOG.md (vivo durante la ejecución)
## Phase 2: Structure Refactoring
### Commit: extract PaymentService from routes/payments.py
- Movido: cálculo de fees, validación de monto, charge logic
- Quedó en route: solo I/O (parse request, return response)
- Tests: ✅ 12/12
### Commit: extract OrderService from routes/orders.py
- ... (mismo formato)Llenar el CHANGE_LOG conforme commites convierte la cápsula 05 en consolidación, no creación.
Troubleshooting
Muchos tests fallan después de un cambio
Solución: Probablemente el cambio fue demasiado grande. Revierte (git checkout) y divide en pasos más pequeños. Si tienes git tag de la phase anterior, git reset --hard <tag> te lleva al punto seguro.
Claude Code pierde contexto a mitad de la ejecución
Solución: Inicia nueva sesión con CLAUDE.md + los archivos que estás modificando. No intentes mantener una sesión de 2 horas. La trampa #4 desarrolla por qué.
El refactoring reveló bugs que no son parte de la migración
Solución: Documenta los bugs como findings pero NO los fixes ahora. La migración preserva comportamiento — fix de bugs es un proyecto separado. La trampa #3 desarrolla por qué.
Phase 2 tomó mucho más de lo estimado
Solución: Ajusta scope de Phase 3, no del proyecto. Documenta en MIGRATION_PLAN.md el ajuste con razón. El objetivo es entregar un proyecto coherente — no completar todo el plan original.
Te quedas atorado en un import circular después del refactoring
Solución: Es la trampa más común al introducir service layer. La solución no es invertir el move — es identificar la dependencia compartida y extraerla a un módulo común. Pídele a Claude Code: "el refactoring creó este import circular. Diagnóstica la causa y propón resolución sin revertir el extract."
Cierre de la Cápsula
Al terminar la ejecución, deberías tener:
- ✅ Un git history limpio con commits atómicos (1 tipo de cambio = 1 commit)
- ✅ Tests verdes en cada commit (no "voy a arreglar después")
- ✅ MIGRATION_PLAN.md actualizado si hubo ajustes con razón documentada
- ✅ CHANGE_LOG.md construido en vivo durante la ejecución
- ✅ Tags de git marcando el final de cada phase
Si esos 5 ítems están en su lugar, la cápsula 05 (Documentación + Handoff) se vuelve consolidación, no creación. Si faltan, vas a necesitar reconstruir información que ya tenías — y eso pesa el doble.
Próxima cápsula: 05 — Entrega: Documentación + Handoff — donde produces el Architecture Map AFTER, métricas before/after, y el HANDOFF.md profesional que cierra el proyecto.
La cápsula 05 es la diferencia entre "código migrado" (resultado técnico) y "proyecto completo portfolio-worthy" (resultado profesional). Mismo código en ambos casos — distinto entregable.