Módulo 4: Refactoring Multi-File Coordinado

Descripción de la cápsula

Phase 1 te enseñó a entender codebases: onboarding sistemático, exploración con Explore, y architecture analysis completo. Ahora empieza Phase 2: modificar codebases. Y el primer tipo de modificación — el más común y más valioso en tu trabajo diario — es refactoring: cambiar la estructura del código sin cambiar su comportamiento.

Lo que hace este módulo diferente de cualquier tutorial de refactoring es la palabra "coordinado." Un rename en un IDE toca 3-4 archivos y toma 2 segundos. Pero un refactoring real — extraer un service layer, reorganizar la estructura de módulos, cambiar una interfaz que 15 archivos consumen — eso es coordinación multi-file. Los IDEs no manejan esto bien. Claude Code sí: puede leer todos los archivos afectados, entender las dependencias, y hacer los cambios coordinados con verificación.

Este módulo tiene un prerequisito implícito pero fundamental: la guía #7 (Testing with Claude Code). Refactoring sin tests es cirugía sin anestesia — técnicamente posible, pero irresponsable. Antes de cada refactoring, escribes tests de regresión. Después de cada refactoring, verificas que los tests pasan. Ese ciclo es la regla de oro de este módulo.

Al terminar las 6 cápsulas, vas a poder planificar y ejecutar refactoring coordinado que toca múltiples archivos, escribir tests de regresión antes de cualquier cambio, y verificar que el comportamiento se preservó — todo dirigiendo Claude Code como coordinador, no como generador autónomo.

Contexto del Módulo

¿Dónde estamos?

Esta es la Guía #8 del Claude Code Agentic Development Path, Phase 2: Refactoring (Módulos 4-6).

Phase 1: Entender Codebases (Módulos 1-3) ✅ COMPLETADA
├── Módulo 1: Onboarding con AI ✅
├── Módulo 2: Agentic Research con Explore ✅
└── Módulo 3: Entender Arquitectura Existente ✅

Phase 2: Refactoring (Módulos 4-6)
├── Módulo 4: Refactoring Multi-File ← ESTÁS AQUÍ
│   → Rename, extract, move, interface changes con Claude Code
├── Módulo 5: Migración de Frameworks
│   → Flask→FastAPI, strangler fig pattern, migration testing
└── Módulo 6: Context Management para Proyectos Grandes
    → 1M tokens, chunking, CLAUDE.md, progressive context

Phase 3: Legacy y Proyecto (Módulos 7-8)
├── Módulo 7: Modernizar Legacy Code
└── Módulo 8: Proyecto Integrador — Migración Completa

Lo que ya sabes

De Phase 1 llegas con:

Método sistemático de onboarding (Módulo 1)
Dominio de Explore para investigación read-only (Módulo 2)
Architecture Map con dependency maps, flow analysis, y pattern/anti-pattern identification (Módulo 3)

De la guía #7 (Testing) llegas con:

Spec-first methodology
TDD con Claude Code
Tests de regresión y coverage

¿Hacia dónde vamos?

Este módulo te enseña los tipos fundamentales de refactoring. El Módulo 5 escala al nivel de frameworks (Flask→FastAPI). El Módulo 6 te da las herramientas para hacer todo esto en proyectos grandes que no caben en el context window. Y el Módulo 8 integra todo en una migración completa.

Objetivo Profesional

Al final de este módulo, serás capaz de planificar y ejecutar refactoring coordinado que toca múltiples archivos usando Claude Code como tu herramienta principal — con tests de regresión que garantizan que el comportamiento no cambió.

Al final de este módulo podrás:

✅ Ejecutar rename refactoring cross-file: renombrar función/clase y actualizar todas las references
✅ Aplicar extract function/class: sacar lógica a un nuevo módulo y actualizar callers
✅ Ejecutar move module: mover archivos y actualizar todos los imports
✅ Propagar interface changes: modificar firma de función y actualizar implementaciones/consumers
✅ Escribir tests de regresión ANTES de refactorizar
✅ Usar Claude Code como coordinador de cambios multi-file
✅ Verificar que el refactoring preservó el comportamiento

Un Refactoring Real: IDE vs Claude Code Coordinado

Para anclar el módulo, considera una tarea típica de mediano tamaño:

