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

Migration Planning y Safety Nets

Siguiente →

Migration Planning y Safety Nets

Descripción de la cápsula

Con el Architecture Map completo (cápsula 02), tienes el mapa: sabes qué hay, dónde está, y qué necesita cambiar. Esta cápsula te enseña a transformar ese mapa en un plan ejecutable y a construir la red de seguridad (tests de regresión) que protege cada cambio. Es la cápsula de preparación — cuando termines, estarás listo para ejecutar con confianza en la cápsula 04.

Hay un principio que separa esta cápsula de las anteriores: nada se modifica todavía. El plan se diseña, los tests se escriben, los git tags se colocan. Pero el código de producción no se toca. Esa disciplina es la diferencia entre un proyecto integrador exitoso y un "intentamos pero algo se rompió y no supimos qué".

Al terminar la cápsula, vas a tener: (1) un MIGRATION_PLAN.md ejecutable con phases, checkpoints y rollback, (2) una test suite de regresión que cubre el comportamiento crítico actual, y (3) un git tag pre-migration que es tu punto de retorno seguro.

Por Qué Plan + Safety Net Van Antes de Ejecutar

Es tentador empezar a refactorizar. El Architecture Map identificó anti-patterns claros, sabes qué cambiar — ¿por qué no empezar?

Por la misma razón que un cirujano no opera sin anestesia ni un equipo sin checklist:

Sin plan + safety net:
→ Cambias código → algo se rompe
→ ¿Qué cambió rompió qué? Imposible saber sin tests
→ Solución: revertir TODO, replantear, pérdida de tiempo
→ O peor: pushear el bug a producción

Con plan + safety net:
→ Tests verdes ANTES del cambio (baseline)
→ Cambias código → tests verdes → continuar
→ Si tests rojos → SABES qué cambio causó qué
→ Rollback localizado en minutos
→ Confianza de equipo intacta

El plan + safety net no es preparación opcional — es la única forma de ejecutar la migración sin riesgo.

El Migration Plan

Estructura del plan

Basándote en los findings del Architecture Map, diseña un plan con fases:

# Migration Plan: [Proyecto]

## Scope
- [Qué se va a mejorar]
- [Qué se mantiene igual]

## Phases

### Phase 1: Safety Net (Tests)
- Escribir tests de regresión para endpoints/funciones principales
- Meta: 70%+ de cobertura en código crítico
- Checkpoint: all tests green

### Phase 2: Structure (Refactoring)
- Extract service layer (si no existe)
- Move modules a directorios correctos
- Rename para consistencia
- Checkpoint: tests green, estructura mejorada

### Phase 3: Modernization
- Syntax modernization (f-strings, type hints, etc.)
- Pattern modernization (context managers, enums)
- Dead code removal
- Dependency updates
- Checkpoint: tests green, código modernizado

### Phase 4: Documentation
- Architecture map "After"
- CHANGE_LOG
- Handoff notes
- Checkpoint: documentation complete

## Rollback Strategy
- Git tag antes de cada phase
- Si Phase N falla: revert a Phase N-1
- Tests como criterio de success/failure

## Estimated Time
- Phase 1: 30-45 min
- Phase 2: 45-60 min
- Phase 3: 30-45 min
- Phase 4: 20-30 min
- Total: 2-3 hours

Generando el plan con Claude Code

> "Basándote en el Architecture Map, genera un migration
   plan para este proyecto. Incluye:
   1. Phases con orden de ejecución
   2. Checkpoints con criterio de éxito
   3. Rollback strategy por phase
   4. Estimación de tiempo
   
   Prioriza: tests primero, luego estructura,
   después modernización, al final documentación."

Safety Net: Tests de Regresión

Escribir tests ANTES de cualquier cambio

> "Escribe tests de regresión completos para el proyecto:
   1. Test de cada endpoint (happy path + error cases)
   2. Test de funciones de negocio principales
   3. Test de integración del flujo principal
   
   Los tests deben pasar con el código ACTUAL.
   No optimices ni corrijas nada — captura el
   comportamiento tal como es."

Verificar la safety net

