Módulo 8: Proyecto Integrador — Migración de Proyecto Legacy Real

Módulo 8: Proyecto Integrador — Migración de Proyecto Legacy Real

Siguiente →

Módulo 8: Proyecto Integrador — Migración de Proyecto Legacy Real

Descripción de la cápsula

Este módulo cierra la guía consolidando todas las técnicas en un proyecto real de principio a fin. Los módulos 1-7 te enseñaron skills individuales: onboarding, exploración, architecture analysis, refactoring, migración, context management, modernización. El módulo 8 los encadena en un workflow completo que refleja cómo funciona una migración real en la industria.

No puedes migrar un proyecto si no lo entiendes (M1-3). No puedes refactorizar sin tests y coordinación multi-file (M4). No puedes migrar framework sin strategy incremental (M5). No puedes trabajar con proyectos grandes sin context management (M6). Y no puedes modernizar sin priorización y enfoque incremental (M7). Este módulo es la prueba de que dominas todo el pipeline.

El entregable es genuinamente portfolio-worthy: un proyecto legacy migrado con documentación completa que demuestra habilidad de nivel senior.

Al completar las 5 cápsulas, habrás ejecutado una migración completa de un proyecto legacy aplicando los 7 módulos previos como un único pipeline, producido documentación profesional con architecture maps antes/después, change log detallado, y handoff doc, y demostrado habilidad de nivel senior en un artefacto que puedes mostrar en entrevistas o procesos de hiring.

Contexto del Módulo

Phase 1: Entender Codebases (M1-3) ✅
Phase 2: Refactoring (M4-6) ✅
Phase 3: Legacy y Proyecto (M7-8)
├── Módulo 7: Modernizar Legacy Code ✅
└── Módulo 8: Proyecto Integrador ← ESTÁS AQUÍ

Este es el último módulo de la guía #8. No hay módulo siguiente — el siguiente paso es aplicar todo a tu trabajo real o continuar con otras guías del path Agentic Development.

Objetivo Profesional

Ejecutar una migración completa de un proyecto legacy usando Claude Code, produciendo un resultado profesional con documentación que demuestra mastery de todas las técnicas de la guía.

Al final podrás:

  • ✅ Ejecutar project assessment de un codebase legacy
  • ✅ Crear migration plan con phases y checkpoints
  • ✅ Ejecutar el full migration cycle: onboarding → analysis → tests → refactoring → modernización → validation → documentation
  • ✅ Producir architecture maps antes/después
  • ✅ Crear handoff documentation profesional
  • ✅ Documentar cada decisión con justificación rastreable

Por Qué Este Proyecto Es Diferente

Hasta ahora, cada módulo te dio un skill aislado. Este módulo te pide ejecutar todos en secuencia, con un único entregable, en un codebase real — no en ejemplos curados.

Módulos 1-7 (skills individuales):
→ "Practica onboarding en este codebase de ejemplo"
→ "Practica refactoring en estos 5 archivos"
→ "Practica modernización en este módulo"
→ Cada uno aislado, con condiciones controladas

Módulo 8 (integración):
→ "Toma un proyecto real con tech debt real"
→ "Aplica TODO lo aprendido en secuencia"
→ "Produce un entregable profesional con documentación"
→ Sin condiciones controladas: la realidad

Es la diferencia entre practicar tiros libres y jugar un partido completo. Los módulos previos son tiros libres. Este es el partido. La integración es donde aparecen los desafíos que no aparecen en ejercicios aislados: dependencias inesperadas, archivos grises (¿es legacy o solo old?), decisiones donde el plan dice una cosa pero el codebase pide otra.

Lo que hace este proyecto portfolio-worthy

Lo que produces NO ES:
❌ Un repo con código que pasa tests (eso lo produce cualquier curso)
❌ Una lista de cambios sin contexto

Lo que produces SÍ ES:
✅ Codebase migrado con tests verdes
✅ Architecture map BEFORE (al inicio) y AFTER (al final) — evidencia
   visual del cambio
