Guía para empezar con karpathy-guidelines: las normas recomendadas para programar con modelos grandes por Andrej Karpathy

Dificultad: nivel inicial | Duración: ~15 minutos | Aporte: dominar 4 principios + ser capaz de programar con AI siguiendo las normas de karpathy-guidelines

Público objetivo

• Desarrolladores que ya usan asistentes de código con IA como Claude Code, Cursor o Copilot
• Personas con 1-5 años de experiencia en desarrollo que quieren que el código que genera la IA sea más preciso, menos “relleno” y que no altere cosas sin control
• Ya con cierta práctica en programación con IA y buscando una forma de colaboración más sistemática

Dependencias y entorno

Estructura completa del proyecto (árbol)

andrej-karpathy-skills/
├── CLAUDE.md                # Archivo de guía principal (versión concisa de 4 principios; se usa con el plugin y con el archivo de forma compartida)
├── README.md                # Instrucciones de instalación y uso
├── EXAMPLES.md              # Muchos ejemplos prácticos de “a favor y en contra”
└── skills/
    └── karpathy-guidelines/  # Formato del plugin para Claude Code (método recomendado)

---

1. Primero entiende el problema: ¿por qué los LLM “se inventan cosas”?

A finales de 2025, Andrej Karpathy publicó un tuit señalando el problema central de la programación con modelos grandes tal como se practica hoy:

"The models make wrong assumptions on their own behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

En español: Los LLM hacen supuestos por su cuenta, siguen adelante sin comprobar; no gestionan su propia confusión, no piden aclaraciones, no sacan a la luz inconsistencias, no presentan compromisos y no se plantan cuando deberían.

Casi todo desarrollador que usa AI a fondo se ha topado con esto: le pides a la IA que arregle un bug pequeño y te reescribe medio módulo; le pides que agregue una función sencilla y mete tres capas de abstracción.

karpathy-guidelines está diseñado justo para estos cuatro fallos:

---

2. Instala karpathy-guidelines

Hay dos formas de instalarlo; se recomienda la primera.

Opción 1: modo plugin (recomendado)

# Paso 1: agregar el market de plugins
/plugin marketplace add forrestchang/andrej-karpathy-skills

# Paso 2: instalar el plugin
/plugin install andrej-karpathy-skills@karpathy-skills

Una vez instalado, Claude Code carga automáticamente esos 4 principios en cualquier proyecto.

Opción 2: descargar directamente CLAUDE.md (para cualquier proyecto)

Proyecto nuevo:

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

Proyecto existente (añadir al CLAUDE.md actual):

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

---

3. Análisis principio por principio

Principio 1: Think Before Coding

**Clave: ** No asumas. No escondas la confusión. Presenta activamente los compromisos.

Es la regla que más contradice el instinto natural de la IA. El objetivo de entrenamiento de una IA es “dar una respuesta”. Cuando recibe instrucciones ambiguas, tiende a inventar una interpretación que parezca razonable y seguir ejecutando, en lugar de detenerse para preguntar: “¿A qué te refieres exactamente?”.

La forma correcta de abrirlo es así:

# El usuario dice: "Haz la búsqueda más rápida"

# ❌ Lo típico que haría la IA: añade en silencio caché, índices y procesamiento asíncrono; escribe 200 líneas de una vez
@lru_cache(maxsize=1000)
async def search(query: str) -> List[Result]:
    # ... un montón de código de optimización
    pass

# ✅ Lo que exige karpathy-guidelines:
"""
"Hacer la búsqueda más rápida" puede entenderse de varias maneras:
1. Respuesta más rápida (< 100 ms): añadir índices de base de datos + caché; estimación 2 horas
2. Mayor rendimiento de concurrencia (throughput): reconvertir a asíncrono + pool de conexiones; estimación 4 horas
3. Mayor velocidad percibida (UX): carga progresiva; estimación 3 horas

¿Cuál es la que quieres?
"""

Cuando la instrucción es ambigua, detenerse para aclarar antes suele ser mucho más eficiente que acabar haciendo y luego tener que rehacer.

A nivel de código, este principio te exige:

• Explicitar tus suposiciones; lo que no sepas, preguntar
• Si hay varias interpretaciones razonables, listarlas todas para que el usuario elija
• Si aparece una solución más simple, proponerla activamente
• Si algo no está claro, detenerse de inmediato para preguntar

---

Principio 2: Simplicity First

**Clave: ** Escribe solo el código mínimo necesario para resolver el problema actual; no hagas diseño predictivo.

La IA tiene una tendencia: meter “best practices” a la fuerza, incluso cuando en este momento no hacen falta. Le pides que escriba un cálculo de descuento y podría montarte una arquitectura completa con Strategy + Factory + una clase de configuración.

Mira esta comparación real:

Solicitud del usuario: "Agregar una función para calcular descuentos"

