En el mundo de la programación asistida por IA, que evoluciona rápidamente, un repositorio de GitHub ha surgido como el conjunto de pautas de comportamiento más popular para los agentes de programación de IA: forrestchang/andrej-karpathy-skills. Creado por el desarrollador Forrest Chang, sintetiza las observaciones virales de Andrej Karpathy sobre los errores comunes al programar con LLM en un único y práctico CLAUDE.md archivo. Lo investigamos en GitHub, Twitter/X, Reddit, artículos web y el propio código fuente — aquí tienes la guía definitiva.
Get the latest on AI, LLMs & developer tools
New MCP servers, model updates, and guides like this one — delivered weekly.
🎬 Mira el desglose en video
¿Prefieres leer? Sigue bajando para ver la guía escrita completa con ejemplos de código.
1. Por qué se volvió viral
Empecemos por qué este repo es importante. Se convirtió en uno de los repositorios de más rápido crecimiento en GitHub — decenas de miles de estrellas en sus primeras semanas — para un repo que contiene esencialmente un solo archivo.
Ni un framework, ni una librería, ni una app. Un único conjunto de pautas de comportamiento para agentes de programación con IA. Creado el 27 de enero de 2026, publicado bajo la licencia MIT, y sigue creciendo. Eso te dice algo importante sobre hacia dónde se dirige la industria.
Por qué esto es importante
Muchas herramientas populares de código abierto con miles de colaboradores y años de desarrollo tienen menos estrellas. Este repo se volvió viral con un puñado de commits y cero dependencias de tiempo de ejecución. El valor no está en el código — está en las ideas.
2. La historia del origen
El repositorio se remonta directamente a un tweet viral de Andrej Karpathy — cofundador de OpenAI, exlíder de IA en Tesla y la persona que acuñó el término “vibe coding.” En su publicación, Karpathy no compartió una herramienta ni un repositorio. Compartió observaciones — una lista de frustraciones sobre cómo se comportan los LLM al escribir código.
Algunas notas aleatorias de programar con Claude bastante durante las últimas semanas.
— Andrej Karpathy (@karpathy) 26 de enero de 2026
Flujo de trabajo de programación. Dado el reciente salto en la capacidad de programación de los LLM, al igual que muchos otros, pasé rápidamente de aproximadamente un 80% de programación manual+autocompletado y un 20% de agentes en noviembre a un 80% de programación con agentes y un 20% de ediciones+retoques en…
El desarrollador Forrest Chang leyó estas observaciones e hizo algo práctico: las convirtió en un formato estructurado y legible por máquina CLAUDE.md archivo. No es una publicación vaga en un blog. No es un hilo de Twitter. Un archivo de configuración que los agentes de IA realmente leen y siguen.
La idea clave fue esta: Karpathy identificó los problemas. Forrest Chang codificó las soluciones. La comunidad validó ambas — convirtiéndolo en uno de los repositorios de flujos de trabajo de IA con más estrellas en GitHub.
3. Los problemas que Karpathy identificó
Las observaciones de Karpathy no fueron quejas vagas. Eran patrones específicos y reproducibles que todo desarrollador que usa agentes de codificación de IA ha experimentado. Aquí están sus palabras exactas:
Problema 1: Suposiciones ocultas
“Los modelos hacen suposiciones erróneas en tu nombre y simplemente siguen adelante con ellas sin verificar. No gestionan su confusión, no buscan aclaraciones, no exponen inconsistencias, no presentan compensaciones ni se oponen cuando deberían.”
Problema 2: Sobreingeniería
“Realmente les gusta complicar demasiado el código y las APIs, inflar las abstracciones, no limpian el código muerto... implementan una construcción inflada de más de 1000 líneas cuando 100 serían suficientes.”
Problema 3: Efectos secundarios no deseados
“A veces todavía cambian o eliminan comentarios y código que no entienden lo suficiente como efectos secundarios, incluso si son ajenos a la tarea.”
Si has usado Claude Code, Copilot, Cursor o cualquier agente de codificación de IA, has sentido esto. Le pides al agente que corrija un error y reescribe la mitad del archivo. Le pides que añada una funcionalidad y construye toda una capa de abstracción. Le pides ayuda y avanza con confianza basándose en suposiciones erróneas.
La comunidad de Reddit (especialmente r/ClaudeAI y r/ClaudeCode) tiene un término muy utilizado para este comportamiento: “el desarrollador junior seguro de sí mismo.” La IA es rápida, tiene conocimientos y es propensa a cometer errores ingenuos si se deja sin supervisión. Es brillante pero poco fiable — exactamente el tipo de ingeniero que necesita límites claros.
4. Los cuatro principios
Forrest Chang sintetizó las observaciones de Karpathy en cuatro principios. Cada uno aborda directamente una clase específica de fallo de los LLM:
| Principio | Aborda |
|---|---|
| Pensar antes de programar | Suposiciones erróneas, confusión oculta, ausencia de tradeoffs |
| La simplicidad ante todo | Sobrecomplicación, abstracciones excesivas, funcionalidades especulativas |
| Cambios quirúrgicos | Ediciones ortogonales, tocar código que no deberías, desviación de estilo |
| Ejecución orientada a objetivos | Implementación vaga, sin verificación, criterios de éxito débiles |
Analicemos cada uno en detalle.
Principio 1: Pensar antes de programar
“No asumas. No ocultes la confusión. Expón los tradeoffs.”
Este es el principio más fundamental. Los LLM tienden a elegir una interpretación en silencio y seguir adelante con ella. Este principio obliga a un razonamiento explícito:
- Declara las suposiciones explícitamente — Si tienes dudas, pregunta en lugar de adivinar
- Presenta múltiples interpretaciones — No elijas en silencio cuando haya ambigüedad
- Cuestiona cuando sea necesario — Si existe un enfoque más sencillo, dilo
- Detente cuando haya confusión — Identifica qué no está claro y pide una aclaración
Ejemplo: La trampa de las suposiciones ocultas
Solicitud del usuario: “Add a feature to export user data”
def export_users(format='json'):
users = User.query.all()
# Se asumen TODOS los usuarios, ubicación del archivo, campos,
# nombres de campos CSV — sin preguntar nada
Antes de implementar, necesito aclarar:
1. Alcance: ¿Exportar todos los usuarios o un subconjunto filtrado?
(implicaciones de privacidad)
2. Formato: ¿Descarga de archivo? ¿Tarea en segundo plano?
¿Endpoint de API?
3. Campos: ¿Qué campos de usuario?
(algunos podrían ser sensibles)
4. Volumen: ¿Cuántos usuarios normalmente?
Enfoque más simple: Añadir un endpoint de API que
devuelva JSON paginado. ¿Cuál es tu preferencia?
Principio 2: La simplicidad primero
“Código mínimo que resuelva el problema. Nada especulativo.”
Esto combate la tendencia de los LLM hacia la sobreingeniería. Las reglas son estrictas:
- Sin funcionalidades más allá de lo solicitado
- Sin abstracciones para código de un solo uso
- Sin “flexibilidad” ni “configurabilidad” que no haya sido solicitada
- Sin manejo de errores para escenarios imposibles
- Si 200 líneas podrían ser 50, reescríbelo
La prueba: ¿Diría un ingeniero senior que esto es demasiado complicado? Si es así, simplifica.
Ejemplo: La trampa de la sobreabstracción
Solicitud del usuario: “Añade una función para calcular el descuento”
class DiscountStrategy(ABC):
@abstractmethod
def calculate(self, amount): ...
class PercentageDiscount(DiscountStrategy): ...
class FixedDiscount(DiscountStrategy): ...
class DiscountConfig: ...
class DiscountCalculator: ...
# Más de 50 líneas para un solo cálculo
# El uso requiere más de 30 líneas de configuración
def calculate_discount(amount, percent):
"""Calcula el descuento. percent es de 0 a 100."""
return amount * (percent / 100)
# Uso
discount = calculate_discount(100.0, 10.0) # $10 de descuento
Idea clave del repositorio
“Los ejemplos ‘sobrecomplicados’ no están obviamente mal — siguen patrones de diseño y buenas prácticas. El problema es el momento oportuno: añaden complejidad antes de que sea necesaria.” El buen código resuelve el problema de hoy de forma sencilla, no el problema de mañana de forma prematura.
Principio 3: Cambios quirúrgicos
“Toca solo lo que debas. Limpia solo tu propio desorden.”
Este es el principio que aborda más directamente la frustración de Karpathy con los LLM que realizan cambios ortogonales. Al editar código existente:
- No “mejores” el código adyacente, los comentarios o el formato
- No refactorices cosas que no estén rotas
- Mantén el estilo existente, incluso si tú lo harías de otra forma
- Si notas código muerto no relacionado, menciónalo — no lo borres
Cuando tus cambios creen huérfanos:
- Elimina las importaciones/variables/funciones que TUS cambios hayan dejado sin uso
- No elimines código muerto preexistente a menos que se te pida
La prueba: Cada línea cambiada debe rastrearse directamente hasta la solicitud del usuario.
Ejemplo: La trampa de la refactorización oportunista
Solicitud del usuario: “Corrige el error por el cual los correos vacíos hacen que el validador falle”
15 líneas cambiadas:
- Se agregó docstring (no solicitado)
- Se agregó validación de nombre de usuario (no solicitado)
- Se cambiaron los comentarios (no solicitado)
- Lógica de validación de email “mejorada” (no solicitado)
- Se agregaron llamadas a .strip() en todas partes (no solicitado)
3 líneas cambiadas:
- Se agregó protección de cadena vacía para el email
- Se cambió la referencia de la variable para evitar un crash
- No se tocó nada más.
Ejemplo: La trampa de la desviación de estilo
Solicitud del usuario: “Agregar logging a la función de carga”
The LLM adds logging — but also changes single quotes to double quotes, adds type hints nobody asked for, adds a docstring, reformats whitespace, and restructures the boolean return logic. The correct approach: add solo las líneas de logging, usando el estilo existente (single quotes, no type hints, same spacing).
Principio 4: Ejecución orientada a objetivos
“Define los criterios de éxito. Itera hasta verificar.”
Este principio resume lo que Karpathy considera la idea de mayor impacto al trabajar con LLMs:
La idea clave de Karpathy
“Los LLMs son excepcionalmente buenos iterando hasta alcanzar objetivos específicos... No le digas qué hacer, dale criterios de éxito y observa cómo avanza.”
El principio transforma tareas imperativas en objetivos declarativos:
| En lugar de... | Transformar a... |
|---|---|
| “Añadir validación” | “Escribe pruebas para entradas inválidas y luego haz que pasen” |
| “Corregir el bug” | “Escribe una prueba que lo reproduzca y luego haz que pase” |
| “Refactorizar X” | “Asegúrate de que las pruebas pasen antes y después” |
Para tareas de varios pasos, el modelo debe proponer un plan breve:
1. [Paso] → verificar: [comprobación]
2. [Paso] → verificar: [comprobación]
3. [Paso] → verificar: [comprobación]
Strong success criteria let the LLM loop
de forma independiente. Los criterios débiles (“haz que funcione”)
requieren aclaraciones constantes.
5. El archivo CLAUDE.md real
Aquí tienes el archivo completo y sin abreviar CLAUDE.md del repositorio. Es intencionalmente corto — menos de 70 líneas. Esa brevedad es una característica, no una limitación:
Guías de comportamiento para reducir errores comunes de programación
de LLM. Combínalas con las instrucciones específicas del proyecto
según sea necesario.
Tradeoff: Estas guías se inclinan hacia la precaución
sobre la velocidad. Para tareas triviales, usa tu criterio.
## 1. Piensa antes de programar
No asumas. No ocultes la confusión. Expón los tradeoffs.
Antes de implementar:
- Declara tus suposiciones explícitamente. Si tienes dudas, pregunta.
- Si existen múltiples interpretaciones, preséntalas.
- Si existe un enfoque más simple, dilo.
- Si algo no está claro, detente. Identifica qué es lo que confunde.
## 2. Simplicidad ante todo
Código mínimo que resuelva el problema. Nada especulativo.
- Sin funcionalidades más allá de lo solicitado.
- Sin abstracciones para código de un solo uso.
- Nada de “flexibilidad” que no haya sido solicitada.
- Sin manejo de errores para escenarios imposibles.
- Si 200 líneas pueden ser 50, reescríbelas.
## 3. Cambios quirúrgicos
Toca solo lo necesario. Limpia solo tu propio desorden.
- No “mejores” el código adyacente ni el formato.
- No refactorices cosas que no estén rotas.
- Respeta el estilo existente, incluso si lo harías de otra forma.
- Si notas código muerto, menciónalo — no lo borres.
## 4. Ejecución orientada a objetivos
Define criterios de éxito. Itera hasta verificar.
Transforma las tareas en objetivos verificables:
- “Añadir validación” → “Escribir pruebas y luego hacer que pasen”
- “Corregir el error” → “Reproducirlo en una prueba y luego corregirlo”
- “Refactorizar X” → “Asegurar que las pruebas pasen antes y después”
Eso es todo. El archivo completo. Su poder reside en su concisión — lo suficientemente corto para caber en la ventana de contexto del agente sin desplazar las instrucciones específicas del proyecto, y lo suficientemente largo para establecer las barreras de comportamiento críticas.
6. Ejemplos del mundo real
El repositorio incluye un EXAMPLES.md archivo con comparaciones detalladas de antes y después. Aquí está el “resumen de anti-patrones” clave del archivo:
| Principio | Anti-patrón | Solución |
|---|---|---|
| Pensar antes de programar | Asume silenciosamente el formato de archivo, los campos y el alcance | Listar las suposiciones explícitamente, pedir aclaraciones |
| La simplicidad primero | Patrón Strategy para un solo cálculo de descuento | Una sola función hasta que la complejidad sea realmente necesaria |
| Cambios quirúrgicos | Reformats quotes, adds type hints while fixing a bug | Cambiar solo las líneas que corrigen el problema reportado |
| Orientado a objetivos | “Revisaré y mejoraré el código” | “Escribir prueba para el error X → hacer que pase → verificar que no haya regresiones” |
7. Cómo instalar
El repositorio ofrece dos métodos de instalación:
Opción A: Claude Code Plugin (Recomendado)
Esto instala las guías como un Claude Code plugin, haciendo que la habilidad esté disponible en todos tus proyectos:
/plugin marketplace add forrestchang/andrej-karpathy-skills
# Luego instala el plugin
/plugin install andrej-karpathy-skills@karpathy-skills
Opción B: CLAUDE.md (Por proyecto)
Para un solo proyecto:
curl -o CLAUDE.md https://raw.githubusercontent.com/
forrestchang/andrej-karpathy-skills/main/CLAUDE.md
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/
andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
Personalización
Estas guías están diseñadas para ser fusionadas con instrucciones específicas del proyecto. Añade tus propias secciones para la configuración de TypeScript, estándares de API, convenciones de pruebas o lo que tu proyecto necesite. Los cuatro principios proporcionan la base de comportamiento; las reglas de tu proyecto se construyen sobre ellos.
8. ¿Qué es CLAUDE.md?
Para quienes no estén familiarizados con el concepto: CLAUDE.md es un Tarjeta de Memoria del Proyecto para agentes de codificación de IA. Claude Code lo lee automáticamente al inicio de cada sesión, proporcionando un contexto persistente que se mantiene a través de las conversaciones.
Piénsalo como el equivalente para la IA de la documentación de onboarding para un nuevo desarrollador — excepto que la IA la lee cada vez que comienza a trabajar en tu proyecto.
Mejores Prácticas para CLAUDE.md (2026)
| Sección | Contenido |
|---|---|
| Descripción General del Proyecto | Resumen de 2 a 3 oraciones sobre lo que hace el proyecto |
| Stack Tecnológico | Lenguajes, frameworks, librerías clave |
| Arquitectura | Mapa del codebase (source, components, config) |
| Comandos | comandos de dev, build, test, lint |
| Estándares de Codificación | Convenciones de nomenclatura, patrones, reglas de estilo |
| Reglas de Seguridad | “Nunca incluyas API keys directamente en el código,” “No edites /config” |
La jerarquía
CLAUDE.md(raíz del proyecto) — Contexto compartido, comiteado en GitCLAUDE.local.md(raíz del proyecto) — Notas privadas específicas del desarrollador (añadir a .gitignore)~/.claude/CLAUDE.md— Preferencias globales para todos los proyectos- Subdirectorio
CLAUDE.mdarchivos — Contexto extraído solo cuando se trabaja en ese directorio
La regla de oro: Si tienes que repetir una instrucción en el chat más de dos veces, promociónala a tu CLAUDE.md.
9. Reacciones de la comunidad
Investigamos discusiones en Reddit (r/ClaudeAI, r/ClaudeCode), Twitter/X y blogs técnicos. Esto es lo que piensa la comunidad:
El consenso del “Junior Dev Seguro de sí mismo”
La comunidad de Reddit describe frecuentemente a Claude Code como un brillante pero a veces poco confiable “desarrollador junior.” Es rápido y tiene amplios conocimientos, pero es propenso a tomar atajos peligrosos, alucinar o cometer errores ingenuos si se deja sin supervisión. El archivo de habilidades de Karpathy aborda esto directamente añadiendo las barreras de seguridad que un desarrollador junior necesita.
El argumento del “Skill Issue”
Un sentimiento predominante en Reddit: la calidad del código generado por IA es directamente proporcional al propio criterio de ingeniería del usuario y a sus habilidades de “ingeniería de contexto”. Los usuarios avanzados que dominan la estructura de los prompts, la gestión del contexto y los bucles de verificación reportan tasas de éxito drásticamente superiores. El archivo de habilidades de Karpathy es una de las herramientas de “ingeniería de contexto” más populares.
El debate sobre la “psicosis de la IA”
La descripción de Karpathy sobre la “psicosis perpetua de la IA” — un estado constante de dirección de agentes hiperproductiva pero agotadora — resonó profundamente. Algunos ven a los agentes de IA como una ventaja competitiva que no se puede ignorar. Otros lo llaman “teatro de la productividad” — sentirse rápido mientras se produce código difícil de mantener. El archivo de habilidades se sitúa en un punto intermedio: reconoce que los agentes de IA son potentes, pero sostiene que necesitan restricciones disciplinadas.
El cambio en el cuello de botella humano
El consenso de la comunidad: la IA ha reducido la barrera para escribir código. Pero el verdadero cuello de botella se ha desplazado de la implementación a la arquitectura y evaluación. El desafío ya no es “¿cómo escribo esto?” sino “¿entiendo lo que el agente acaba de construir lo suficientemente bien como para mantenerlo?”
10. El panorama general
De “Vibe Coding” a la “Ingeniería Agéntica”
Cuando Karpathy acuñó el término “vibe coding” a principios de 2025, describía una forma relajada y conversacional de interactuar con la IA mediante prompts. Para 2026, la comunidad ha evolucionado esto hacia la “ingeniería agéntica” — una disciplina donde los desarrolladores tratan a la IA como un socio que requiere objetivos claros, límites definidos y pruebas rigurosas.
El andrej-karpathy-skills repo representa esta evolución. No se trata de limitar lo que la IA puede hacer. Se trata de canalizar lo que puede hacer a través de principios que producen mejores resultados.
El patrón “Archivo de Ideas”
Este repo también ejemplifica lo que Karpathy llama el “archivo de ideas” patrón — compartir ideas en lugar de implementaciones. El CLAUDE.md archivo no es una librería que alguien importe. Es un conjunto de principios que cualquiera puede adaptar. El agente del destinatario lo personaliza para sus necesidades específicas. Este es un nuevo tipo de código abierto: no código abierto, sino ideas abiertas.
Cómo saber si está funcionando
Según el README del repo, estas pautas están funcionando si ves:
- Menos cambios innecesarios en los diffs — Solo aparecen los cambios solicitados
- Menos reescrituras por sobrecomplicación — El código es simple a la primera
- Las preguntas aclaratorias van antes de la implementación — No después de los errores
- PRs limpios y mínimos — Sin refactorizaciones de paso o “mejoras”
La nota sobre los tradeoffs
El repositorio es honesto sobre sus tradeoffs: “Estas pautas priorizan la precaución sobre la velocidad.” Para tareas triviales (correcciones simples de typos, one-liners obvios), usa tu criterio — no todos los cambios requieren de todo el rigor. El objetivo es reducir errores costosos en trabajos no triviales, no ralentizar las tareas simples.
11. Todas las fuentes & enlaces
Este artículo fue investigado usando investigación de múltiples fuentes a través de GitHub, Twitter/X, Reddit, artículos web y el propio código fuente. Aquí están todas las fuentes primarias:
Fuentes primarias
- GitHub: forrestchang/andrej-karpathy-skills — El repositorio en sí
- CLAUDE.md — El archivo de pautas real
- EXAMPLES.md — Ejemplos reales de antes/después
- Tweet original de Karpathy — El post viral que identifica los errores comunes al programar con LLM
Discusiones de la comunidad
- Reddit r/ClaudeAI — Discusiones de la comunidad sobre flujos de trabajo de Claude Code y el consenso del “junior dev seguro de sí mismo”
- Reddit r/ClaudeCode — Hilos sobre mejores prácticas de CLAUDE.md y sistemas de especificaciones
- Twitter/X — Reacciones de desarrolladores, intercambio de flujos de trabajo y reportes de adopción
Fuentes web
- Medium — Reseñas técnicas y guías de implementación
- dev.to — Tutoriales de la comunidad de desarrolladores
- Forbes — Cobertura de la evolución del “vibe coding” hacia la “ingeniería agéntica”
- VentureBeat — Análisis de la analogía del “compilador” de Karpathy para la gestión de contexto
- Analytics Vidhya — Análisis técnico del enfoque del archivo de habilidades (skills file)
Documentación
- Documentación de Claude Code — Referencia oficial de CLAUDE.md
- HumanLayer.dev — Mejores prácticas para la configuración de CLAUDE.md
Artículos relacionados en este sitio
- Bases de conocimiento de LLM de Karpathy: El tweet original, explicado
- Wiki de LLM de Karpathy: La guía completa de su archivo de ideas
- Cómo configurar habilidades en tu IDE de IA
- La guía completa de System Prompts para agentes de IA
Get the Ultimate Antigravity Cheat Sheet
Join 5,000+ developers and get our exclusive PDF guide to mastering Gemini 3 shortcuts and agent workflows.