Claude Code y la trampa del contexto: por qué dos llamadas MCP resuelven la arquitectura pero no garantizan la ejecución

La amnesia de Claude Code y el experimento de Bit Cloud: cómo dos llamadas MCP reconstruyen una arquitectura sin archivos locales

Cualquier ingeniero que utilice Claude Code de forma recurrente conoce bien la frustración del inicio en blanco. Al abrir una sesión de trabajo sobre un proyecto creado apenas unos días antes para pedir un cambio puntual, el asistente inteligente se comporta como un recién llegado: comienza explorando el árbol de carpetas a ciegas, intentando averiguar qué servicio controla los datos, qué interfaz de usuario los consume y qué modelo de datos comparten ambos extremos. Las conversaciones anteriores donde se acordó esa estructura ya no existen o quedaron reducidas a un resumen general que omite detalles técnicos críticos.

Hasta ahora, la industria ha intentado resolver este vacío mediante notas de texto. Claude Code carga archivos de instrucciones como CLAUDE.md o AGENTS.md al arrancar, junto con un archivo de notas automáticas que el propio modelo actualiza con correcciones operativas. A esto se sumó la actualización de Claude Projects, diseñada para compartir notas contextuales entre hilos de trabajo paralelos. Sin embargo, estas notas dependen exclusivamente de lo que un humano o un resumen automático deciden registrar. Si alguien olvida anotar que la versión de un contrato cambió el martes, el asistente trabajará con premisas obsoletas.

Para comprobar si existía una alternativa más sólida, un equipo de ingenieros de Bit Cloud sometió a prueba a Claude Code bajo condiciones extremas: una terminal completamente vacía, sin historial de conversación previo, sin código descargado en local y con una única instrucción de alto nivel para añadir una función de filtrado a una consola de soporte existente. La consola contaba con cuatro piezas en producción: una interfaz en React, una API en Express con base de datos MongoDB, una entidad de datos compartida para los tiques y una puerta de enlace de plataforma.

En lugar de rastrear archivos inexistentes, Claude Code utilizó el protocolo Model Context Protocol (MCP) para consultar el registro del sistema de compilación de Bit Cloud. Con solo dos operaciones (read_scope y read_components), el agente recibió la lista completa de componentes, sus dependencias exactas y la documentación de las interfaces. Al leer que la entidad de tiques estaba catalogada como compartida entre la API y la aplicación web, el modelo comprendió qué podía modificar y qué debía dejar intacto. Descargó el código, programó el filtro del lado del cliente y superó 41 pruebas automatizadas sin tocar una sola línea del backend.

Memoria de texto frente a registros de compilación: comparativa técnica entre CLAUDE.md y grafos de dependencias

El debate central que plantea este experimento no es si la inteligencia artificial sabe escribir código, sino de dónde debe extraer la verdad sobre el sistema. Las herramientas habituales de desarrollo asistido, como Cursor o Claude Code en su configuración estándar, confían en archivos markdown locales (CLAUDE.md) para orientarse. El problema de los archivos de texto libre es su desvinculación respecto al ciclo de compilación: reflejan lo que un desarrollador creyó relevante en un momento dado, pero no garantizan correspondencia con la versión real del software.

Por el contrario, cuando un sistema de compilación genera un componente modular, registra de forma automática sus dependencias directas e indirectas como parte de su manifiesto inmutable. Si la interfaz de usuario utiliza la versión 1.2.0 de una entidad de datos y el servicio backend utiliza la misma versión, esa relación queda grabada en el registro de paquetes. El agente no necesita deducir la arquitectura leyendo miles de líneas de código fuente; simplemente lee el grafo de dependencias generado por el compilador.

Comparativa técnica entre documentación declarativa tradicional y registros de empaquetado para asistentes de desarrollo.

En términos de coste y velocidad, la diferencia es sustancial. En una simulación estándar sobre un repositorio mediano con 50 componentes, un agente que recurre al escaneo ciego de archivos locales consume entre 15.000 y 45.000 tokens solo para ubicar qué módulos interactúan entre sí. Con una tasa de inferencia típica en modelos avanzados de primera línea, cada reinicio de sesión representa entre 0,05 y 0,15 dólares de gasto improductivo antes de escribir la primera línea de código.

