¿CLAUDE.md demasiado largo? Qué recortar y adónde llevarlo

Un CLAUDE.md es demasiado largo cuando contiene líneas sin las que el agente no se equivocaría. La documentación de Anthropic fija como objetivo menos de 200 líneas por archivo CLAUDE.md; nosotros presupuestamos palabras, porque las líneas esconden la densidad. Al terminar esta guía habrás auditado tu archivo línea a línea, le habrás dado un sitio a cada línea recortada y tendrás un único archivo que leen Claude Code, OpenCode y Kimi Code.

Un archivo de instrucciones largo no es un problema de redacción. Es un problema de orden: casi todas sus líneas son ciertas, solo que están en el sitio equivocado. Una línea mal colocada cuesta contexto en cada sesión y entierra las reglas que importan. Anthropic lo dice sin rodeos: los archivos CLAUDE.md sobrecargados hacen que Claude ignore tus instrucciones reales (Anthropic, Best practices(se abre en una pestaña nueva)).

Todos los ejemplos usan Mossbank, una app de planificación inventada para empresas de fontanería y calefacción. Su archivo y sus cifras son inventados; los presupuestos y las reglas son los que aplicamos en Neomanex.

Qué necesitas antes de empezar

Audita los archivos que se cargan juntos, no el que tengas abierto en ese momento. El agente nunca ve un archivo aislado: Claude Code carga todos los CLAUDE.md desde la raíz del proyecto hasta la carpeta en la que trabajas, más todo lo que importan.

Mide lo que se carga de verdad

Dejamos de contar líneas. Una fila de tabla puede contener un párrafo, así que presupuestamos palabras y tratamos un archivo denso como uno largo.

El coste de un archivo son sus palabras: dos archivos de 180 líneas pueden tener costes muy distintos, así que el presupuesto se fija en palabras para cada tipo de archivo y para todo lo que se carga junto.

Ejecuta wc -lw en cada archivo, suma las palabras y divide las palabras entre las líneas. Por encima de unas 15 palabras por línea, las celdas de las tablas se han convertido en párrafos: divide la celda o saca el contenido.

El objetivo de líneas de Anthropic existe porque «los archivos más largos consumen más contexto y reducen el grado de cumplimiento» (Anthropic, Memory(se abre en una pestaña nueva)). Las importaciones cuentan enteras: los archivos importados también se cargan al arrancar.

El archivo raíz de Mossbank tiene 420 líneas y unas 9600 palabras: 23 palabras por línea, muy por encima del máximo de 1800 palabras para la raíz de un proyecto.

Aplica la prueba de una línea a cada línea

La pregunta de poda de Anthropic es toda la auditoría: ¿eliminar esta línea haría que Claude cometiera un error? La disciplina está en hacérsela a cada línea, incluidas las que escribiste la semana pasada.

¿Qué es un registro de recortes? Un registro de recortes es una tabla con una fila por cada línea o bloque del archivo: la línea, si el agente se equivoca sin ella, por qué y adónde va la línea.

Se quedan dos filas. La fila 2 se queda solo porque nombra el archivo que la demuestra.

Dale un destino a cada línea recortada

Eliminar es el último recurso, no el primero. La mayoría de las líneas recortadas son conocimiento que debe estar en algún sitio que el agente lea solo cuando lo necesite.

Una línea que no supera la prueba de una línea va al primer destino cuya pregunta responde con un sí: hook, paso de flujo de trabajo, regla de carpeta, skill, página de documentación o eliminar.

Haz las preguntas en este orden. El primer sí elige el destino.