Tarea: Extraer la lógica de cálculo de precios (que actualmente vive en 3 route handlers de Flask) a un nuevo pricing_service.py. La lógica está duplicada parcialmente, tiene 4 funciones helper privadas, y los handlers la usan con argumentos ligeramente diferentes.

Enfoque A: Solo IDE (PyCharm, VS Code)

1. Localizar el código duplicado leyendo los 3 handlers
   manualmente. (~15 min)

2. Crear pricing_service.py y copiar el código.
   Decidir cómo unificar las 3 versiones ligeramente
   distintas. (~30 min)

3. Actualizar el handler 1: importar el service, reemplazar
   la lógica. Ajustar argumentos. Probar. (~20 min)

4. Repetir para handler 2 y handler 3. Cada uno con sus
   sutilezas. (~40 min)

5. Encontrar los tests existentes (si hay) y ajustarlos.
   Probablemente romper algunos. (~30 min)

6. Debug del rompimiento. Buscar referencias indirectas
   que olvidaste. (~45 min)

TOTAL: ~3 horas. Riesgo de bug: ALTO (manual).

Enfoque B: Claude Code coordinado (este módulo)

1. RESEARCH (M2 técnicas, ya las dominas)
   "Encuentra todas las funciones que calculan precio,
    independiente de cómo se llamen. Lista archivo, función,
    diferencias entre ellas."
   → Claude Code lista las 3 ubicaciones y diferencias. (~3 min)

2. TESTS DE REGRESIÓN (Cápsula 05)
   "Escribe tests de regresión que capturen el comportamiento
    actual de las 3 versiones, incluyendo casos edge."
   → Tests pasan contra el código actual. Safety net activo. (~10 min)

3. PLAN
   "Vamos a extraer pricing_service.py con una función unificada
    que acepta los argumentos de las 3 variantes via parámetros
    opcionales. Después actualizar los 3 handlers."

4. EXTRACT (Cápsula 02)
   "Crea pricing_service.py con la función unificada. Mantén
    los handlers usando su lógica antigua por ahora."
   → Service creado. Tests siguen verdes. (~5 min)

5. INTERFACE CHANGES (Cápsula 04)
   "Actualiza handler 1 para usar pricing_service. Mantén
    handlers 2 y 3 sin tocar."
   → Tests del handler 1 verdes. Los otros 2 verdes. (~3 min)

6. Repetir paso 5 para handlers 2 y 3, uno a la vez.
   → Tests verdes en cada paso. (~6 min)

7. Cleanup: eliminar las funciones duplicadas viejas
   ahora que nadie las usa. (~3 min)

TOTAL: ~30 minutos. Riesgo de bug: BAJO (tests verdes en cada paso).

6× más rápido. Riesgo de regresión radicalmente menor.

La diferencia no es "Claude Code es más inteligente que un IDE". La diferencia es:

