Borra tu CLAUDE.md, medido: tablas de ablación, checklist y fuentes

TL;DR

• En un repositorio real con un CLAUDE.md de 177 líneas, 3 skills y 1 hook, borrarlo todo rompió exactamente una regla, en una sola situación: la regla de i18n en un archivo nuevo. Todas las demás convenciones se mantuvieron porque el código circundante ya las enseñaba.
• El archivo costó entre un 4 y un 14% de los tokens leídos en las tareas donde el resultado fue idéntico, más o menos un dólar de cada diez. El 32% de ahorro que se cita está dominado por la única tarea donde el archivo hizo que el modelo trabajara más.
• Los skills y el hook no cuestan nada medible: los skills se cargan al invocarlos y ninguno se invocó, el hook inyecta una sola frase.
• La visión general de arquitectura de 82 líneas no aportó nada en la pregunta de arquitectura: seis respuestas, todas correctas, con o sin el archivo.
• «Borrar», en palabras de Anthropic, significa ablacionar y pasar a la divulgación progresiva, no eliminar. Conserva las reglas que el código no puede enseñar, mueve el resto a archivos de reglas y skills, y convierte las innegociables en hooks.
• Dos repeticiones por configuración son un mínimo, no un veredicto: las diferencias por tarea por debajo del 15% están dentro del ruido entre ejecuciones.

Qué dicen las mediciones

La charla a la que todos reaccionan dice dos cosas, y la segunda se pierde. Boris Cherny confirma en el escenario que Claude Code eliminó el 80% de su prompt de sistema, y describe el método: borrar todo el prompt de sistema y luego devolverlo línea por línea para medir el impacto de cada una s2. El pasaje de «every 6 months» está entre 00:06:58 y 00:07:05, y la formulación es «really do recommend», no «strongly recommend» s1. Dos frases que se le atribuyen mucho no están en la charla: «context, goals and a definition of done» (lo más cercano real, en 15:22, es «describe the task, the guardrails, the exit criteria») y «64 agents». Él dice «eleven days» y, cuando le preguntan cuántos agentes, «I'm not sure» s2. La cifra de 64 pertenece al artículo sobre la reescritura de Bun: «64 Claudes running for 11 days», unos $165,000 a precio de API, 9 billion de tokens de entrada sin caché, 690 million de tokens de salida y 72 billion de lecturas de tokens de entrada en caché s14.

Lo que hace medible todo esto es la carga. CLAUDE.md y los archivos de reglas se inyectan en cada turno; los skills solo se cargan cuando se invocan. La documentación de memoria también incluye la guía de tamaño que todos parafrasean: «target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.» s4. La versión escrita del consejo de Anthropic presenta el CLAUDE.md como repositorio central como un mito y apunta a la divulgación progresiva y a la memoria automática s3.

El único estudio controlado antes del nuestro es el artículo de ETH sobre AGENTS.md: 138 issues en 12 repositorios, y «providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average». Los archivos escritos por desarrolladores superan a los generados por un LLM en un 7% de media, y las instrucciones que nombran herramientas concretas sí ayudan s5.

Dos datos sobre qué contienen estos archivos y cómo se leen. En 28,721 repositorios y 165,063 archivos, el archivo de instrucciones mediano tiene 50 elementos de contenido, de los cuales 12 son directivas reales; el autor lo resume diciendo que solo el 27% del archivo hace lo que crees s8. En un experimento controlado con dos instrucciones en conflicto real, mover una sola regla de arriba del archivo al final cambia en unos 90 puntos la frecuencia con que el modelo la obedece, de casi nunca a casi siempre s9. El mismo editor traza la línea que sigue nuestro experimento: ablación no es borrado, y los hooks son cumplimiento forzado, no caducan con una actualización de modelo s7.

Dos referencias informales coincidieron con nuestro resultado. Un CLAUDE.md de 1,000 líneas comparado con una versión recortada de ~20 líneas sobre los mismos issues de GitHub y el mismo modelo: la arquitectura se mantuvo, las reglas de la casa se rompieron s6. Un comentarista que movió todo a divulgación progresiva cuenta que el contexto cargado automáticamente pasó de ~35k a ~4.5k tokens por sesión, sin borrar ningún conocimiento s11. Para puntuar ablaciones de skills hay una herramienta: el --ablate de caliper cubre skills y servidores MCP y su compare informa tasa de éxito, tokens y tiempo real; el intercambio del CLAUDE.md sigue siendo manual s16.

