Deja de Inflar tu CLAUDE.md: Así se Elimina el Context Drift

TL;DR: El context drift, la degradación progresiva de calidad en sesiones largas de Claude Code, no se soluciona con un CLAUDE.md de 300 líneas. La clave es compactar al 60% de contexto (no al 95%), usar instrucciones de preservación en cada /compact, y combinar tres capas de memoria: CLAUDE.md, Auto Memory y Session Memory. Menos instrucciones permanentes, más gestión activa.

¿Qué es el context drift y por qué arruina tus sesiones?

Context drift es la pérdida gradual de precisión y coherencia que sufre un coding agent conforme su ventana de contexto se llena de información obsoleta, redundante o contradictoria. No es un bug. Es una consecuencia directa de cómo funcionan los transformers.

Las señales son predecibles: Claude empieza a sugerir enfoques que ya descartaste, repite preguntas que contestaste hace media hora, o genera código que contradice decisiones arquitectónicas del inicio de la sesión. Si has trabajado más de dos horas seguidas en Claude Code, lo has experimentado.

El mecanismo es directo. Los modelos calculan pesos de atención entre todos los tokens del contexto. A medida que la ventana crece, cada token recibe menos atención relativa. Los tokens del inicio de la conversación, donde están tus decisiones fundamentales, compiten con cientos de resultados de grep, diffs y errores de compilación. La señal se diluye en el ruido. Un estudio técnico de Chroma lo documenta: el rendimiento de recuperación de contexto se degrada con cada token nuevo que se introduce.

Tu CLAUDE.md no es un seguro contra el context drift

El primer instinto de todo desarrollador es meter más instrucciones en CLAUDE.md. Si Claude olvida la arquitectura, añades una sección. Si ignora las convenciones de naming, otra más. El archivo crece hasta las 200, 300, 400 líneas.

Esto es contraproducente. Un estudio de ETH Zürich encontró que los archivos de contexto inflados sin criterio reducen la tasa de éxito en tareas entre un 0,5% y un 2%, mientras incrementan los costes de inferencia más de un 20%. Más reglas no producen mejor rendimiento.

CLAUDE.md tiene una propiedad crítica: sobrevive a toda compactación. Después de cada /compact, Claude Code relee el archivo desde disco y lo reinyecta fresco en la sesión. Nada de lo que escribas ahí se pierde. Pero precisamente por eso, cada línea consume tokens en cada sesión, desde el primer mensaje. Un CLAUDE.md de 400 líneas puede estar quemando el 15% de tu ventana de contexto antes de que escribas nada. Puedes verificarlo tú mismo con el comando /context.

El principio que funciona se llama progressive disclosure: no le digas a Claude todo lo que podría necesitar. Dile cómo encontrar la información cuando la necesite. En vez de documentar 50 endpoints, indica dónde está el archivo de rutas.

Las tres capas de memoria en Claude Code

Claude Code tiene tres sistemas de memoria distintos. Entender cuándo usar cada uno es la diferencia entre sesiones productivas y sesiones que se degradan a la hora y media.

Capa	Quién escribe	Cuándo se carga	Sobrevive compactación
CLAUDE.md	Tú	Inicio de sesión	Sí (relee de disco)
Auto Memory	Claude	Inicio de sesión	Sí (archivos en disco)
Session Memory	Claude (background)	Al compactar	Sí (resúmenes pre-calculados)

CLAUDE.md es para instrucciones que aplican a todo el proyecto: comandos de build, estándares de código, decisiones arquitectónicas irrevocables. Tú lo escribes y mantienes.

Auto Memory (disponible desde v2.1.59) son notas que Claude escribe para sí mismo: patrones detectados, preferencias de workflow, insights de debugging. Se almacenan en ~/.claude/projects/<proyecto>/memory/ y su índice MEMORY.md no debe superar las 200 líneas. Cuando se acumulan demasiadas notas, Claude las reorganiza en archivos temáticos como debugging.md o patterns.md.

Session Memory funciona en segundo plano. Cada ~5.000 tokens o 3 tool calls, Claude extrae un resumen incremental de la conversación. Cuando ejecutas /compact, en vez de reanalizar toda la conversación (lo que antes tardaba hasta dos minutos), carga el resumen pre-calculado. Compactación instantánea. Disponible en Claude Pro y Max, no en Bedrock ni Vertex.

Workflow práctico: compacta antes, no después

El error más común es esperar a que la auto-compactación salte al ~83% de capacidad (o al 95% en configuraciones anteriores). A ese punto, Claude ya trabaja con contexto degradado y el resumen será peor. La regla: compacta al 60%. Algunos desarrolladores establecen una regla temporal: compactar cada 45-60 minutos en sesiones complejas, independientemente del porcentaje.

Monitoriza el porcentaje en la barra inferior de la terminal. Si se acerca al 60% y estás en medio de algo complejo, actúa. Usa /context para ver qué está consumiendo espacio.
Compacta con instrucciones de preservación. No uses /compact a secas.

# Preserva decisiones de arquitectura y estado actual
/compact Preservar: decisiones en src/routes/, archivos modificados,
  tests que fallan, y la decisión de usar PostgreSQL

Verifica después de compactar. Envía: "Resume dónde estamos y qué queda por hacer". Si algo se perdió, lo recuperas de inmediato mientras está fresco.
Usa /clear entre tareas no relacionadas. Si terminas un feature y empiezas otro, /clear es más limpio. Como explicamos en el artículo sobre reducir el consumo de tokens en agentes de código, cada token innecesario es coste y rendimiento que se pierde.
Usa /btw para preguntas rápidas. Si necesitas consultar algo sin contaminar el contexto, /btw muestra la respuesta en un overlay que no entra en el historial de conversación.