Claude Code lee todos los archivos relevantes antes de cambiar nada (Cápsula 02-03)
Tests de regresión actúan como red de seguridad continua (Cápsula 05)
Cambios incrementales verificados evitan el "todo se rompió al final" (Cápsula 04)
Tú diriges, no aceptas el primer intento (principio del Módulo 5 de la guía #1)

Este módulo te entrena para ejecutar este flujo por defecto — que un refactoring multi-file deje de ser un día de trabajo y se vuelva una hora.

Progresión del Módulo

Mapa del Módulo

Cápsula	Tema	Qué aprenderás
02	Rename y Extract Cross-File	Refactoring fundamentales: renombrar y extraer con actualización automática de references
03	Move Module y Actualización de Imports	Reorganizar la estructura de archivos sin romper imports
04	Interface Changes y Propagación	Modificar interfaces y propagar cambios a todos los consumers
05	Tests de Regresión para Refactoring	El ciclo tests→refactor→verify como regla de oro
06	Proyecto: Refactoring Coordinado	Refactorizar una feature que toca 5+ archivos con tests

Flujo de aprendizaje

Empiezas con los refactoring más simples (rename, extract) que son los más frecuentes. Luego subes a move module, que afecta imports en todo el codebase. Después interface changes, que es el más complejo porque propaga cambios a múltiples implementaciones. La cápsula 05 te da el framework de testing que aplica a todos los anteriores. Y el proyecto final integra todo en un refactoring real de 5+ archivos.

La progresión de complejidad es:

Rename (1 nombre, N archivos)
  → Extract (1 bloque → nuevo módulo, N callers)
    → Move (1 archivo → nueva ubicación, N imports)
      → Interface (1 firma → N implementaciones + N callers)

Conexión con Proyecto

Proyecto de este módulo: Refactoring Coordinado

Vas a recibir (o elegir) un codebase con una feature que necesita refactoring: lógica de negocio mezclada con routing, funciones duplicadas, naming inconsistente, o god objects. Ejecutas refactoring coordinado con Claude Code: escribes tests primero, haces los cambios, y verificas que los tests pasan.

Conexión con el proyecto de la guía

En el Módulo 8 (Proyecto Integrador), el refactoring multi-file es uno de los pasos de la migración completa. El Architecture Map del Módulo 3 identifica qué refactorizar. Este módulo te da las técnicas para ejecutar ese refactoring.

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

❌ Migración de frameworks — Eso es el Módulo 5. Aquí refactorizas dentro del mismo framework.
❌ Rewrite completo — Refactoring preserva comportamiento. Rewrite empieza de cero. Aquí hacemos refactoring.
❌ Diseño de arquitectura — No diseñamos la arquitectura ideal. Mejoramos la existente con cambios incrementales.
❌ Performance optimization — Refactoring mejora estructura, no rendimiento. Optimización es un objetivo diferente.
❌ Testing desde cero — Asumimos que conoces TDD de la guía #7. Aquí aplicamos tests de regresión al refactoring.

El Principio Central

Tests primero, refactoring después.

Este principio no es negociable. Antes de cada refactoring:

Escribe tests que capturan el comportamiento actual
Verifica que los tests pasan
Ejecuta el refactoring
Verifica que los tests siguen pasando
Si pasan: el refactoring fue exitoso
Si fallan: algo se rompió — investiga antes de continuar

Sin tests, ¿cómo sabes que el refactoring no rompió nada? No lo sabes. Y "parece que funciona" no es una verificación profesional.

Trampas a Evitar al Cursar Este Módulo

Cinco malentendidos previsibles. Anticípalos antes de empezar.

1. "Tests son opcionales si el refactoring es simple"

No. La definición de "simple" es retrospectiva: parecía simple hasta que algo se rompió. Tests de regresión son baratos (Claude Code los genera en minutos) y eliminan la categoría completa de "rompí algo y no me di cuenta hasta que el cliente reportó". La regla del módulo es absoluta: tests primero, sin excepciones.

2. "Limpiar todo a la vez es más eficiente"

Lo opuesto. Cada refactoring debe ser incremental y verificable: rename ahora, extract después, move más tarde. Si haces 4 cambios juntos y los tests fallan, no sabes cuál rompió qué. Si los haces uno a la vez con tests entre cada paso, sabes exactamente dónde está el problema. La cápsula 05 desarrolla el ciclo.

3. "Refactoring incluye mejorar la arquitectura"

No en este módulo. Refactoring preserva comportamiento mientras cambia estructura dentro del paradigma actual. Si quieres rediseñar la arquitectura (ej. monolito → microservicios), eso es Módulo 5 (migración) o un proyecto distinto. Mezclar refactoring con rediseño aumenta el riesgo y la opacidad del cambio.

4. "Claude Code va a refactorizar autónomamente"

No. Tú diriges, Claude Code coordina. La diferencia: tú decides qué extraer, qué mover, qué renombrar — Claude Code aplica los cambios en los archivos correctos manteniendo consistencia. Si le delegas la decisión ("limpia esto"), va a tomar decisiones que tú no querías. La guía #1 Módulo 5 te dio el framework — aquí lo aplicas.

5. "Si los tests pasan, el refactoring está perfecto"

Tests verdes son necesario pero no suficiente. También verifica: (1) el diff del cambio es razonable y no incluye sorpresas, (2) la estructura nueva es realmente más clara, (3) no introdujiste duplicación nueva al eliminar la vieja. La cápsula 05 te da el checklist post-refactoring completo.

Diagnóstico: ¿Cuál es tu Punto de Partida?

Cinco preguntas para calibrar antes de empezar.

Pregunta 1: La última vez que renombraste una función usada en 10+ archivos, ¿cómo lo hiciste?

Si dijiste "F2 en mi IDE": funciona para casos simples (mismo lenguaje, mismo proyecto, sin meta-programación). La cápsula 02 te muestra los casos donde el IDE falla y Claude Code resuelve.

Si dijiste "grep + sed": rápido pero peligroso (puede tocar strings y comentarios). La cápsula 02 te enseña el approach correcto.

Pregunta 2: ¿Escribes tests antes de refactorizar, después, o nunca?

Si dijiste "antes": vas bien. La cápsula 05 te da estructura formal para los tests de regresión.

Si dijiste "después" o "nunca": la cápsula 05 es prioritaria. Es el cambio de hábito de mayor leverage del módulo.

Pregunta 3: Cuando mueves un archivo, ¿qué pasa con los imports en el resto del codebase?

Si dijiste "los actualizo a mano / mi IDE los actualiza": depende del IDE y del lenguaje. La cápsula 03 te muestra cómo Claude Code lo hace de forma confiable independiente del setup.

Si dijiste "no he tenido que hacerlo": lo vas a hacer en el proyecto del módulo (5+ archivos involucrados).

Pregunta 4: ¿Has cambiado la firma de una función que tenía 8+ callers? ¿Cómo aseguraste que todos los callers se actualizaron correctamente?

Si tienes un proceso: la cápsula 04 lo formaliza como pattern reutilizable.

Si no: la cápsula 04 te lo enseña. Interface changes son los refactorings de mayor riesgo y este módulo te da una manera segura de ejecutarlos.

Pregunta 5: ¿Puedes distinguir un refactoring de una mejora arquitectural?

Si sí: vas a usar este módulo correctamente (refactoring) y reservar mejoras arquitecturales para Módulo 5 o proyectos dedicados.

Si no: la sección "Límites" arriba es tu punto de partida. La distinción es crítica — mezclarlas duplica el riesgo de cualquier cambio.

Si dudaste en 3 o más: este módulo te llena vacíos críticos para el resto de Phase 2. Si respondiste todas con criterio claro, úsalo como repaso enfocado en la cápsula 04 (interface changes), que suele ser donde más se equivocan los developers experimentados.

Evidencia de Éxito

Antes de avanzar al Módulo 5 (Migración de Frameworks), deberías poder:

✅ Ejecutar un rename que actualiza 10+ references en diferentes archivos sin romper nada
✅ Extraer lógica a un nuevo módulo y que todos los callers sigan funcionando
✅ Mover un archivo y que todos los imports se actualicen correctamente
✅ Cambiar la firma de una función y propagar el cambio a todos los consumers
✅ Escribir tests de regresión antes de cada refactoring por hábito (no por esfuerzo)
✅ Darle a Claude Code una instrucción de refactoring y confiar en que coordina los cambios correctamente
✅ Identificar cuándo un cambio cruza la línea de "refactoring" y se vuelve "rediseño" (Módulo 5)

Si alguno no se cumple al final, regresa a la cápsula correspondiente. El Módulo 5 (migración de frameworks) usa estas técnicas a una escala mayor — sin dominarlas aquí, la migración se vuelve frágil.

Resumen

Este módulo abre Phase 2: Refactoring — de entender a modificar
El foco es refactoring coordinado multi-file usando Claude Code
Los 4 tipos de refactoring: rename, extract, move, interface changes
Tests de regresión son prerequisito obligatorio de todo refactoring
El ciclo tests → refactor → verify es la regla de oro
Claude Code es el coordinador que lee todo el codebase y hace cambios coherentes
El proyecto aplica todo en un refactoring real de 5+ archivos
La diferencia entre "3 horas con riesgo alto" y "30 minutos con riesgo bajo" del escenario inicial es exactamente lo que enseña este módulo

Siguiente cápsula: 02 — Rename y Extract Cross-File — los dos refactorings más frecuentes. Empezamos por aquí porque son la base de los otros: si entiendes cómo Claude Code coordina rename y extract, los demás son extensiones.

Recursos Adicionales

Refactoring: Improving the Design of Existing Code - Martin Fowler - La biblia del refactoring, segunda edición con JavaScript
Working Effectively with Legacy Code - Michael Feathers - Cómo introducir tests en código sin tests para poder refactorizar
Refactoring Guru - Catalog - Catálogo visual de refactorings con antes/después
Claude Code Documentation - Referencia oficial de Claude Code
Python Refactoring Patterns - Patterns específicos para Python
Kent Beck - Test-Driven Development - TDD como fundamento del refactoring seguro

← AnteriorProyecto del Módulo: Architecture Map de Proyecto Real Siguiente →Rename y Extract Refactoring Cross-File