Mediciones

Protocolo: un repositorio privado Expo / React Native (1,021 archivos rastreados), CLAUDE.md de 177 líneas, 7,243 caracteres, unos 1,800 tokens, 3 skills, 4 comandos slash, 1 hook PreToolUse. Modelo fijado en claude-opus-5 en todas las ejecuciones, Claude Code 2.1.278, claude -p en modo headless, --max-turns 40, directorio de configuración de usuario vacío, sin MCP, clon limpio restablecido antes de cada ejecución. Cinco tareas cotidianas (componente nuevo, editar un componente, refactorizar helpers compartidos, persistir un campo del store, explicar un recorrido de datos), ablación de una pieza cada vez. 44 ejecuciones, $38.97 a precio de API, 92 minutos de tiempo de agente. Puntuación: las reglas de la casa del repo sobre las líneas añadidas, tsc --noEmit, eslint, respuestas calificadas a mano.

Calidad, qué se rompió:

Coste por ejecución, media sobre las ejecuciones de la config (tokens = lecturas de caché, el contexto releído en cada turno):

Por tarea, de A a B (media de 2 ejecuciones cada una):

Cómo leer las tablas. Sin el CLAUDE.md, 3 de 4 ejecuciones del componente nuevo escribieron el título como cadena simple; con él, 4 de 4 crearon el .content.ts con EN y FR. En la tarea de edición todas las configs, incluso E, pusieron la cadena nueva en un .content.ts: los archivos vecinos llevaban la convención. Todo lo demás se mantuvo en las 44 ejecuciones: 0 imports relativos, type y no interface en seis ediciones del archivo de tipos, design tokens en cada diff, 0 colores hexadecimales, ningún archivo barrel. Una instrucción que nadie pudo seguir: el archivo dice que importes theme desde @design-tokens, un alias que no existe en tsconfig.json; ninguna ejecución, en ninguna config, lo usó, 1,800 tokens leídos para nada en cada sesión. El ahorro de T1 es la ejecución más barata haciendo menos trabajo. La varianza entre ejecuciones es mayor que la mayoría de los efectos de config: T1 con la config completa costó $2.11 y luego $1.33. Un control con el grafo de código de 333 MB presente cayó en las cifras de la config completa ($1.59 vs $1.72 en T1, $0.38 vs $0.34 en T5): el bloque del grafo y el hook no cambiaron nada medible.

Qué hacer el lunes

• Cuenta tu CLAUDE.md: líneas, caracteres y cuántas líneas son directivas reales (Always, Never, Use, Prefer). El resto es contexto que el modelo relee en cada turno.
• Elige una convención por sección y comprueba si un archivo vecino ya la muestra. Si tres archivos de la carpeta siguen la regla, la línea es candidata a borrarse.
• Encuentra la regla que el código no puede enseñar en un archivo nuevo (i18n, telemetría, cabeceras de licencia, un paso de registro obligatorio). Consérvala, formúlala en una línea y ponerla cerca del principio.
• Prueba cada ruta de import y cada comando que nombra tu archivo. Un alias muerto o un script renombrado es una instrucción que nadie puede seguir.
• Mueve las visiones de arquitectura largas y los pasos de instalación a un archivo de reglas o a un skill que se cargue bajo demanda, y compara el contexto cargado automáticamente antes y después.
• Convierte tus dos o tres reglas innegociables en un hook o una regla de lint. El cumplimiento forzado no depende de que el modelo lea un párrafo.
• Ejecuta tus dos tareas más comunes dos veces con el archivo y dos veces sin él, con un modelo fijado, y lee los tokens y el diff. Dos repeticiones dicen dónde mirar, no qué concluir.

Para ir más lejos