✅ Change log con decisiones rastreables: "esto se hizo, esto NO se hizo,
   y por qué"
✅ Handoff doc que un colega podría usar para continuar el trabajo
✅ Métricas before/after: tech debt items resueltos, líneas eliminadas,
   coverage añadido

Un empleador o cliente puede leer esto y verificar que entiendes migración a nivel senior — no que "sabes Claude Code".

Progresión del Módulo

CápsulaTemaQué harás
01Introducción + Assessment (esta cápsula)Evaluar el proyecto legacy: estado, tech debt, prioridades
02Onboarding + ArchitectureEntender el codebase y generar architecture map (M1-3)
03Migration Planning + Safety NetsCrear plan de migración + tests de regresión (M4-5)
04Execution: Refactoring + ModernizaciónEjecutar el refactoring y modernización (M4, M7)
05Entrega: Documentación + HandoffProducir documentación final

Flujo de aprendizaje

Esta cápsula 01 hace el assessment inicial — sin esto, decides a ciegas. Las cápsulas 02-04 ejecutan el ciclo completo aplicando los módulos 1-7. La cápsula 05 cierra con documentación que convierte el trabajo técnico en un artefacto profesional.

El Proyecto

Codebase Legacy a Migrar

Usa un proyecto legacy real. Opciones:

Opción A — Proyecto proporcionado:

Un mini-proyecto Flask de 10-15 archivos, ~2K líneas, con tech debt realista: sin tests, patterns mixtos, dependencias deprecated, naming inconsistente, lógica en los route handlers, sin type hints. Disponible en el repositorio de ejemplos de la guía.

Opción B — Proyecto open-source:

Un proyecto open-source que necesite modernización. Busca issues tagged "good first issue" + "refactoring" en GitHub. Repos con poca actividad y deuda visible son ideales.

Opción C — Tu propio proyecto:

Si tienes un proyecto legacy real que quieres mejorar, úsalo. El beneficio es que produces valor real para tu empresa o producto personal.

Requisitos mínimos:

  • 5-15 archivos
  • 1-3K líneas de código
  • Al menos 3 tipos de tech debt
  • Funcionalidad verificable (puedes correr la app)
  • Permite cambios (si es de tu trabajo, confirma con tu equipo)

El Full Migration Cycle

1. ASSESS    → Evaluar estado del codebase (esta cápsula)
2. ONBOARD   → Entender con Claude Code (M1)
3. ANALYZE   → Architecture map (M3)
4. PLAN      → Migration plan con checkpoints
5. TEST      → Safety net de regresión (M4-5)
6. REFACTOR  → Mejorar estructura (M4)
7. MODERNIZE → Actualizar patterns (M7)
8. VALIDATE  → Verificar comportamiento preservado
9. DOCUMENT  → Handoff documentation

Cada paso usa técnicas específicas de módulos anteriores. El valor de este proyecto es la integración — no inventarás técnicas nuevas, las orquestas.

Assessment: Primer Paso (Lo que Haces en Esta Cápsula)

El assessment es la decisión informada antes de empezar a tocar código. Sin assessment, decides a ciegas. Con assessment, cada decisión tiene justificación rastreable.

El comando inicial

> "Analiza este proyecto legacy y produce un assessment:
   1. Tamaño: archivos, líneas, módulos
   2. Tech stack: lenguaje, framework, dependencias
   3. Test coverage: ¿hay tests? ¿cuántos? ¿qué cubren?
   4. Tech debt: top 5 problemas por severidad
   5. Documentation: README, docstrings, comentarios
   6. Overall health score: 1-10 con justificación"

El Assessment Report

# Project Assessment: [Nombre del proyecto]

## Overview
- Files: X
- Lines: X
- Framework: Flask 1.x
- Python: 3.8
- Tests: 0 (!)
- Dependencies: 5 (2 deprecated)

## Health Score: 4/10
- ✅ Funciona (la app corre)
- ✅ Tiene estructura básica de directorios
- ❌ Sin tests
- ❌ Sin type hints
- ❌ Lógica en route handlers (no service layer)
- ❌ Dependencies deprecated
- ❌ Dead code significativo

