Por qué Claude falla en legacy (la técnica de los 5 archivos de señal)

Abrís un monolito de 3 años en Claude, pegás 40 archivos y el modelo te devuelve un refactor genérico que ignora los edge cases más importantes del sistema. No es un problema del modelo. Es un problema de lo que le pasaste.

Los 5 archivos de señal

No es un número mágico; es un límite que fuerza la decisión correcta. Qué archivos necesita el modelo para razonar sobre este refactor específico:

1. El archivo que querés refactorizar
2. Sus imports directos (no los transitivos)
3. El archivo de tipos que lo afecta
4. Un test representativo, si existe
5. Un CONTEXT.md escrito por vos

El punto 2 es donde más se equivoca la gente. Los imports transitivos traen consigo utilidades, helpers y módulos que no tienen nada que ver con el refactor; Claude los usa igual para "entender el sistema" y termina sugiriendo cambios que acoplan lo que querías desacoplar.

El CONTEXT.md es lo que más separa una sesión AIDD senior de una amateur. El modelo no sabe por qué ese código existe; vos sí:

## Contexto: payment-gateway.ts

**Qué hace:** Procesa pagos via Bancard vPOS y gestiona el estado de las órdenes.

**Restricciones que no se pueden romper:**

- El bloque `legacyId === 999` compensa un error de redondeo en PYG para cuentas corporativas. No borrar.
- La función debe ser idempotente; los webhooks de Bancard pueden llegar duplicados.

**Objetivo del refactor:** Extraer la lógica de validación a una función pura y testeable, sin tocar la integración con Bancard.

Con este contexto antes del código, el modelo entiende el sistema: sabe qué no puede tocar, hacia dónde tiene que ir y por qué ese bloque raro del legacyId no es un bug sino una decisión deliberada. Sin él, optimiza archivos individuales y te propone exactamente el refactor que rompe producción—olvidando a veces cómo manejar pagos indestructibles con Algebraic Data Types.

El flujo en Claude Code

# Empezá la sesión con el contexto, no con el código
/read CONTEXT.md
/read src/payment-gateway.ts
/read src/types/payment.ts
/read src/payment-gateway.test.ts

El trade-off

Si el refactor cruza más de 3 módulos interdependientes, esta técnica sola no alcanza. La señal de qué es importante se fragmenta entre sesiones y el modelo pierde el hilo de las restricciones que definiste en el CONTEXT.md. Ahí dividís el trabajo en sesiones por módulo, cada una con su propio CONTEXT.md, o usás un subagente por contexto si el tooling lo permite.

El indicador práctico: si para describir el objetivo del refactor necesitás más de 5 oraciones en el CONTEXT.md, el scope es demasiado grande para una sola sesión.

El mismo criterio aplica si usás IA para generar tests: cuanto más señal y menos ruido en el contexto inicial, mejor resultado. Ver cómo genero tests E2E con IA.