225,000 estrellas para un Markdown: Karpathy en cuatro reglas

Un repositorio que contiene un solo archivo Markdown tiene 225,000 estrellas. Esta semana ganó unas 4,000 más. No hay código, ni paso de compilación, ni release, ni tabla de benchmarks: solo cuatro principios y un conjunto de instrucciones sobre cómo debe comportarse un modelo de lenguaje cuando se le pide modificar una base de código.

El archivo se llama CLAUDE.md, está en un repositorio llamado andrej-karpathy-skills y lo mantiene forrestchang. Comprime una serie de reproches que Andrej Karpathy hizo sobre el comportamiento de los LLM al programar en algo que un agente sí leerá al inicio de cada sesión. El dato interesante es el número de estrellas, no el contenido, porque sugiere algo sobre cómo se está parcheando hoy el comportamiento de los agentes: de forma oficiosa, en prosa y por individuos.

Las quejas, en palabras de Karpathy

Tres citas del texto original sobre el que se construye el repositorio:

«Los modelos hacen suposiciones equivocadas en tu nombre y siguen adelante con ellas sin comprobar nada. No gestionan su confusión, no piden aclaraciones, no señalan incoherencias, no plantean contrapartidas, no discuten cuando deberían.»

«Les encanta complicar el código y las API, inflar las abstracciones, no limpiar el código muerto... implementan una construcción hinchada de más de 1,000 líneas cuando 100 bastarían.»

«Todavía a veces cambian o eliminan, como efecto secundario, comentarios y código que no entienden del todo, incluso cuando es ortogonal a la tarea.»

Quien haya entregado código escrito por un agente reconoce las tres. La segunda es la más común: pides una función de validación y recibes una clase base abstracta, un patrón estrategia, un objeto de configuración y cuarenta líneas de manejo de errores para estados que no pueden ocurrir.

Qué dicen en realidad los cuatro principios

Pensar antes de programar. Enunciar las suposiciones en voz alta, presentar varias interpretaciones en lugar de elegir una en silencio, discutir cuando existe un enfoque más simple, detenerse cuando hay confusión y nombrar qué es lo que no está claro.

La simplicidad primero. El mínimo código que resuelve el problema. Sin funciones más allá de lo pedido, sin abstracciones para código de un solo uso, sin configurabilidad que nadie pidió, sin manejo de errores para escenarios imposibles. La prueba: ¿un ingeniero senior diría que esto está sobredimensionado?

Cambios quirúrgicos. Tocar solo lo imprescindible. No mejorar el código adyacente ni reformatear lo que uno solo atraviesa. Respetar el estilo existente aunque uno lo haría distinto. Si se ve código muerto no relacionado, mencionarlo, no borrarlo. Si tus cambios generan huérfanos, limpia solo esos. La prueba: cada línea modificada se remonta a la petición.

Ejecución guiada por objetivos. Convertir instrucciones imperativas en criterios de éxito verificables. No «añade validación», sino «escribe tests para entradas inválidas y haz que pasen». No «arregla el bug», sino «escribe un test que lo reproduzca y haz que pase».

El último es el único principio que no es una contención. Es palanca, y viene con la mejor frase del material original: los LLM son excepcionalmente buenos iterando hasta cumplir objetivos concretos. No le digas qué hacer; dale criterios de éxito y míralo trabajar.

Instalación, y el hecho de que sean dos líneas

Dos rutas, ambas triviales.

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

O, por proyecto:

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

También hay una regla de Cursor versionada en .cursor/rules/karpathy-guidelines.mdc, de modo que la misma guía se aplica cuando el proyecto se abre en Cursor. Licencia MIT.

La historia de la distribución es el punto. Hace dos años, arreglar «los modelos sobreingenierizan» habría significado un fine-tuning, un system prompt distribuido por un proveedor o un framework. Ahora es un archivo que un usuario deja caer en un repositorio, más una entrada de marketplace que lo instala en todos los proyectos de esa máquina. El bucle de retroalimentación entre la queja y la corrección es mucho más corto, y por eso el contador de estrellas está donde está: el archivo es la unidad más barata posible de cambio de comportamiento.

