Reducir un CLAUDE.md gigante en un 91 % y medir qué se rompió

Imagina que cada sesión en un repositorio empieza cargando un CLAUDE.md de 194.492 caracteres. Son unos 48.600 tokens antes de escribir una sola palabra, repetidos en cada mensaje, y casi cinco veces el tamaño a partir del cual Claude Code empieza a avisar sobre un archivo de memoria. Ahora imagina que nada de eso es basura. Son dos años de memoria operativa ganada a pulso: el comando de migración que elimina un índice sin avisar, el índice de plazas que reintenta la misma plaza para siempre, la función de color cuya sintaxis de salida no sabían leer dos comprobadores de contraste. Borrarlo no es una opción.

El camino viable dejó el archivo en 17.283 caracteres, un recorte del 91 %, con cuatro palabras perdidas, todas de encabezados eliminados a propósito. Después vino la parte de la que poca gente se ocupa: medir si la reestructuración funcionó de verdad. A continuación, el método completo, error incluido.

Una advertencia antes de probarlo. La reestructuración reescribe CLAUDE.md en su sitio y crea archivos bajo .claude/, así que haz commit o stash antes de empezar, y git checkout podrá deshacerlo. El entorno de pruebas lanza sesiones headless reales de Claude Code, una por prompt, que consumen cuota de la API y a veces varios minutos cada una. Prueba primero con dos o tres prompts en lugar de veinte. Y como cada base de código es distinta, lee cada comando y cada script antes de ejecutarlo en tu sistema.

Por qué fallan las soluciones obvias

Borrar lo obsoleto parece sensato, pero no puedes saber qué está obsoleto sin releer el código que describe cada nota. «Esto parece anticuado» es una suposición, y una suposición equivocada elimina justo la nota que habría salvado una futura sesión de depuración.

Resumir es la opción peligrosa, y tiene su propia sección más abajo.

Dividir con @import tampoco ayuda. Los imports se expanden en línea, así que obtienes un archivo más ordenado con el mismo coste de contexto.

El problema real no es el tamaño. Es que todo se carga para cada tarea, incluido el 90 % que no tiene nada que ver con la que estás haciendo. A un bug de CSS no le sirven de nada las reglas sobre el orden de los webhooks de Stripe.

Tres capas

Piensa en niveles: un núcleo ligero que siempre se carga, skills que entran cuando el modelo decide que su descripción encaja con la tarea, y archivos de referencia que solo se abren cuando hacen falta. Un cuarto mecanismo recibe muy poca atención. Los archivos de reglas en .claude/rules/ pueden llevar frontmatter paths:, de modo que se cargan cada vez que tocas archivos que coinciden. Es coincidencia por glob, sin que nadie tenga que decidir nada.

Dónde acabó: un CLAUDE.md de 17KB, más 12 skills y 28 archivos de referencia.

Decidir qué se queda cargado

Un skill se carga cuando el modelo decide que su descripción encaja. Ese juicio es muy bueno, pero sigue siendo un juicio. Por eso «¿es importante?» es la prueba equivocada, ya que todo en el archivo importaba. Pregúntate esto: si esta regla no se cargara justo en el momento en que cuenta, ¿qué tan grave sería?

Una trampa de estilos te cuesta algo de tiempo. Que falle una regla de seguridad significa publicar el bug que existe para evitar. Así que todas las reglas de seguridad se quedaron residentes, las 26, más 21 invariantes de arquitectura (una base de datos por cliente, un registro contable de solo inserción, un índice único parcial que resuelve la competencia por plazas) y los comandos, que se necesitan constantemente y cuestan poco. Tarifas, reservas, notificaciones, apps móviles, páginas renderizadas, prácticas de testing y la lista de carencias conocidas salieron fuera.

Extrae las reglas, no las reescribas

Meter 47 reglas en unas 200 líneas invita a reescribir cada una como una frase nítida. No lo hagas. Una línea de la propia guía del repositorio, escrita tras llevarse un buen susto, lo explica bien: una afirmación obsoleta que se edita sin comprobarla no queda corregida, queda blanqueada, así que o relees el código que describe la línea o la dejas como está.

