[Contexto de IA #4] Por qué CLAUDE.md debe ser breve

En la tercera parte vimos cómo borrar el historial con /clear. Sin embargo, al comprobar el contexto restante justo después, no aparece al 100 %. Ejecuta /context en Claude Code y la razón queda clara. El prompt del sistema, las definiciones de herramientas, CLAUDE.md y las herramientas registradas por los servidores MCP ya consumen decenas de miles de tokens. Antes incluso de que empiece la conversación.

Esta parte trata el “contexto cargado permanentemente”. Si el historial de conversación es un coste variable, este es un coste fijo. Se incluye en todos los turnos, no desaparece con /clear y ocupa parte de la atención del modelo durante toda la sesión. Un diseño deficiente del coste fijo hace que cualquier sesión empiece en desventaja, por lo que conviene corregirlo antes que la gestión de la conversación.

Lo que ya está cargado antes de iniciar la sesión

La ventana de contexto de un agente no empieza como una página en blanco. Varias capas ya están colocadas antes de que llegue la primera entrada del usuario.

Abajo está el prompt del sistema. Contiene las instrucciones base que instala el arnés del agente—un entorno de ejecución como Claude Code—, incluidas las reglas de uso de herramientas y formato de respuesta, con miles de tokens. El usuario no puede modificar esta zona.

Encima se cargan las definiciones de herramientas. Para usar una herramienta, el modelo necesita conocer su nombre, descripción y esquema de parámetros, y todo entra en el contexto como texto. La carga no es grande con las herramientas básicas, pero cambia al conectar servidores MCP. Es habitual que un solo servidor registre decenas de herramientas, y unos pocos servidores pueden consumir decenas de miles de tokens solo en definiciones. Las herramientas que nunca usas hacen el viaje de ida y vuelta en cada turno.

La última capa son los archivos de instrucciones del proyecto, como CLAUDE.md. La configuración global, la del proyecto y la de los subdirectorios se cargan automáticamente, y esta es la única capa que el usuario puede diseñar directamente.

Principio de CLAUDE.md: breve y solo con verdades permanentes

Solo hay un criterio para decidir qué incluir en CLAUDE.md: “¿Esto es siempre cierto para todas las tareas de este proyecto?” Como el archivo se incluye en cada turno y tarea, el contenido relevante para unas tareas pero irrelevante para otras no justifica su espacio.

Los comandos de compilación y pruebas, la estructura general del código y unas pocas reglas que no se pueden infringir superan el criterio. En cambio, las especificaciones detalladas de una función concreta, la documentación completa de una biblioteca y el historial de trabajos anteriores solo hacen falta para tareas específicas, así que quedan fuera.

La longitud encierra una paradoja. Puede parecer que escribir más instrucciones mejora el cumplimiento, pero en la práctica ocurre casi lo contrario. Como vimos en la segunda parte, un contexto más largo diluye la atención dedicada a cada elemento y, en un archivo de instrucciones de cientos de líneas, las reglas importantes quedan enterradas en el lost in the middle. Con 50 reglas, las 50 se cumplen de forma difusa; con 10, esas 10 se cumplen con claridad. Si el agente incumple continuamente las reglas de CLAUDE.md, quizá el orden correcto sea acortar el archivo antes de añadir más reglas.

No lo cargues todo; carga solo punteros

Entonces, ¿dónde deben ir los documentos detallados que no superaron el criterio, es decir, los que solo hacen falta ocasionalmente? La respuesta es: “déjalos fuera del contexto e indica únicamente su ubicación”.

En vez de incluir en CLAUDE.md todo el procedimiento de migración de la base de datos, escribe una línea: “Consulta docs/migration.md para el procedimiento de migración”. El agente lee ese archivo solo al realizar una migración. El contenido detallado entra en el contexto únicamente en las sesiones que lo necesitan; las demás solo pagan el coste de un puntero de una línea.

El skill de Claude Code sistematiza el mismo principio. Un skill es un procedimiento para una tarea concreta; normalmente, en el contexto solo aparecen su nombre y una descripción de una línea, y el cuerpo se carga cuando comienza esa tarea. Si conviertes el “procedimiento de despliegue” en un skill en lugar de mantenerlo residente en CLAUDE.md, ahorras esos tokens en el 99 % de los turnos que no implican despliegues.

Las herramientas también necesitan depuración. Si hay un servidor MCP conectado pero sin uso, desactivarlo elimina decenas de miles de tokens de coste fijo. Cada vez más arneses admiten carga diferida: normalmente conservan solo los nombres de las herramientas y cargan los esquemas completos cuando hacen falta. La idea es la misma: cargar lo necesario cuando sea necesario, en vez de cargarlo todo siempre.

Rutina de revisión del coste fijo

El contexto cargado permanentemente es difícil de detectar una vez que crece. El coste es el mismo en todas las sesiones, así que no hay una referencia con la que compararlo. Por eso merece la pena revisarlo conscientemente de vez en cuando.

En Claude Code, /context desglosa dónde y cuánto se utiliza el contexto actual. Muestra los tokens del prompt del sistema, las herramientas, MCP y los archivos de memoria; si las definiciones de herramientas resultan anormalmente mayores que la conversación, empieza por depurar los servidores MCP. Abre CLAUDE.md aproximadamente una vez por trimestre y elimina líneas según el criterio “¿esta línea ayudó realmente el mes pasado?”. Los archivos de instrucciones solo crecen si se abandonan, así que la poda debe convertirse en rutina para mantenerlos breves.

Resumen

• El prompt del sistema, las definiciones de herramientas y CLAUDE.md son costes fijos incluidos en cada turno. No desaparecen con /clear, así que deben diseñarse antes de gestionar la conversación.
• El criterio para CLAUDE.md es “¿Esto es siempre cierto para todas las tareas?” Como la longitud difumina las reglas individuales, cuando no se cumplen lo primero es acortar el archivo.
• Usa punteros en lugar de documentos detallados completos, separa los procedimientos repetitivos en skills y desactiva los servidores MCP que no uses. El principio es cargar lo necesario solo cuando sea necesario.

Con esto, el contexto de una sesión queda bastante limpio. Pero, por mucho que ahorres, llega un momento en que una tarea grande no cabe en una sola sesión. La próxima parte presenta la solución estructurada para ese caso: los subagentes. Veremos cómo un patrón de aislamiento—encargar la exploración a otro contexto y recibir solo la conclusión—protege el contexto.

Lecturas recomendadas

• Reglas y memoria de Claude Code: ¿en qué se diferencian CLAUDE.md y la función de memoria?
• [MCP·Skill #2] Guía completa de Skills para agentes de IA, desde los comandos de barra hasta los activadores automáticos
• [Contexto de IA #5] ¿Por qué usar subagentes? Principios del aislamiento de contexto de los agentes de IA y criterios de delegación