Para compactación parcial, Esc + Esc o /rewind te permiten seleccionar un punto de la conversación y compactar solo desde ahí. Esto preserva el contexto anterior intacto mientras libera tokens de una fase de debugging larga.

CLAUDE.md lean: menos es más

Si aplicas el principio que comentamos en AI Fatigue: menos herramientas, mejor código, la conclusión es clara: un CLAUDE.md de 80 líneas bien curado supera a uno de 400 copiado de un template.

Qué debe estar:

Comandos de build y test (exactos, copy-paste)
Decisiones arquitectónicas no derivables del código
Convenciones que el linter no cubre
Instrucciones de compactación personalizadas

Qué no debe estar:

Documentación de API (referencia al archivo, no copies el contenido)
Listas de endpoints, modelos o schemas completos
Histórico de decisiones (eso va en commits o ADRs)
Reglas que un linter o formatter aplica automáticamente

Puedes personalizar el comportamiento de compactación dentro del propio CLAUDE.md:

## Compact Instructions
Al compactar, preservar siempre:
- Lista de archivos modificados en esta sesión
- Tests que fallan y por qué
- Decisiones arquitectónicas de la conversación

Para auditar si tu CLAUDE.md se ha quedado obsoleto, context-drift es una CLI que detecta rutas muertas, scripts inexistentes y versiones desactualizadas en tus archivos de contexto:

npm install -g @geekiyer/context-drift
context-drift scan

En Producción

Subagentes protegen tu contexto principal. Cada subagente trabaja en su propia ventana de contexto. Si necesitas explorar 15 archivos o investigar un bug, delega. El resultado vuelve como un resumen limpio, sin contaminar tu conversación. El mismo principio que aplicamos al seleccionar qué servidores MCP mantener activos: lo que no necesitas en contexto, no lo cargues.

Proyectos multi-día necesitan memoria estructurada. No empieces sesiones con "implementa X" a menos que la tarea sea trivial. Empieza con orientación: pide a Claude que inspeccione los archivos relevantes, resuma la arquitectura e identifique riesgos. Actualiza el log de progreso antes de cerrar cada sesión para que la siguiente tenga un punto de partida fiable.

La ventana de 1M tokens no elimina el problema. Anthropic expandió la ventana a un millón de tokens para Opus 4.6 y Sonnet 4.6 (GA, sin beta headers). Jon Bell, CPO de Anthropic, reportó una reducción del 15% en eventos de compactación. Pero la dilución de atención sigue existiendo. Un CLAUDE.md inflado sigue siendo un problema en una ventana de 1M, solo que tarda más en notarse.

Context collapse (en desarrollo). El análisis del código fuente filtrado de Claude Code revela una feature interna llamada "marble_origami": comprime resultados de herramientas verbose de turnos anteriores sin activar una compactación completa. Si un grep devolvió 500 líneas hace 5 turnos, se colapsa a una representación corta. Es una optimización que complementa, no reemplaza, la compactación manual.

Costes. Una sesión larga sin compactación estratégica genera respuestas de menor calidad y más reintentos. Si estás en Claude Max con límites en hora punta, cada token cuenta el doble. Compactar al 60% no solo mejora la calidad: reduce el consumo real por sesión.

Errores comunes y cómo solucionarlos

Error: Claude repite enfoques ya descartados.
Causa: La compactación automática comprimió la conversación y eliminó el razonamiento de por qué se descartaron.
Solución: Compacta manualmente antes del 60% incluyendo decisiones descartadas: /compact Preservar: descartamos Redis por latencia, usamos PostgreSQL.

Error: Después de compactar, Claude no sabe en qué archivos trabajabas.
Causa: No incluiste instrucciones de preservación en el /compact.
Solución: Incluye siempre la lista de archivos: /compact Preservar archivos: src/routes/auth.ts, src/middleware/jwt.ts.

Error: CLAUDE.md supera las 300 líneas y Claude ignora instrucciones del final.
Causa: A partir de ~200 líneas, la adherencia disminuye. El modelo prioriza el inicio del contexto.
Solución: Mueve el detalle a .claude/rules/ o usa imports con @path. Mantén CLAUDE.md por debajo de 150 líneas.

Preguntas frecuentes

¿Cuál es la diferencia entre /compact y /clear?

/compact resume la conversación y usa ese resumen como nuevo punto de partida, preservando el hilo de trabajo. /clear borra todo el historial y empieza de cero. Usa /compact para continuar una tarea y /clear cuando cambias de tema.

¿Session Memory funciona con todos los proveedores?

No. Session Memory solo está disponible en la API de primera parte de Anthropic (planes Claude Pro y Max). Si usas Claude Code a través de Bedrock, Vertex o Foundry, no tendrás compactación instantánea ni resúmenes pre-calculados en segundo plano.

¿Cómo sé cuándo mi CLAUDE.md es demasiado largo?

Ejecuta /context en tu sesión. Muestra exactamente cuántos tokens consume cada componente: system prompt, herramientas, archivos de memoria y conversación. Si tus archivos de memoria ocupan más del 15% de la ventana antes de empezar a trabajar, necesitas recortar.

El context drift no es un problema de modelo, es un problema de workflow. Compactar a tiempo, mantener un CLAUDE.md ligero y aprovechar las tres capas de memoria convierte sesiones que se degradan a las dos horas en sesiones productivas de cuatro o más. La herramienta ya tiene los mecanismos. Solo falta usarlos con intención.

¿Has probado alguna estrategia contra el context drift? Cuéntamelo en Twitter @sergiomarquezp_ o en los comentarios.