Un fenómeno que muchos builders ya sufrían tiene por fin nombre: recuerdo catastrófico (catastrophic remembering). Un trabajo publicado en arXiv bajo el título Why Does Claude.md Keep Growing? analiza por qué el archivo CLAUDE.md —el documento que le dice a Claude Code cómo comportarse en tu proyecto— tiende a engordar sin freno hasta convertirse en un lastre que consume contexto y degrada la calidad de las respuestas.
El dato incómodo: cada vez que un agente comete un error y el desarrollador añade una regla nueva para evitarlo, el archivo crece. Con el tiempo, se acumulan decenas de instrucciones que rara vez vuelven a activarse, pero que ocupan tokens en cada llamada. Es lo contrario del olvido catastrófico de las redes neuronales: aquí el sistema lo recuerda todo, incluso lo que ya no importa. En este artículo desglosamos qué describe el paper, qué significa para quien construye con Claude Code a diario y cómo mantener el CLAUDE.md a raya.
¿Qué es el recuerdo catastrófico en la codificación con agentes?
El CLAUDE.md es un archivo de instrucciones persistentes que Claude Code lee al iniciar cada sesión: convenciones de estilo, comandos de build, rutas del proyecto, cosas que NO debe tocar. El problema, según el análisis publicado en arXiv sobre el crecimiento de Claude.md, es que su tamaño crece de forma monótona porque los desarrolladores lo usan como parche reactivo: cada fallo del agente se traduce en una regla nueva.
La consecuencia es doble. Primero, un coste directo: ese texto viaja en cada petición y ocupa parte de la ventana de contexto que podría dedicarse al código real. Segundo, un coste de calidad: cuando el archivo mezcla instrucciones vigentes con reglas obsoletas o contradictorias, el modelo recibe señales ruidosas y su comportamiento se vuelve menos predecible. Los autores describen el patrón como un crecimiento que rara vez se revierte, porque nadie audita ni poda el archivo.
Desde nuestra experiencia con Claude Code, esto encaja con lo que se ve en cualquier equipo tras unas semanas: el CLAUDE.md pasa de 20 líneas a 300 sin que nadie decida conscientemente que deba ser así.
¿Qué significa esto para los builders?
Para quien construye en producción, la lección es que el contexto es un recurso escaso y hay que gestionarlo como código. Un CLAUDE.md hinchado no solo encarece cada interacción —recuerda que pagas por tokens de entrada en cada llamada—, sino que puede empeorar el resultado justo cuando más reglas has añadido para mejorarlo.
Algunas prácticas que recomendamos:
- Trata el archivo como deuda técnica. Revísalo periódicamente y elimina reglas que respondían a bugs ya resueltos o a versiones antiguas del proyecto.
- Prioriza lo estructural sobre lo anecdótico. Convenciones de arquitectura y comandos de build merecen estar; un parche puntual para un caso que ocurrió una vez, probablemente no.
- Divide por ámbito. Claude Code admite archivos por subdirectorio, así que no todo tiene que vivir en el
CLAUDE.mdraíz. - Mide el impacto. Si notas que el agente responde peor tras semanas de añadir reglas, sospecha del archivo antes que del modelo.
Frente a alternativas como los archivos de configuración de Cursor o los system prompts de la API de OpenAI, el CLAUDE.md tiene la virtud de ser versionable en Git y legible por humanos, pero comparte el mismo talón de Aquiles: nadie lo mantiene si no se establece un proceso. Para los builders hispanohablantes esto significa incorporar la revisión del archivo a la rutina del equipo, igual que se revisa un README.
¿Cómo afecta esto a equipos en España y LATAM?
El ángulo regional es puramente económico. Los equipos en España, Colombia o México que adoptan Claude Code suelen operar con presupuestos de API más ajustados que los de las grandes tecnológicas estadounidenses. Un CLAUDE.md de 300 líneas que se envía en cada una de las cientos de peticiones diarias de un equipo se traduce en euros o pesos tirados en tokens que no aportan valor.
La buena noticia es que la solución no cuesta dinero: es disciplina de mantenimiento. Para un freelance en Bogotá o una startup en Madrid, auditar el archivo una vez por sprint puede recortar el consumo de contexto sin tocar el código ni cambiar de modelo. Es de esas optimizaciones que dan rendimiento inmediato sin infraestructura extra.
¿Cómo mantener el CLAUDE.md bajo control?
Pasos accionables para empezar hoy:
- Abre tu
CLAUDE.mdy marca cada regla con la fecha o el motivo por el que se añadió. - Elimina todo lo que responda a un problema que ya no existe.
- Agrupa las instrucciones por categoría (build, estilo, prohibiciones) para detectar contradicciones.
- Establece un límite blando —por ejemplo, 100 líneas— que obligue a decidir qué entra y qué sale.
- Versiona los cambios: si el agente empeora, puedes revertir a un archivo más limpio.
Quien quiera profundizar en flujos de trabajo con el agente encontrará útil un recorrido para dominar el desarrollo con IA en el terminal, donde estas prácticas de gestión de contexto se vuelven parte del día a día.
El paper pone nombre a una intuición que muchos teníamos: acumular instrucciones no es lo mismo que enseñar mejor al agente. El insight que añadimos desde la redacción es que el CLAUDE.md debería tener un ciclo de vida propio —con poda incluida— y no crecer como sedimento. Un archivo pequeño y vigente casi siempre rinde más que uno enorme y desactualizado. Cuidar tu CLAUDE.md es, hoy, una de las optimizaciones más baratas y rentables al construir con Claude Code. Comparte este artículo si te fue útil.
