Reglas de codificación LLM de Andrej Karpathy: Think, Simplify y Iterate

Los modelos de lenguaje grande, como Claude, tienen un gran potencial para la generación de código, pero también pueden producir resultados desordenados, sobreingenierizados o incluso incorrectos. Andrej Karpathy, pionero en el campo, destiló sus observaciones en cuatro principios que ayudan a los desarrolladores a escribir código fiable y limpio con Claude. Este tutorial recorre cada regla, explica por qué importa y muestra cómo integrar las pautas en tu propio flujo de trabajo.

1. Think Before Coding

Objetivo: Exponer supuestos, aclarar ambigüedades y rechazar decisiones cuando existen opciones más seguras.

Cuando Claude lee una tarea, a menudo infierne una interpretación y procede sin preguntar. Esto puede llevar a confusión oculta o a compensaciones erróneas.

• Expresa explícitamente los supuestos: Comienza tu prompt con una breve lista de lo que supones.
• Pide aclaraciones: Si un requisito es vago, primero genera una pregunta para el usuario.
• Presenta alternativas: Ofrece múltiples enfoques viables en lugar de comprometerte con uno.
• Detén el proceso cuando tengas dudas: Nombra lo que no te queda claro y solicita más contexto antes de codificar.

Consejo práctico: agrega un bloque de comentario al inicio de cada archivo que generas con un breve esquema de supuestos y la estrategia elegida.

2. Simplicity First

Objetivo: Priorizar el código más simple que cumpla la especificación.

Claude ama explorar cada posible abstracción y a menudo produce soluciones de 1.000 líneas cuando una de 50 líneas bastaría. La sencillez reduce la carga cognitiva para futuros desarrolladores y reduce la superficie de fallos.

• Elimina características innecesarias: No añadas argumentos opcionales a menos que la especificación los exija explícitamente.
• Evita una infraestructura genérica: Si una función auxiliar pequeña resuelve el problema, escríbela; no construyas una clase completa por si crees que podrías reutilizarla.
• Mantén el manejo de errores realista: Gestiona solo los caminos de error realistas. No protejas estados imposibles.
• Aplica la regla «más de 200 líneas = 50 líneas»: Cuando el código supere las 200 líneas, refactorízalo o elimínalo.

Usa la Prueba de Ingeniero Senior: ¿Diría un ingeniero senior que esto está sobrecomplicado? Si la respuesta es sí, simplifica.

3. Surgical Changes

Objetivo: Modificar únicamente lo que el usuario solicita explícitamente.

Al ajustar código existente, Claude a veces se extiende a secciones no relacionadas, alterando comentarios o refactorizando código que funcionaba correctamente.

• No toques código no relacionado: Limita los cambios a las líneas que abordan directamente la solicitud.
• Mantén el estilo: Preserva la guía de estilo del proyecto; imita los patrones existentes.
• No elimines código muerto preexistente: Si notas una función abandonada, simplemente mándala notar—no la borres a menos que se solicite.
• Limpia después de ti: Elimina importaciones o variables que tus cambios dejaron sin uso.

Después de un cambio, ejecuta un bucle de revisión diff para confirmar que no haya modificaciones inesperadas.

4. Goal‑Driven Execution

Objetivo: Definir criterios de éxito claros y repetir hasta verificarlos.

Este principio aprovecha la fortaleza de Claude de iterar hasta que se cumpla una condición verificable. En lugar de dar un comando imperativo, especificas el estado deseado.

• Describe la meta: por ejemplo, "Añadir validación de entrada y exponer mensajes de error a través de una respuesta API".
• Define pasos de verificación: "Escribe una prueba unitaria para entrada vacía; ejecuta y confirma fallo; añade validación; vuelve a ejecutar y confirma éxito."
• Crea un plan corto con checkpoints paso a paso.
• Repite: Después de cada cambio, pide a Claude que ejecute o evalúe las pruebas.

Ejemplo de pseudocódigo:

1. Añadir una prueba unitaria para entrada vacía → Verificar fallo.
2. Insertar lógica de validación → Verificar fallo.
3. Ajustar lógica para pasar la prueba → Verificar éxito.

Cómo instalar las pautas

El repositorio contiene un único archivo CLAUDE.md que puedes añadir a cualquier proyecto.

# Opción A: Como plugin CLI de skills
npx skills add forrestchang/andrej-karpathy-skills

# Opción B: Copia directa del archivo
# Para un nuevo proyecto
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md 

# Para un proyecto existente (añadiendo)
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Una vez presente el archivo, plantea Claude con el formato Goal‑Driven Execution: "Añade validación de datos; escribe pruebas que lo detecten; ejecuta hasta que las pruebas pasen." Claude hará referencia a las pautas automáticamente.

Caso de uso práctico

Escenario: Un equipo está construyendo una API sencilla de registro de usuarios. Quieren: 1. Aceptar name, email y password. 2. Validar el formato del email. 3. Rechazar correos duplicados. 4. Almacenar el hash de la contraseña.

Con las reglas de Karpathy:

1. Think before coding – preguntar si la API debería devolver un 409 para duplicados o un 400 genérico.
2. Simplicity first – usar un único helper para la validación de email en lugar de un servicio externo completo.
3. Surgical changes – modificar únicamente el archivo del controlador, no el middleware.
4. Goal-driven – especificar los criterios de éxito: pruebas unitarias para entradas válidas e inválidas.

Claude generará código mínimo y bien estructurado que se adhiera al estilo del proyecto, y el desarrollador podrá revisar un pull request limpio con solo los cambios requeridos.

Resumen

Adoptar los cuatro principios de Karpathy puede reducir drásticamente el ruido y los errores que experimentas al usar LLMs para codificar. Al poner de relieve las suposiciones, la sencillez, la precisión en las modificaciones y los objetivos explícitos, los desarrolladores pueden aprovechar el poder de Claude mientras mantienen su base de código mantenible y fiable.

Prueba añadiendo CLAUDE.md a tu próximo proyecto y observa cómo tu código se repite de manera más inteligente, y tus revisiones se vuelven menos y más focalizadas.