Parafrasear 47 reglas sin verificar produce 47 afirmaciones seguras que nadie ha comprobado, y parecerían recién revisadas, lo cual es peor que parecer viejas.

La salida es que tus reglas probablemente ya empiezan con la regla misma como primera frase. Copia esa frase palabra por palabra y lleva el razonamiento a un archivo de referencia. No se reescribe nada. La regla vive en CLAUDE.md y el «porqué» queda a un salto de distancia. Una entrada residente tiene este aspecto:

- **The card never touches this server.** A SetupIntent hands the browser a
  client secret and Stripe's own SDK collects the number, which is why no
  endpoint here takes one.

Una frase se queda cargada, y las 400 palabras restantes de razonamiento van a hard-rules/references/security.md.

Dos entradas empezaban con un hallazgo en lugar de una instrucción, como una mayúscula que movía a un rastreador anónimo al límite de peticiones de los miembros de un estudio. Cada una terminaba además con una frase que empezaba por "The general rule" («La regla general»), y esa línea se trasladó tal cual.

Demuestra que no ha desaparecido nada

Un diff línea a línea no sirve de nada, porque la prosa movida cambia sus saltos de línea y todo aparece modificado. Comparar frases funciona solo un poco mejor, ya que las negritas y los encabezados cambian dónde empiezan y terminan las frases. Contar palabras como multiconjunto esquiva ambos problemas: cada palabra del corpus antiguo tiene que aparecer en el nuevo al menos tantas veces como antes.

La ejecución final mostró 4 de 31.697 apariciones de palabras ausentes: Traps, bitten, Invariants y simplify, todas de dos encabezados de sección eliminados. Así es como se ve «terminado».

Comprueba también que la verificación falla cuando debe. Borrar el directorio de un skill y volver a ejecutarla produjo 2.522 pérdidas, incluida la palabra fee cuarenta veces. Una verificación que nunca has visto fallar no es una verificación.

El error

El script de construcción añadía las entradas movidas al final de dos archivos de skills existentes, y se ejecutó dos veces durante las iteraciones. El resultado fueron 36 bloques de entradas donde debía haber 28, una duplicación silenciosa, justo el fallo del que avisan todas las guías. Se detectó solo porque cada entrada se contaba en todos los archivos y se exigía que apareciera exactamente una vez. Añade esa comprobación. Haz que el script sea idempotente, o que reescriba los archivos en lugar de añadir al final.

Mide, no te fíes de una cifra citada

Una cifra muy compartida dice que los skills se activan alrededor del 79 % de las veces, frente al 100 % de una regla que está directamente en CLAUDE.md. Como advertencia es útil, pero es la medición de una persona sobre su propia configuración, no una constante. Mide la tuya:

1. Escribe 14 prompts que podría teclear un usuario real, que cubran todos los skills y estén formulados como síntomas en lugar de temas. "The Booked screen crashes with RangeError" («la pantalla Booked falla con RangeError») funciona. "Tell me about the mobile app" («háblame de la app móvil») ya te da la respuesta.
2. Ejecuta cada uno en una sesión headless nueva con claude -p. La sesión que hizo la reestructuración ya tiene todos los skills en su contexto, así que preguntarle qué habría cargado no te dice nada.
3. Captura el session_id de cada ejecución con --output-format json, para que las pruebas en paralelo no se mezclen.
4. Abre la transcripción de esa sesión y anota qué skills se cargaron.
5. Bloquea Edit y Write para que la medición no pueda modificar el repositorio que mide.

Cuenta dos eventos como éxito: que se llame a la herramienta Skill o que el modelo abra a mano un archivo de skill. Si llega al conocimiento correcto leyendo el archivo, también cuenta.

El resultado fue 13 de 14, un 93 %, no un 79 %. Y en cada acierto, el skill se activó como la primerísima llamada a herramienta, antes de abrir ningún archivo.

Un fallo cuesta dinero, no exactitud

El único fallo dio igualmente una respuesta correcta. Simplemente reconstruyó el conocimiento desde cero: 56 llamadas a herramientas frente a una mediana de 16 en los aciertos. Releyó cuatro archivos fuente y pasó grep por la API para deducir lo que el skill habría aportado en una sola lectura. La capa residente también funcionó como red de seguridad: una regla estricta sobre fechas de calendario bastó para dirigirlo a la referencia correcta de todos modos.