Mediante las consultas MCP read_scope y read_components, el consumo inicial se desploma a unas 3.200 unidades de contexto. El modelo recibe únicamente la carga útil necesaria: nombres de artefactos, árboles de dependencias y contratos exportados. Esto elimina el ruido de bibliotecas de terceros y archivos de configuración auxiliares.

El impacto en la ingeniería de software: consumo de tokens, prevención de roturas y deuda invisible

Trasladar la carga del contexto desde la memoria textual hacia registros estructurados altera profundamente tres variables operativas en los equipos de desarrollo: el gasto continuo en modelos, el tiempo de entrega de cambios puntuales y la estabilidad estructural de los servicios compartidos.

Reducción del gasto operativo (OPEX) y ahorro de tokens por sesión

En organizaciones donde decenas de desarrolladores interactúan a diario con asistentes en la terminal, el tiempo que el modelo pasa explorando directorios locales se traduce directamente en factura de computación. Un equipo de 20 ingenieros que inicie un promedio de cuatro sesiones diarias por persona realiza unas 80 sesiones de contexto al día.

Si cada sesión gasta 30.000 tokens en redescubrir la topología de la aplicación, el equipo desecha 2,4 millones de tokens diarios en tareas de orientación redundante. Al sustituir esa exploración por llamadas estructuradas a registros de empaquetado vía MCP, el consumo se reduce a menos de 300.000 tokens diarios. Esto representa un recorte del 87% en el volumen de contexto inicial desperdiciado, permitiendo reservar la ventana de contexto para el código que realmente requiere análisis lógico y pruebas unitarias.

Reducción de los tiempos de entrega (Lead Time) al eliminar la fase de exploración a ciegas

El tiempo de espera del programador frente a la consola suele pasar desapercibido en las métricas convencionales. Cuando un agente ejecuta comandos como find, grep o inspecciones recursivas de carpetas, el desarrollador espera entre 90 y 180 segundos mientras la herramienta recopila archivos dispersos.

Al operar con un registro centralizado de dependencias, Claude Code tardó apenas dos intercambios de red en saber exactamente qué componentes formaban la consola de soporte. En lugar de navegar durante minutos por la jerarquía de directorios, el agente ejecutó la descarga directa mediante bit import del paquete concreto que requería modificaciones. La fase previa a la edición del código se redujo a menos de 20 segundos, permitiendo ciclos de iteración mucho más ágiles en correcciones de interfaz y ajustes de lógica interna.

Estabilidad del sistema y blindaje contra cambios destructivos en contratos compartidos

El mayor riesgo de delegar tareas en agentes autónomos dentro de arquitecturas distribuidas es la modificación involuntaria de contratos compartidos. Si un desarrollador pide “añade un campo de prioridad a los tiques”, un agente que solo ve el código local suele modificar el esquema de datos en el cliente sin percatarse de que el servicio backend espera una estructura diferente, rompiendo la serialización en producción.

En la prueba de Bit Cloud, el registro de compilación indicó explícitamente que la entidad Ticket estaba compartida entre el servicio Express y la interfaz de React. Gracias a ese dato objetivo, Claude Code tomó una decisión de diseño crítica: no tocó la entidad común ni intentó modificar los extremos de la API, sino que implementó el filtrado exclusivamente en memoria dentro del componente de React. Saber con certeza qué partes del sistema están acopladas proporciona al modelo una regla de contención clara sobre qué zonas del código no debe tocar.

Dónde se agota el registro inmutable: la brecha entre la arquitectura estática y el comportamiento en tiempo de ejecución

A pesar del éxito inicial en la importación y modificación de los componentes, el experimento reveló una frontera técnica evidente: los registros de compilación proporcionan una imagen perfecta de las dependencias estáticas, pero quedan ciegos ante el comportamiento dinámico del software en ejecución.

