Cuando la Documentación se Convierte en un Cajón de Sastre

Imagina esto: inicias un nuevo proyecto con un archivo CLAUDE.md limpito. Pones algunas pistas útiles. Un par de notas de contexto. Una advertencia sobre ese caso extraño en tu flujo de autenticación. Meses después, abres el archivo y parece una novela interminable de instrucciones que se contradicen, recordatorios obsoletos y apéndices desesperados que nadie entiende del todo.

Y no es solo tu experiencia. Es algo universal.

El Problema del Crecimiento Sin Límites

Una investigación que analizó 247.694 instrucciones durante su vida útil en 1.867 repositorios reveló algo impactante: los prompts agentivos no solo crecen, sino que lo hacen sin control alguno. Más del triple a lo largo de su vida útil (+226%). En promedio, estos archivos ganan +4,9 instrucciones netas con cada commit. El archivo nunca se encoge. Solo se expande.

Pero lo verdaderamente fascinante es esto: mientras más antigua es una instrucción, menos probable es que alguien la elimine. Los datos muestran un hazard logarítmico de -0,032 por commit. Las instrucciones se vuelven cada vez más inmortales con el tiempo. No es que nadie quiera hacer limpieza. Es que nadie sabe si puede eliminar algo de forma segura.

La Paradoja de Agregar vs. Eliminar

¿Por qué pasa esto? Los investigadores lo llaman "recuerdo catastrófico", la versión inversa del famoso "olvido catastrófico" en machine learning. Pero no necesitas un doctorado para entenderlo.

Piénsalo desde el costo: agregar una instrucción es barato. Ves un problema, escribes la solución, sigues adelante. El costo inmediato es bajo y el beneficio percibido es claro.

Eliminar una instrucción es otra historia. Tienes que entender cada lugar donde esa instrucción podría importar. Razonar sobre las interacciones con todas las demás. Verificar que quitarla no rompa algo sutil e importante. Los investigadores calcularon este costo cognitivo como O(2^|D|) en un prompt con |D| instrucciones. Es decir, crece exponencialmente con el número de instrucciones existentes.

Así que los desarrolladores hacen lo racional: dejan de intentarlo. Se anexan nuevas instrucciones. Las viejas permanecen. El archivo crece.

Los Comentarios: los Héroes Olvidados

Aquí es donde la investigación se pone interesante. La solución no está en técnicas de prompting más sofisticadas ni en modelos más inteligentes. Está en algo que los desarrolladores han usado desde el inicio de la programación: los comentarios.

Los investigadores tomaron un enfoque peculiar. Invertieron IFEval, un benchmark estándar, para crear "mundos verificables" donde los prompts óptimos son conocidos. Cuando añadieron comentarios que codifican el razonamiento latente, el crecimiento excesivo de instrucciones cayó de +211,3% a apenas +1,4%.

Eso es una reducción del 99,3%.

Pero lo mejor de todo: estos comentarios no solo controlaron el crecimiento, sino que mejoraron el rendimiento real en el seguimiento de instrucciones hasta un 23,1% en tareas del mundo real. Los comentarios no son desorden organizativo. Son estructuras de carga que ayudan a los asistentes de IA a razonar correctamente sobre el contexto.

Por Qué Importa Ahora

Estamos viviendo un cambio fundamental en lo que significa "código". Los investigadores plantean una pregunta provocadora: "¿Si el inglés es el nuevo código, por qué todavía no tenemos comentarios?"

Es un punto válido. Durante décadas, los desarrolladores han entendido que el código sin comentarios es deuda técnica. Los comentarios explican el "por qué", no solo el "qué". Capturan la intención, los casos edge y el conocimiento institucional que no se puede inferir de la sintaxis.

Sin embargo, en nuestra prisa por delegar cada vez más a los asistentes de código con IA, hemos tratado las instrucciones en lenguaje natural como si fueran distintas. Escribimos imperativos: haz esto, no hagas aquello, recuerda verificar X, sin explicar nuestro razonamiento.

El resultado es lo que vemos en esos archivos CLAUDE.md que se inflan sin control: instrucciones que nadie entiende del todo, que pueden contradecirse entre sí, y que crecen sin ningún mecanismo de racionalización.

El Camino Adelante

Si mantienes un archivo CLAUDE.md o un prompt agentivo similar, esto es lo que sugiere la investigación:

1. Comenta tus instrucciones, no solo tu código. Explica por qué existe una regla. Documenta los casos edge. Captura el razonamiento detrás de las decisiones.

2. Abraza la racionalización periódica. No solo anexes, reescribe. La investigación señala explícitamente que las reescrituras completas son una de las pocas cosas que detienen el crecimiento.

3. Trata tus instrucciones de IA como documentación de onboarding. ¿Le darías a un nuevo desarrollador un archivo de 400 líneas de reglas indiferenciadas? Tu asistente de IA merece la misma claridad.

La trayectoria en la que estamos no es sostenible. Cada nuevo proyecto empieza con buenas intenciones y termina en un desastre inmanejable. Pero la solución quizás sea más simple de lo que pensábamos: escribe para el humano (o la IA) que leerá tus instrucciones en seis meses, no solo para el que responde tu pregunta hoy.

Los comentarios no son desorden. Son la arquitectura del entendimiento.