Por qué sigo siendo escéptico ante este marco

Tres reservas, planteadas con el espíritu del propio archivo.

Los principios no son tests. «La simplicidad primero» es una preferencia, no un criterio. Un agente que lo lea seguirá produciendo una solución de 300 líneas donde bastarían 80, porque el modelo no tiene forma de medir la complejidad. El único principio del archivo que funciona de verdad —la ejecución guiada por objetivos— funciona precisamente porque sustituye una preferencia por una comprobación: un test que pasa o no pasa.

«Cambios quirúrgicos» pelea contra aquello en lo que los agentes son buenos. Si pides un cambio pequeño y recibes un cambio pequeño, has usado una herramienta cara para ahorrarte pulsaciones. El valor de un agente es que puede reestructurar algo que tú no querías tocar. La respuesta del archivo es que la reestructuración debe pedirse, no ofrecerse: razonable, pero significa que la guía está optimizada para un tipo concreto de usuario, alguien con una base de código existente y una opinión firme sobre los diffs.

Nadie mide si funciona. El repositorio enumera señales: menos cambios innecesarios en los diffs, menos reescrituras, preguntas de aclaración antes de implementar en vez de después. Son reales y observables. Pero no hay condición de control. Instalas un archivo que dice «pregunta antes de suponer» y ahora el agente pregunta antes de suponer. ¿Lo causó el archivo, o el hecho de escribirlo te hizo notar un comportamiento que ya estaba ahí?

El autor es honesto sobre la contrapartida, y hay que reconocérselo: la guía se inclina por la cautela antes que por la velocidad, y en tareas triviales conviene usar el criterio propio. Es la advertencia correcta y también es la tensión. Un agente que se detiene a preguntar por una errata de una línea es peor que uno que la arregla.

La versión que yo escribiría

Si la debilidad del archivo es que tres de sus cuatro principios son preferencias, el remedio es convertirlos en comprobaciones. En concreto, cuatro líneas que sobreviven al contacto con un repositorio real:

Antes de editar, enumera los archivos que piensas tocar y detente si la lista es más larga de lo que implica la petición. Eso convierte «cambios quirúrgicos» en una puerta y no en un estado de ánimo.

Antes de terminar, ejecuta los tests y pega la salida. Eso hace que «ejecución guiada por objetivos» no sea negociable, y es la instrucción con más palanca que puedes poner delante de un agente.

Si una tarea admite más de una interpretación plausible, escribe las dos y pregunta cuál. Eso convierte «pensar antes de programar» de una aspiración en un turno de la conversación.

Y un presupuesto de diff: si el cambio añade más de unas 150 líneas para un arreglo de bug, detente y justifica cada abstracción. Es tosco, pero atrapa el modo de fallo que describió Karpathy, el que de verdad cuesta tiempo.

Nada de eso está en el archivo, y no hace falta. La tarea del archivo es fijar una postura. Las comprobaciones son tarea de quien es dueño del repositorio.

Qué dice en realidad el número de estrellas

La mayor parte del tooling para agentes publicado este año va de capacidad: contexto más largo, más herramientas, ejecución en paralelo. Este archivo va de contención, y recibió más atención que la mayoría de los lanzamientos de capacidad.

Esa brecha es reveladora. Quienes pagan por estas herramientas han concluido que el cuello de botella ya no es lo que el modelo puede hacer, sino conseguir que deje de hacer cosas que nadie le pidió. Un archivo Markdown con 225,000 estrellas es una señal inusualmente clara de dónde está de verdad la frustración.

También es una señal algo incómoda para los laboratorios. El repositorio con más estrellas de esta categoría es una lista de cuatro cosas que los modelos ya deberían estar haciendo.