> "Ejecuta todos los tests y reporta:
   1. Total de tests
   2. Tests passing
   3. Coverage percentage
   4. Cualquier test que falle (eso es un bug en el test,
      no en el código)"

Plan Ejemplificado: Caso Real

Para anclar la cápsula, considera un proyecto típico del Módulo 8 (Flask, ~2K líneas, 0 tests, tech debt mixto). El plan podría verse así:

# Migration Plan: payments-legacy-app

## Scope
- ✅ Mejora: estructura (extraer service layer), modernización syntax,
       eliminar dead code identificado
- ❌ NO incluye: cambio de framework, mejoras a la lógica de negocio,
                 cambios al modelo de datos
- ❌ Tech debt remanente documentado para backlog (no en este proyecto):
       (1) refactoring del módulo de notificaciones,
       (2) migración a async,
       (3) introducción de feature flags

## Phases con Checkpoints

### Phase 1: Safety Net (45 min)
**Objetivo:** Tests de regresión que capturen comportamiento actual
**Acciones:**
- Tests para los 4 endpoints críticos identificados en Architecture Map
- Tests para las 3 funciones de negocio centrales
- 1 test de integración del flujo principal (POST /orders end-to-end)
**Checkpoint:** todos los tests passing contra el código ACTUAL

### Phase 2: Structure Refactoring (60 min)
**Objetivo:** Extraer service layer, normalizar estructura
**Acciones (un commit cada uno):**
- Extract `PaymentService` de `routes/payments.py`
- Extract `OrderService` de `routes/orders.py`
- Move helpers de `utils/payments_utils.py` a `services/payment_service.py`
- Rename funciones inconsistentes (snake_case)
**Checkpoint:** tests verdes después de cada commit

### Phase 3: Modernization (45 min)
**Objetivo:** Modernizar syntax y patterns dentro de la nueva estructura
**Acciones (un commit por tipo, M07 cápsula 04):**
- Dead code removal (verificado dinámicamente)
- f-strings throughout
- isinstance() en lugar de type() == X
- Context managers para file I/O
- Type hints en funciones públicas
**Checkpoint:** tests verdes, módulo pasa pyupgrade --py310-plus

### Phase 4: Documentation (30 min)
**Objetivo:** Producir entregables para handoff
**Acciones:**
- Architecture Map AFTER (comparar con BEFORE)
- CHANGE_LOG.md con cada commit explicado
- HANDOFF.md con tech debt remanente
- Métricas before/after
**Checkpoint:** documentación cubre los 4 entregables del módulo 8

## Rollback Strategy