• La charla en sí, por el método y no por la frase suelta: borrar y luego devolver línea por línea s2.
• Todos los resultados del artículo, incluido que los archivos escritos por desarrolladores superan a los generados en un 7% y que nombrar herramientas ayuda s5.
• La posición de la regla como variable: el salto de ~90 puntos y cómo el modelo resuelve en silencio instrucciones en conflicto s9.
• La anatomía de un archivo de instrucciones en 30k repositorios: 50 elementos, 12 directivas, y qué son los otros 38 s8.
• La guía de HumanLayer para escribir un buen CLAUDE.md y el hilo que la discute s10.
• El hilo «MUST use agent, ignorado el 80% de las veces»: un argumento a favor de los hooks donde la prosa falla s12.
• El hilo «Claude Code now ignores everything», útil para separar la deriva del modelo de los conflictos de instrucciones s13.
• caliper, para puntuar ablaciones de skills y MCP con tasa de éxito, tokens y tiempo real s16.

Fuentes

• Boris Cherny: We Cut 80% of Claude Code's Prompt, Y Combinator. Por qué leerlo: la cita primaria, con el matiz que los clips recortan.
• Transcript of the talk, Y Combinator. Por qué leerlo: texto con búsqueda para comprobar qué se dijo y qué no.
• The new rules of context engineering for Claude 5 generation models, Anthropic. Por qué leerlo: la versión escrita del consejo, divulgación progresiva en lugar de un archivo central.
• Memory docs: CLAUDE.md and rules files, Claude Code docs. Por qué leerlo: qué se carga en cada turno, qué se carga bajo demanda y la guía de 200 líneas.
• Evaluating AGENTS.md, arXiv. Por qué leerlo: la única medición controlada de archivos de contexto antes de esta.
• Should you delete your CLAUDE.md every 6 months?, Modern Creator. Por qué leerlo: una comparación informal de 1,000 líneas contra 20 cuyo patrón de fallos coincide con el nuestro.
• Opus 5: delete your CLAUDE.md?, reporails. Por qué leerlo: ablación frente a borrado, y por qué los hooks sobreviven a una actualización de modelo.
• The State of AI Instruction Quality: 30k-repo analysis, reporails. Por qué leerlo: qué contiene realmente un archivo de instrucciones mediano.
• Opus 5: the cost of instruction conflicts, reporails. Por qué leerlo: un experimento controlado sobre la posición de las reglas.
• Writing a good CLAUDE.md, HN thread, Hacker News. Por qué leerlo: profesionales discutiendo qué debe ir en el archivo.
• Anthropic says keep CLAUDE.md under 200 lines, r/ClaudeCode. Por qué leerlo: el comentario de antes y después de ~35k a ~4.5k.
• CLAUDE.md says MUST use agent, Claude ignores it, r/ClaudeCode. Por qué leerlo: un caso concreto donde las instrucciones en prosa fallan.
• Claude Code now ignores everything, r/ClaudeCode. Por qué leerlo: los reportes de síntomas detrás de la sensación de que «algo cambió».
• Rewriting Bun in Rust, Simon Willison. Por qué leerlo: de dónde salen las cifras de 64 agentes y $165,000.
• caliper, GitHub. Por qué leerlo: un arnés de puntuación para ablaciones de skills y MCP.

FAQ

¿Debo borrar mi CLAUDE.md?

No a ciegas. En nuestro repo la única pérdida fue una regla en archivos nuevos; todo lo que el código ya demostraba se mantuvo sin el archivo. Ablaciona una sección cada vez y conserva lo que cambia el resultado.

¿Por qué el archivo ahorró un 32% de tokens si solo costó entre un 4 y un 14%?

Porque el agregado está dominado por la tarea del componente nuevo, donde el archivo hizo que el modelo escribiera un segundo archivo en dos idiomas. La ejecución más barata hacía menos. En las tareas con resultado idéntico, el ahorro fue del 4 al 14%.

¿Los skills y los hooks cuestan tokens en cada turno?

Los skills solo se cargan al invocarlos, así que un skill sin invocar no cuesta nada; el hook inyecta una sola frase. Borrar ambos no cambió ninguna cifra en nuestras ejecuciones. Los archivos de reglas y el CLAUDE.md son los que se releen en cada turno.

¿Bastan dos ejecuciones por configuración?

No. Dos repeticiones localizan el efecto, no lo dimensionan. Nuestra config completa costó $2.11 y luego $1.33 en la misma tarea, así que las diferencias por tarea por debajo del 15% están dentro del ruido.