Eso cambia la forma de ver el riesgo. Un fallo no significa que la regla no se aplique. Significa una sesión unas 3,5 veces más cara, un fallo mucho menos aterrador.

El fallo era un error de redacción

Los dos prompts sobre la app móvil apuntaban al mismo skill, pero solo el que contenía la palabra "Expo" lo activó. La descripción del skill anunciaba herramientas, como fijar la versión del SDK, Metro con pnpm y controlar un simulador. También contenía trampas a nivel de pantalla: un botón Book para una clase que el miembro ya tiene reservada, un campo de fecha que provocaba un fallo. Un prompt sobre el fallo de la pantalla Booked no coincidía con ninguna de las palabras anunciadas.

Así que describe síntomas, no herramientas. Pregúntate qué verá realmente el usuario. Una descripción floja enumera ajustes de pnpm, globs de tests de Node, salida de tsc y la estructura de la imagen Docker. Una buena se activa cuando un build se rompe por motivos ajenos al propio código, por ejemplo MODULE_NOT_FOUND, ningún query engine presente, una imagen inflada o un arreglo que solo funciona al segundo intento.

Tras reescribir así las 11 descripciones y probar siete prompts nuevos formulados como síntomas, el resultado fue 7 de 7, todos en la primera llamada a herramienta. El prompt que antes falló ahora acertó, con 26 llamadas en lugar de 56.

Reglas asociadas a rutas como segunda red

Para todo lo que corresponda a un directorio, .claude/rules/*.md elimina el juicio por completo:

---
paths:
  - "apps/mobile/**"
  - "apps/mobile-yoga/**"
---

You are in one of the two Expo member apps.

**Read `.claude/skills/mobile-apps/SKILL.md` before changing anything here.**m

Mantenlas como punteros, nunca como copias, para que el conocimiento viva en un único sitio.

Una prueba canario de doble cara te dice si la asociación funciona de verdad, porque un glob que no coincide con nada se comporta desde fuera igual que uno que funciona. Crea una regla limitada a un directorio, con un texto que indique a Claude imprimir una cadena marcador inventada. Abre un archivo de ese directorio y deberías ver el marcador. Abre uno de otro sitio y el marcador no debería aparecer.

Casi todo el mundo se salta el último paso. Sin él no puedes distinguir «funciona» de «se carga siempre», y lo segundo borra tu ahorro sin avisar. Aquí ambas pruebas se comportaron bien: 1 y 0.

Un aviso: escribe los globs según tu estructura real. La primera suposición fue apps/api/src/fees/, pero las tarifas, las membresías y los bonos de clases vivían en realidad en apps/api/src/billing/. Sin comprobarlo, esas reglas no habrían coincidido con nada, en silencio y para siempre.

Lo que cuesta

El corpus creció un 14 %, de 194.492 a 220.885 caracteres. Esos 26.393 caracteres extra son frontmatter, tablas de índice y punteros, sin conocimiento nuevo; están ahí para que el archivo correcto te encuentre. Las ediciones ahora también tocan más archivos, porque un cambio se convirtió en tres. Una tabla de enrutado en CLAUDE.md reduce el riesgo de contenido obsoleto sin eliminarlo. Y cambias un archivo que siempre está algo inflado por otro que suele ser ligero y a veces sale caro. Es un intercambio que vale la pena repetir, siempre que admitas que no es gratis.

Versión empaquetada

El método se ha empaquetado como plugin de Claude Code con dos skills: uno hace la reestructuración con las reglas de seguridad incorporadas y otro mide si tus skills se activan de verdad. Instálalo con:

/plugin marketplace add your-org/claude-md-progressive-disclosure

/plugin install progressive-claude-md

Después dile a Claude que tu CLAUDE.md es demasiado grande y pídele que lo reestructure, y más adelante pídele que mida si tus skills se activan.

Te quedes con lo que te quedes de esto, mide tu propia tasa de aciertos antes de construir nada para arreglarla. Aquí el punto de partida era del 93 % antes de cambiar nada, y el único defecto real fue una frase mal escrita, no la arquitectura.