El hook va primero porque el archivo es orientativo: la documentación de Anthropic dice que, para bloquear una acción decida lo que decida Claude, uses un hook PreToolUse. Nuestra guía para impedir que Claude Code borre tus archivos monta uno paso a paso. Una regla de carpeta en Claude Code es un archivo de .claude/rules/ con frontmatter paths:, en este caso con migrations/**, o un CLAUDE.md hijo en esa carpeta. Nosotros limitamos las nuestras por ruta.

La lista de comprobación de lanzamientos de Mossbank es el clásico ejemplo de línea mal archivada: un orden y la aprobación de Dana, leídos enteros en cada sesión, con la parada confiada a la memoria. Nosotros guardamos este tipo de procesos como flujos de trabajo de ConvOps(se abre en una pestaña nueva), de modo que el agente lee un paso cada vez y la aprobación es un paso en sí misma (cómo dirigimos nuestra empresa con flujos de trabajo). Saca todos los procesos y el archivo se reduce a un archivo de identidad: esa es la vía radical, la ingeniería de grafos.

Mueve cada línea y deja un puntero de una línea

Un recorte que pierde conocimiento no es un recorte. Es un bug futuro, así que cada línea movida deja un puntero.

El CLAUDE.md de 420 líneas de Mossbank conserva las líneas que evitan errores y lleva cada una de las demás a un destino desde el que se carga solo cuando hace falta.

El mapa de módulos de Mossbank pasa a docs/module-map.md, y el archivo conserva una línea que nombra la página. De las 420 líneas, 90 se quedan, 150 van a tres páginas de documentación, 60 a dos skills, 30 a una regla de carpeta, 25 al flujo de trabajo de lanzamiento, 10 a dos hooks y 55 se eliminan. El archivo termina con unas 100 líneas, las 90 conservadas más 10 punteros, y 1100 palabras, por debajo del objetivo de 1200.

Una importación con @ no es un recorte. @docs/module-map.md carga la página al arrancar de todos modos. Un puntero normal no carga nada hasta que el agente lo sigue.

Haz que un solo archivo sirva como CLAUDE.md y AGENTS.md

Dos archivos de instrucciones para tres herramientas significan que cada herramienta lee un archivo distinto. Nosotros mantenemos una sola fuente y enlazamos el otro nombre a ella.

Con dos archivos, Claude Code lee CLAUDE.md mientras OpenCode y Kimi Code leen AGENTS.md; con AGENTS.md como enlace simbólico a CLAUDE.md, las tres herramientas leen el mismo archivo una sola vez (probado en octubre de 2026).

Probamos cada configuración el 9 de octubre de 2026, con una palabra clave distinta en cada archivo:

Dos archivos separados acaban divergiendo, así que cada herramienta sigue instrucciones distintas. Con solo CLAUDE.md, Kimi Code se queda sin nada. Mantén CLAUDE.md como fuente y ejecuta ln -s CLAUDE.md AGENTS.md: de las cuatro configuraciones que probamos, es la única en la que las tres herramientas leen el mismo texto una sola vez. El nuestro se genera: un script crea un AGENTS.md junto a cada CLAUDE.md, así que cada carpeta tiene una sola fuente.

Según la documentación de Anthropic, las herramientas Edit y Write de Claude Code se niegan a escribir a través de un enlace simbólico, así que edita CLAUDE.md; en Windows, haz que CLAUDE.md sea una importación de una línea, @AGENTS.md. Elimina o mueve los dos archivos juntos: un CLAUDE.md eliminado deja su enlace AGENTS.md apuntando a la nada.

Comprueba que se ha cargado y vuelve a comprobarlo cada vez que crezca

Un archivo recortado vuelve a crecer por defecto, porque cada lección quiere vivir en el archivo que todos leen. La nueva comprobación forma parte de la edición, no de un día de limpieza.

El archivo de Mossbank gana dos líneas en su primera semana (y las dos son lecciones reales), y el recuento de palabras las detecta. La regla: una lección nueva va primero a su destino, y al archivo en último lugar.

Empieza por tu proceso más largo. Crea una cuenta gratuita de ConvOps(se abre en una pestaña nueva), pide a tu IA que escriba ese proceso como flujo de trabajo y después elimínalo del archivo. ¿Quieres que alguien más revise los archivos de instrucciones de tu equipo? Reserva una sesión de descubrimiento gratuita.

Errores habituales y las reglas que nos dejaron

Cada regla de nuestro presupuesto existe porque un archivo se equivocó en algo, no porque lo dijera una guía de estilo. Cada error de abajo nos pasó a nosotros; aquí lo contamos con el ejemplo de Mossbank.