```bash
# Tags antes de cada phase
git tag pre-migration              # estado inicial
git tag post-phase-1-tests         # tras safety net
git tag post-phase-2-structure     # tras refactoring
git tag post-phase-3-modernization # tras modernización

# Si algo falla:
git reset --hard <tag>             # rollback al phase previo

Estimated Time

  • Phase 1: 45 min
  • Phase 2: 60 min
  • Phase 3: 45 min
  • Phase 4: 30 min
  • Total: ~3 horas

Criterios de "Done"

  • ✅ Tests verdes
  • ✅ Architecture Map AFTER documenta el cambio
  • ✅ CHANGE_LOG con métricas before/after
  • ✅ Git history limpio (1 commit = 1 tipo de cambio)
  • ✅ Tech debt remanente documentado

Este plan es **ejecutable**: cada phase tiene acciones concretas, criterio de "done", y rollback. Sin este nivel de detalle, ejecutar es improvisar.

---

## Trampas Comunes en Planning + Safety Nets

### 1. "Empezar a escribir tests sin entender el comportamiento actual"

Los tests de regresión capturan **el comportamiento actual**, no el ideal. Si la función tiene un bug, el test debe reproducir ese bug. Si "arreglas" el bug mientras escribes el test, ya no estás capturando — estás cambiando. La cápsula 04 es donde se pueden hacer cambios; aquí solo se captura.

### 2. "Cobertura 100% antes de empezar"

Sweet spot: 70-80% en código crítico (paths principales, money path, auth). Pretender 100% bloquea el proyecto y produce tests poco valiosos para casos triviales. Mejor 70% sólido que 100% mediocre.

### 3. "Tests verdes pero sin contenido real"

`def test_function_exists(): assert function is not None` no es un test. Cada test debe **ejercitar comportamiento** — input específico, output verificado. Si tu test no falla cuando comentas la lógica de la función, no es un test útil.

### 4. "Plan sin rollback strategy"

"Si algo falla, reverteré" no es estrategia. Estrategia es: tags por phase + tests como criterio de éxito + rollback documentado en menos de 5 minutos. Sin esto, un fallo en phase 3 puede destruir 2 horas de trabajo.

### 5. "Subestimar el tiempo del plan"

Si tu estimación es "2 horas", el plan probablemente toma 4. Multiplica por 1.5x lo que estimes y todavía te puedes pasar. La cápsula 04 ejecuta — y los proyectos integradores que se "atoran" típicamente se atoran porque el plan subestimaba el esfuerzo.

---

## Entregable de Esta Cápsula

1. **MIGRATION_PLAN.md** — Plan completo con phases, checkpoints, rollback (siguiendo la estructura ejemplificada arriba)
2. **tests/** — Suite de tests de regresión con coverage 70%+ en código crítico
3. **Git tag:** `pre-migration` en el estado actual del codebase

---

## Diagnóstico: ¿Está Listo Tu Plan + Safety Net?

<details>
<summary>Pregunta 1: ¿Tu MIGRATION_PLAN.md tiene phases con criterio de "done" verificable?</summary>

**Si sí:** la cápsula 04 puede ejecutar.

**Si no:** sin "done verificable", no sabes cuándo terminar una phase. Reescribe.
</details>

<details>
<summary>Pregunta 2: ¿Tus tests de regresión pasan contra el código actual SIN modificarlo?</summary>

**Si sí:** safety net activa.

**Si dudas:** ejecuta los tests. Si fallan, los tests están mal (capturan comportamiento que no existe) — corrígelos antes de avanzar.
</details>

<details>
<summary>Pregunta 3: ¿Documentaste cómo hacer rollback de cada phase en menos de 5 minutos?</summary>

**Si sí:** vas con seguridad.

**Si no:** "git reset al último commit" no es rollback de phase. Necesitas tags específicos por phase.
</details>

<details>
<summary>Pregunta 4: ¿Tu plan deja explícito qué tech debt NO vas a abordar?</summary>

**Si sí:** scope acotado, expectativas claras.

**Si no:** vas a sentirte presionado a abordar todo y el proyecto crece sin control.
</details>

---

## Conexión con Siguiente Cápsula

La **cápsula 04 (Execution)** toma el migration plan y lo ejecuta. Los tests que escribiste aquí son la safety net que verifica cada cambio. Sin un buen plan + safety net en esta cápsula, la ejecución se vuelve improvisación riesgosa.

La **cápsula 05 (Documentación)** consume el CHANGE_LOG que se va construyendo desde la phase 1 — empieza el log desde el primer commit, no al final.

---

## Troubleshooting

### El código legacy es difícil de testear

Usa mocking mínimo. Si una función tiene dependencias hardcodeadas, monkey-patch solo lo necesario. El objetivo es capturar comportamiento, no escribir tests perfectos.

### No llego a 70% coverage

Enfócate en los paths más usados. Si el endpoint de login tiene 10 paths, testea los 3-4 más comunes. 70% de lo importante > 100% de lo trivial.

### El migration plan es demasiado ambicioso

Reduce scope. Mejor migrar 60% del proyecto con calidad que 100% con prisa. Documenta lo no abordado como tech debt remanente en HANDOFF.md.

### Los tests "capturan" un bug del código original

Documenta el bug en HANDOFF.md como "issue found, not addressed". Tu test debe seguir verde porque captura el comportamiento actual (con el bug). Arreglar el bug es **otro proyecto**, no este.
← AnteriorOnboarding y Architecture Analysis del Proyecto LegacySiguiente →Execution: Refactoring, Modernización y Testing