## Top 5 Tech Debt
1. [ALTA] Lógica en route handlers → necesita service layer
2. [ALTA] 0 tests → necesita safety net antes de cualquier cambio
3. [MEDIA] Dependencies deprecated → requests 2.25 → httpx
4. [MEDIA] No type hints → difícil de mantener
5. [BAJA] Dead code: 3 funciones no usadas

## Recommendation
Prioridad: Tests → Service Layer → Dependencies → Type Hints → Dead Code
Estimado: 8-12 horas con Claude Code

Por qué el assessment es la cápsula más importante

Sin un assessment riguroso, todo lo que viene después es improvisación. Con assessment, las cápsulas 02-05 ejecutan un plan informado:

  • El scope del proyecto está acotado (no agregas features nuevos)
  • La prioridad del tech debt está clara
  • La estimación te ayuda a decidir si es 1 día o 1 semana de trabajo
  • El health score sirve como baseline para el "after" del proyecto

Conexión con las Cápsulas Siguientes

  • Cápsula 02: Onboarding + Architecture analysis del proyecto (aplica M1, M2, M3)
  • Cápsula 03: Migration planning + Safety nets — tests de regresión que protegen el cambio (aplica M4)
  • Cápsula 04: Ejecución del refactoring y modernización con todos los módulos previos (aplica M4, M5, M7)
  • Cápsula 05: Documentación final + Handoff — convierte el trabajo técnico en artefacto profesional

El architecture map que produces en la cápsula 02 es el input directo del plan de la cápsula 03. El plan de la cápsula 03 es el input de la ejecución de la cápsula 04. La ejecución de la cápsula 04 alimenta la documentación de la cápsula 05. Es una pipeline lineal — saltarse pasos rompe el flujo.

Trampas a Evitar al Cursar Este Módulo

Cinco malentendidos previsibles que aparecen específicamente cuando integras los 7 módulos en un proyecto único.

1. "Voy a empezar refactorizando porque me siento cómodo con M4"

Es la trampa más cara. Sin assessment (esta cápsula) y sin architecture map (cápsula 02), tus decisiones de refactoring no tienen base. Vas a refactorizar lo equivocado, en el orden equivocado, sin las prioridades correctas. La regla del módulo 8 es secuencia obligatoria: assess → onboard → analyze → plan → test → execute → document.

2. "El assessment es solo paperwork"

No. El assessment es la decisión informada de qué tocar y qué no. Sin assessment, vas a tocar 30 cosas y resolver 5. Con assessment, tocas 5 y resuelves 5. El tiempo invertido en assessment se recupera 5× en la ejecución.

3. "Voy a aprovechar para mejorar la lógica de negocio"

No mientras ejecutas el proyecto integrador. Migración preserva comportamiento. Si el código tiene un bug, lo documentas en el handoff doc — no lo arreglas ahora, porque mezclar bug fixes con migración hace imposible verificar qué cambió y por qué. La cápsula 05 te da el formato del "issues found, not addressed" doc.

4. "Si Claude Code lista 30 items de tech debt, los arreglo todos"

No. El módulo 7 te dio la matriz impacto/riesgo. Aquí la aplicas. Probablemente abordes 5-10 items de los 30 — los de alto impacto y riesgo manejable. Los demás se documentan como "tech debt remaining" en el handoff. Querer resolver todo en un PR es cómo se hacen los "big bang" del módulo 7 que terminan mal.

5. "La documentación es lo último, lo hago al final si me sobra tiempo"

Lo opuesto. La documentación es el entregable más valioso. Un proyecto migrado sin documentación es trabajo personal; con documentación, es portfolio. La cápsula 05 te da la estructura — empieza el change log desde el primer commit, no al final.

Diagnóstico: ¿Listo para el Proyecto Integrador?

Cinco preguntas para confirmar que tienes lo necesario antes de empezar.