# ❌ Lo que haría la IA normalmente: introducir abstracciones innecesarias
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Protocol, Union

class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float:
        pass

class PercentageDiscount(DiscountStrategy):
    def __init__(self, percentage: float):
        self.percentage = percentage
    def calculate(self, amount: float) -> float:
        return amount * (self.percentage / 100)

@dataclass
class DiscountConfig:
    strategy: DiscountStrategy
    min_purchase: float = 0.0
    max_discount: float = float('inf')

class DiscountCalculator:
    def __init__(self, config: DiscountConfig):
        self.config = config
    def apply_discount(self, amount: float) -> float:
        # ... un montón de código

# Para usarlo, necesitas preparar 30+ líneas

# ✅ Enfoque Simplicity First:
def calculate_discount(amount: float, percent: float) -> float:
    """Calcula el importe del descuento. percent es un porcentaje; por ejemplo, 10 significa 10%"""
    return amount * (percent / 100)

# Uso
discount = calculate_discount(100.0, 10.0)  # 90 de descuento (es decir, 10%)

Criterios para juzgar este principio:

• No añadir funcionalidades que nadie pidió
• No abstraer código que se usa una sola vez
• No reservar “flexibilidad” si no se necesita
• Si no puede ocurrir un escenario con error, no escribir el manejo de errores
• Después de escribir el código, preguntarte: “¿Esto es un sobre-diseño para un ingeniero senior?” Si lo es, reescribe

---

Principio 3: Surgical Changes

**Clave: ** Cambia solo lo que es imprescindible; limpia la basura que causes tú, pero no toques lo que ya estaba bien.

Cuando la IA arregla un bug, suele ser especialmente fácil caer en “optimizar de paso”: cambiar 3 líneas del bug y aprovechar para cambiar nombres de variables, ajustar formato, cambiar comentarios. karpathy-guidelines exige precisión de nivel “cirugía”.

Un escenario típico: el usuario dice “arregla el problema del validador cuando el email está vacío”

  def validate_user(user_data):
-     # Check email format
-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")
-     # Basic email validation
-     if '@' not in user_data['email']:
+     if '@' not in email:
          raise ValueError("Invalid email")
-     # Check username
-     if not user_data.get('username'):
+     # Check username  ← así como estaba antes, se escribe igual
+     if not user_data.get('username'):
          raise ValueError("Username required")
      return True

❌ Lo que suele hacer la IA (más allá del alcance del usuario):

# Y encima agrega:
# - Validación de formato de email más estricta (expresiones regulares)
# - Validación de longitud para el nombre de usuario
# - Validación de caracteres del nombre de usuario
# - docstring
# - Cambió el estilo de comillas ('' → "")

✅ Lo que exige Surgical Changes (solo cambiar las dos líneas relacionadas con el email vacío):

-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")
-     if '@' not in user_data['email']:
+     if '@' not in email:
          raise ValueError("Invalid email")

Criterio: cada línea de código modificada debe poder rastrearse hasta la solicitud concreta del usuario.

---

Principio 4: Goal-Driven Execution

**Clave: ** Traduce “qué hay que hacer” a “cómo se valida que se consiguió”. Sustituye instrucciones ambiguas por criterios de éxito.

Este es uno de los puntos más enfocados por Andrej Karpathy: “Los LLM son muy buenos ejecutando en bucle hasta alcanzar un objetivo específico. En vez de decirle qué hacer, dáselo en términos de criterios de éxito y deja que corra por su cuenta.”

Compara ambas formas de dar instrucciones:

❌ Instrucción ambigua (la IA no sabe hacia dónde ir):

Arreglar el problema del sistema de inicio de sesión

✅ Instrucción Goal-Driven (dirección clara para la IA):

Problema concreto del sistema de inicio de sesión: después de que el usuario cambie la contraseña, la sesión antigua no se invalida.

Plan:
1. Escribir pruebas: cambiar contraseña → verificar que la sesión antigua es rechazada
   Validación: las pruebas fallan (se reproduce el bug)

2. Implementar: al cambiar la contraseña, limpiar las sesiones del usuario correspondiente
   Validación: las pruebas pasan

3. Casos borde: inicio de sesión en varios dispositivos, cambios de contraseña concurrentes
   Validación: todas las pruebas nuevas pasan

4. Verificación de regresión: asegurar que todas las pruebas relacionadas con login existentes pasan
   Validación: pnpm test

Cobertura de pruebas del módulo de login actual: [datos]
Dime exactamente qué problema de login estás encontrando.

Formato estándar para tareas de varios pasos:

1. [Descripción del paso] → Validación: [método de validación]
2. [Descripción del paso] → Validación: [método de validación]
3. [Descripción del paso] → Validación: [método de validación]

La ventaja de esto es que: en cada paso, la IA tiene una lista de verificación clara con la que contrastar; no necesita estar confirmando repetidamente “¿así está bien o no?”.

