CLAUDE.md: por qué 200 líneas es el objetivo y 4 MiB el límite real

La documentación de Claude Code fija un objetivo para el archivo CLAUDE.md: menos de 200 líneas por archivo. No es una frontera dura, nada se rompe en la línea 201. Lo que ocurre es que el archivo consume más contexto y el modelo empieza a pasar por alto sus propias instrucciones. El límite real, el que corta en seco, es otro: 4 MiB. Por encima de esa cifra Claude Code se salta el archivo entero y no lo carga.

Dos números, dos comportamientos

A las 200 líneas se llega por acumulación y el coste crece poco a poco. Los 4 MiB son una frontera de comportamiento: el archivo se carga completo hasta ahí y se ignora a partir de ahí. Con prosa normal es imposible acercarse; con un log pegado o un artefacto generado, no tanto.

Conviene no mezclarlo con MEMORY.md. La regla de que solo se cargan las primeras 200 líneas o 25 KB, lo que llegue antes, es exclusiva de la memoria automática. El CLAUDE.md no se trunca a las 200 líneas. El mismo número significa cosas distintas según el archivo del que se hable.

Lo que pesa al arrancar

La documentación incluye una simulación interactiva de lo que se carga al abrir una sesión: 4.200 tokens de prompt de sistema, 1.800 del CLAUDE.md de proyecto, 320 del de ámbito de usuario en ~/.claude/CLAUDE.md, 680 de memoria automática y 450 de descripciones de skills. Son cifras ilustrativas de la simulación, no medidas de archivos reales, pero dan la escala: 1.800 tokens contra una ventana de 200.000.

El detalle que se suele escapar son los subagentes. Cada subagente carga el mismo CLAUDE.md en su propio contexto, así que cuenta contra el suyo y no contra el de la sesión principal. Los agentes incorporados Explore y Plan se lo saltan para no inflarse. En un flujo con varios subagentes, la longitud del archivo se multiplica. Para ver los números propios, /context y la sección Memory files.

Recortar, dividir o mover

Pasado el umbral hay tres movimientos y no equivalen a lo mismo.

Recortar es el que más devuelve. La recomendación es probar cada línea con una pregunta: si la quito, ¿Claude cometería un error? Si la respuesta es no, fuera. Los archivos inflados hacen que el modelo ignore instrucciones reales. La herramienta /doctor propone recortes concretos, lo que se deduce leyendo el código, como listados de directorios o dependencias, y deja lo que no se deduce: trampas, decisiones de arquitectura y convenciones que se salen de lo estándar. El chequeo requiere la versión v2.1.206 o posterior.

Dividir en archivos separados con imports @path mejora la legibilidad y no ahorra un solo token: los importados se expanden y se cargan al arranque.

Mover es lo único que reduce contexto de verdad. Las reglas con ámbito de ruta, definidas en .claude/rules/ con un campo paths, solo entran cuando Claude lee un archivo que encaja. Las skills se cargan al invocarlas o cuando el modelo las considera relevantes, así que los procedimientos de varios pasos van ahí y no en el CLAUDE.md.

Un último recurso para dejar notas sin gastar contexto: los comentarios HTML a nivel de bloque se eliminan antes de que el contenido llegue al modelo, así que sirven para avisos dirigidos a quien mantiene el archivo.

La cifra de 200 líneas no es una alarma, sino un aviso de que cada línea compite por atención con el código que el modelo tiene delante. Lo que no esté ahí se deduce del repositorio; lo que esté de más, resta.