Pregunta 1: ¿Puedes ejecutar onboarding sistemático con Claude Code en menos de 1 hora? (M1)

Si sí: vas listo para la cápsula 02.

Si no: repasa el Módulo 1 (las 5 preguntas de onboarding y el doc de hallazgos).

Pregunta 2: ¿Puedes generar un Architecture Map (dependency map + flow analysis + patterns) de un proyecto que no conoces? (M3)

Si sí: la cápsula 02 va a fluir.

Si no: repasa Módulo 3. Es input directo del plan de migración.

Pregunta 3: ¿Escribes tests de regresión por hábito antes de cualquier refactoring? (M4)

Si sí: vas a sobrevivir la ejecución de la cápsula 04.

Si dudas: repasa Módulo 4 cápsula 05. Sin esto, el proyecto integrador es un "big bang" arriesgado.

Pregunta 4: ¿Tienes un CLAUDE.md útil para tus proyectos? (M6)

Si sí: vas a poder mantener context productivo durante el proyecto.

Si no: repasa M6 cápsula 04 antes de empezar — vas a necesitarlo para el codebase elegido.

Pregunta 5: ¿Sabes la diferencia entre modernización (preserva comportamiento) y rewrite (cambia comportamiento)? (M7)

Si sí: vas a evitar la trampa #3.

Si dudas: repasa M7 antes de la cápsula 04 del proyecto.

Si dudaste en 2 o más: regresa al módulo correspondiente antes de empezar el proyecto. El módulo 8 no se puede ejecutar bien sin los previos sólidos. Si respondiste todas con confianza, estás listo — empieza con el assessment de tu codebase elegido.

Evidencia de Éxito Final

Al cierre del proyecto integrador, tu entregable debe contener:

  • ✅ Project Assessment (esta cápsula) — el documento que justifica todas las decisiones
  • ✅ Architecture Map BEFORE y AFTER (cápsula 02 + cápsula 05) — evidencia visual del cambio
  • ✅ Migration Plan (cápsula 03) — phases con checkpoints
  • ✅ Test suite de regresión (cápsula 03) — green pre y post migración
  • ✅ Codebase migrado (cápsula 04) — refactorizado y modernizado, tests verdes
  • ✅ Change log (cápsula 05) — un commit por tipo de cambio, justificación rastreable
  • ✅ Handoff doc (cápsula 05) — un colega podría continuar tu trabajo leyéndolo
  • ✅ Métricas before/after (cápsula 05) — tech debt items resueltos, coverage, líneas eliminadas

Si los 8 entregables están en su lugar, completaste la guía #8 — y tienes un artefacto que demuestra habilidad de nivel senior en migración de codebases legacy con AI.

Resumen

  • Este módulo integra todo lo que aprendiste en M1-M7
  • El full migration cycle tiene 9 pasos que se ejecutan en secuencia
  • El assessment es el primer paso — informa todas las decisiones siguientes
  • El proyecto es portfolio-worthy: demuestra habilidad de nivel senior
  • Usa un codebase real con tech debt real
  • La trampa más cara es saltarse el assessment y empezar a tocar código
  • La documentación es el entregable más valioso, no la última tarea opcional

Siguiente cápsula: 02 — Onboarding + Architecture Analysis — aplicas M1 (onboarding) y M3 (architecture map) al proyecto que asseseaste aquí. Es el input directo del plan de migración (cápsula 03).

Recursos Adicionales

  1. Working Effectively with Legacy Code - Michael Feathers, la biblia del legacy code
  2. Refactoring - Martin Fowler - La referencia de refactoring
  3. The Pragmatic Programmer - Principios de software que aplican a migraciones
  4. Strangler Fig Pattern - Para migraciones graduales
  5. Claude Code Documentation - Referencia de la herramienta principal
  6. The Software Engineer's Guidebook - Gergely Orosz - Capítulos sobre migration y senior-level work
← AnteriorProyecto del Módulo: Modernización de Módulo LegacySiguiente →Onboarding y Architecture Analysis del Proyecto Legacy