---

4. Cómo verificar si la guía está funcionando

Después de instalar karpathy-guidelines, puedes evaluar si está teniendo efecto en estos aspectos:

Calidad del diff:

• ¿Los cambios son todos los que pidió el usuario?
• ¿Hay “optimización de paso” innecesaria?
• ¿Se cambió el estilo de comillas, comentarios o docstring sin autorización?

Momento de preguntar:

• ¿La IA se detiene y pregunta cuando la instrucción es ambigua?
• ¿O simplemente asume una interpretación y empieza a escribir?

Complejidad del código:

• ¿El código nuevo es exactamente lo necesario?
• ¿Hay abstracción o diseño excesivo?

Si esos tres aspectos mejoran, significa que la guía está funcionando.

---

5. Cómo combinarlo con el CLAUDE.md existente del proyecto

La mayoría de los proyectos ya tienen su propio CLAUDE.md; si lo reemplazas directamente, perderás configuraciones previas. La forma correcta es añadir y no sustituir:

# Primero confirma el contenido actual del CLAUDE.md
cat CLAUDE.md

# Luego combínalo manualmente con un editor, o bien:
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Estructura recomendada tras la combinación:

# Descripción del proyecto (mantén el contenido original)

---

# karpathy-guidelines (nuevo contenido, PS: recomendado por Andrej Karpathy)

[Aquí pega el contenido de CLAUDE.md]

---

## Normas específicas del proyecto

- Usar el modo estricto de TypeScript (strict)
- Todos los endpoints de la API deben tener tests
- Seguir el patrón de manejo de errores definido en src/utils/errors.ts

---

Solución de problemas frecuentes

P1: ¿No se aplicó después de instalar el plugin?

# Confirmar que el plugin está cargado
/plugin list

# Si no aparece, reinicia Claude Code
# En Claude Code escribe /exit para salir y entra de nuevo

P2: ¿Qué hago si el CLAUDE.md del proyecto y el plugin entran en conflicto?

Manda el CLAUDE.md del proyecto. El plugin ofrece un comportamiento global “por si acaso”; el archivo del proyecto sobrescribe la configuración del plugin.

P3: Tareas simples también se quedan “atascadas” pidiendo confirmación. ¿Qué hago?

Es normal: karpathy-guidelines exige aclarar instrucciones ambiguas para todo tipo de tareas. Para tareas claramente simples (por ejemplo, “cambiar la variable a por b”), puedes especificar explícitamente en el prompt: “es un reemplazo simple, hazlo directamente”. Entonces la IA saltará el paso de confirmación.

P4: La IA no respeta Surgical Changes y sigue cambiando el formato. ¿Cómo evitarlo?

Limita explícitamente el alcance de los cambios en la instrucción:

Cambia solo la validación de valores vacíos dentro de la función validateEmail; no toques ningún otro código ni el formato.

P5: Después de combinar CLAUDE.md hay conflictos. ¿Cómo resolverlos?

Edita CLAUDE.md manualmente, mantén el contenido original y los principios recién añadidos, evitando duplicar párrafos. Si en dos lugares se definen los mismos principios, manda la norma concreta del CLAUDE.md original del proyecto.

P6: ¿Hay que aplicar estos principios retroactivamente a proyectos existentes?

No. karpathy-guidelines restringe el comportamiento de los cambios a partir de ahora, no te obliga a refactorizar el código existente. Úsalo para guiar las nuevas interacciones de programación.

---

Lecturas recomendadas y caminos de nivel avanzado

• El tuit original de Andrej Karpathy —— observaciones sobre el origen de las trampas al programar con LLM
• forrestchang/andrej-karpathy-skills —— repositorio GitHub del proyecto, que incluye un EXAMPLES.md completo (vale mucho la pena leerlo porque tiene muchos ejemplos positivos y negativos)
• Documentación oficial de Claude Code —— para conocer las capacidades completas de la CLI y las opciones de configuración
• Tutorial de integración con OpenClaw —— si quieres explorar más a fondo prácticas locales de AI Agent, OpenClaw ofrece capacidades de llamadas a herramientas más profundas

---

Caminos de nivel avanzado

Después de dominar los cuatro principios, puedes seguir explorando estas direcciones:

Extensiones personalizadas: añade en CLAUDE.md normas de codificación específicas del proyecto para que la IA mantenga las restricciones generales de karpathy-guidelines y, además, respete el estilo propio del proyecto.

Compartir con el equipo: integra karpathy-guidelines dentro de la documentación de normas de codificación del equipo; así, cuando los nuevos integrantes clonen el proyecto, obtienen automáticamente las pautas de comportamiento para programar con AI.

Cuantificar el efecto: registra cuántas veces hay que rehacer código con la IA antes y después de introducir la guía, el alcance de los cambios y el número de cambios no relacionados en los PR, y valida con datos el valor real de esta metodología.