Por qué Claude Code vuelve a leer todo el proyecto y cómo solucionarlo

Documentación de Ailoot: API, claves y conexión.

¿Por qué Claude Code vuelve a leer el proyecto desde cero cada vez?#

Mucha gente piensa que es un error. En realidad, Claude Code está diseñado así: no tiene un índice propio del proyecto. Cuando le pides que arregle algo, no dispone de un mapa del código preparado; vuelve a explorar el proyecto: encuentra los archivos pertinentes, busca las cadenas necesarias y carga los archivos en memoria.

Este enfoque tiene ventajas reales. El código siempre está actualizado: no hay un índice que haya quedado obsoleto. No hay nada que configurar. Tu código no se envía a ninguna base de datos.

Pero también tiene una desventaja: cada tarea nueva implica otra ronda de búsqueda y lectura de archivos. Se gastan tokens en volver a averiguar dónde está cada cosa, aunque Claude ya lo hubiera descubierto en la sesión anterior. Cuanto más grande es el proyecto, más cuesta este reconocimiento. Este mecanismo es precisamente lo que puede dar la sensación de que el agente «lo está leyendo todo».

¿Cuántos tokens consume realmente?#

El coste empieza antes de tu solicitud. Una medición independiente lo muestra con sencillez: Claude Code envía unos 33.000 tokens de prompt del sistema y descripciones de herramientas antes de leer el primer carácter de tu mensaje. Como comparación, OpenCode empieza con unos 7.000.

Después entra en juego la relectura. Cada búsqueda y lectura de archivos añade tokens al contexto. La documentación oficial de Claude Code lo dice claramente: leer archivos domina el uso del contexto. Analizar auth.ts, que tiene 2.400 tokens, significa que Claude ha visto esos 2.400 tokens solo en ese archivo; lo mismo ocurre con cada archivo que abre durante el reconocimiento.

Para nuestro público, esto se traduce en dinero y límites. El mayor temor de quienes empiezan con el vibe coding es: «He pagado y se me han agotado los límites para nada». Si el agente explora el proyecto y vuelve a leer los archivos desde cero en cada tarea, el contexto se consume el doble de rápido: primero por la carga del sistema y luego por el reconocimiento. En la guía «Adónde van los tokens de Claude Code» expliqué en detalle dónde se gastan exactamente: volver a leer el proyecto es uno de los nueve patrones que se describen allí.

¿Qué es la memoria persistente de código?#

La memoria de código resuelve justo la carencia que hace que Claude vuelva a leer el proyecto. La idea es sencilla: que algo analice todo el código una vez, cree un mapa y lo tenga a mano. Así, el agente no necesita buscar desde cero cada vez: consulta el mapa.

Técnicamente, funciona así. Una herramienta independiente analiza el proyecto y lo descompone en componentes: qué funciones y clases existen, quién llama a quién y qué archivos están relacionados. Esta estructura se guarda en el disco. Cuando Claude necesita saber dónde está la lógica de pagos o qué se rompería si se modifica una función, hace una consulta específica al mapa en vez de leer docenas de archivos.

Este mapa se conecta mediante MCP, el método estándar para incorporar una herramienta externa a Claude Code (expliqué cómo conectar otros servidores en la guía «Servidores MCP para Claude Code»). La herramienta de memoria de código añade sus propios comandos para buscar en el mapa y Claude los usa por iniciativa propia cuando necesita orientarse en el proyecto.

En la práctica, la diferencia está entre «leer toda la carpeta para encontrar una función» y «preguntarle al mapa dónde está esa función». Lo primero cuesta decenas de miles de tokens; lo segundo, cientos.

Dos enfoques para la memoria de código: ¿en qué se diferencian?#

Las herramientas de memoria de código se diferencian por lo que construyen a partir de tu proyecto. La forma más sencilla de entenderlas es esta: una le da al agente manos de cirujano para hacer cambios y la otra busca por significado.

El número de estrellas de GitHub corresponde al 15 de julio de 2026 (según la API de GitHub). Las dos herramientas son gratuitas y de código abierto, funcionan con Claude Code y se conectan como servidores MCP.

En resumen, para quienes no programan: Serena ofrece precisión quirúrgica: úsala cuando modifiques la misma parte por todo el proyecto y la precisión sea importante. claude-context busca por significado: encuentra código a partir de una descripción, pero requiere configurar una base de datos en la nube y usar una clave.

¿Cuándo elegir Serena o claude-context?#

Las dos herramientas no compiten por un único premio. Recuerdan cosas distintas, así que la elección depende de la tarea.

Elige Serena si haces mucha refactorización. Le ofrece al agente navegación por el código como la de un entorno de desarrollo inteligente: encuentra la definición de una función y todos sus sitios de llamada reales, y luego cambia cuidadosamente el nombre de la función o sustituye su cuerpo por todo el proyecto. El autor describe así su ventaja.