La frase que resume el límite del sistema es directa: los registros se terminaron cuando llegó la hora de validar el comportamiento. La interfaz de usuario listaba en su documentación interna de pruebas una serie de rutas HTTP (GET /tickets, POST /tickets, PATCH /tickets/:id), pero esas rutas correspondían a un servidor simulado (mock) utilizado para pruebas unitarias. Ningún registro del sistema de paquetes comprobaba si la API real en Express seguía respondiendo a esas mismas rutas con los mismos encabezados y códigos de estado.

El segundo fallo crítico apareció en las pruebas automatizadas. El informe de integración marcó un resultado en verde con 41 pruebas superadas. Sin embargo, una revisión manual evidenció que las pruebas de persistencia con MongoDB se habían omitido silenciosamente porque el contenedor de base de datos temporal no pudo iniciarse en el entorno de ejecución continua. El código parecía válido, pero no se había comprobado la escritura real en disco.

La persistencia tuvo que auditarse a mano: crear un tique en la aplicación, añadir un comentario, reiniciar el servicio contra la base de datos real y comprobar que los datos permanecían intactos. Aspectos esenciales de la ingeniería de software como el control de concurrencia, las migraciones de esquemas, los planes de contingencia y la monitorización de infraestructura en plataformas como Datadog siguen dependiendo enteramente del criterio humano. Los registros estáticos resuelven la topología del código, pero no reemplazan la validación en tiempo de ejecución.

Veredicto de implementación: qué equipos deben conectar agentes a registros MCP y quiénes deben esperar

La combinación de Claude Code con protocolos MCP conectados a sistemas de compilación modular no es una solución universal para cualquier proyecto de software. Su rendimiento varía drásticamente según la arquitectura del repositorio y el nivel de madurez operativa de la organización.

Cuándo adoptar registros de dependencias vía MCP (Condiciones de idoneidad)

• Arquitecturas modulares con paquetes versionados de forma independiente: Si la organización gestiona aplicaciones compuestas por librerías internas, entidades compartidas y microservicios con versiones semánticas (mediante herramientas como Bit, Turborepo o registros privados de npm), la exposición de estos metadatos a través de un servidor MCP elimina por completo la amnesia del agente entre sesiones.
• Equipos con alta rotación en repositorios transversales: En proyectos donde los desarrolladores entran y salen de módulos que no crearon, los agentes conectados al registro de paquetes identifican al instante qué piezas son compartidas y qué piezas son locales, reduciendo drásticamente los incidentes causados por modificaciones no coordinadas.
• Operaciones con restricciones estrictas de presupuesto de contexto: Empresas que monitorizan el gasto de tokens y buscan optimizar la ventana de inferencia deben suprimir el rastreo de archivos por fuerza bruta y sustituirlo por endpoints estructurados de descubrimiento arquitectónico.

Cuándo mantener el modelo tradicional de documentación manual (Riesgos operativos)

• Monolitos fuertemente acoplados: En aplicaciones donde el código de la interfaz y la lógica de base de datos residen en la misma base de código sin límites de empaquetado claros, un servidor de registros de compilación no tiene información modular que ofrecer. En estos casos, un archivo CLAUDE.md bien estructurado sigue siendo más efectivo para explicar las peculiaridades del sistema.
• Sistemas que dependen de decisiones de negocio no codificadas: Los registros de paquetes indican qué versión depende de qué entidad, pero no pueden explicar por qué se decidió descartar una función específica el mes anterior o qué directiva de cumplimiento normativo obligó a cambiar un flujo de autenticación. Esa memoria histórica pertenece a las notas documentales redactadas por personas.
• Equipos sin infraestructura de pruebas en tiempo de ejecución: Si una organización confía ciegamente en que un asistente compile en verde sin contar con entornos de prueba que levanten dependencias reales (bases de datos, pasarelas de pago, colas de mensajería), el uso de registros modulares puede generar una falsa sensación de seguridad. La certeza sobre el contrato estático jamás debe confundirse con el correcto funcionamiento del software bajo tráfico real.