Serena no publica un porcentaje exacto de ahorro y no le atribuiré una cifra inventada. Su ventaja es distinta: mientras que una búsqueda normal devuelve cuarenta coincidencias, incluidos comentarios y cadenas, tras lo cual Claude lee cuatro archivos enteros, Serena responde con unas pocas consultas precisas. Eso significa menos llamadas y menos coincidencias falsas y, por tanto, menos riesgo de que el agente edite algo que no debe.

Elige claude-context si necesitas buscar por significado y no te desanima la configuración. Convierte el código en vectores (huellas numéricas del significado) y busca a partir de una descripción: «encuentra dónde está nuestra lógica de pagos», aunque no conozcas los nombres de las funciones. El coste de esta búsqueda es la configuración adicional.

claude-context requiere una base de datos vectorial externa, una clave de un proveedor de embeddings y una versión reciente de Node. De las dos herramientas, es la más laboriosa de configurar, así que recomiendo a quienes empiezan que prueben otra primero.

¿Qué puedes hacer directamente en Claude Code sin herramientas de terceros?#

Antes de instalar herramientas de terceros, aprovecha al máximo lo que Claude Code ya incluye. Estos comandos son gratuitos y funcionan nada más empezar.

1. /context — muestra en tiempo real qué ocupa la ventana: prompt del sistema, CLAUDE.md, memoria, herramientas y archivos. El comando /mcp muestra el coste de cada servidor conectado, y /memory indica qué se cargó al iniciar.
2. /compact — comprime el historial de la conversación en un resumen breve y continúa con la misma tarea. Puedes orientar el resumen añadiendo a /compact lo que quieres conservar.
3. /clear — descarta todo el historial. La recomendación oficial es ejecutarlo al cambiar a una tarea no relacionada, para que la conversación anterior no ocupe el espacio de los archivos que necesitas.
4. /doctor (también conocido como /checkup, introducido el 8 de julio de 2026) — diagnostica la configuración y sugiere soluciones: elimina duplicados en CLAUDE.md, encuentra herramientas y servidores sin usar y detecta controladores lentos.

Una nota aparte sobre CLAUDE.md. Este archivo se carga en el contexto al inicio de cada sesión y se incluye en todos los mensajes. Si es demasiado largo, sigues pagando por él. La recomendación oficial es mantenerlo por debajo de 200 líneas y trasladar los detalles de referencia a skills que se cargan cuando hacen falta. En la guía independiente «Cómo configurar CLAUDE.md» expliqué cómo prepararlo correctamente.

Otra herramienta integrada son los subagentes. Tienen su propio contexto independiente, así que puedes delegarles lecturas extensas y tareas de reconocimiento sin llenar tu ventana principal. En su análisis de ingeniería, Anthropic expresa así el principio general.

¿Un servidor MCP adicional hará que el contexto sea aún mayor?#

Antes era cierto que «un servidor más significa más sobrecarga de contexto», pero Claude Code ha cambiado. Ahora las descripciones de las herramientas MCP se aplazan de forma predeterminada: al inicio solo se incluyen en el contexto los nombres de los servidores y las descripciones completas se cargan cuando se necesita una herramienta concreta para la tarea. La documentación lo explica directamente.

La cuenta de la memoria de código es sencilla: una sobrecarga pequeña y fija por los nombres de las herramientas frente a miles de tokens ahorrados porque el agente deja de volver a leer archivos. El balance favorece claramente al índice.

Un par de salvedades honestas para que no esperes milagros. Hay que reconstruir el índice de vez en cuando: el mapa refleja el código tal como estaba en el momento del análisis y debe actualizarse después de cambios importantes (esto depende de la herramienta: algunas lo hacen automáticamente y otras requieren un comando). Además, afirmaciones como «120 veces menos tokens» describen el mejor caso en consultas seleccionadas, no lo que verás en todas las tareas. El ahorro real es más modesto, pero sigue siendo apreciable. Si quieres profundizar en cómo evitar quedarte sin límites en general, tengo un análisis independiente: «Cómo evitar agotar los límites de Claude Code».

¿Por dónde empezar hoy?#

Si eliminas todo lo innecesario, el plan para hoy es sencillo:

1. Ejecuta /doctor y limpia lo que sugiera: duplicados en CLAUDE.md y herramientas sin usar.
2. Reduce CLAUDE.md a 200 líneas y traslada el material de referencia a skills.

Después, elige según tus necesidades: si haces mucha refactorización, añade Serena para realizar cambios precisos; si necesitas buscar por significado, configura claude-context. La memoria de código y un contexto limpio resuelven hoy el problema principal.

Si necesitas acceder a modelos de IA a través de Ailoot, visita Ailoot.