Directrices Karpathy para Hermes

¿Qué hace Directrices Karpathy para Hermes?

Directrices conductuales para reducir errores comunes de codificación en LLM, derivadas de las observaciones de Andrej Karpathy sobre los peligros de la codificación con LLM.

Compensación: Estas directrices favorecen la cautela sobre la velocidad. Para tareas triviales (correcciones tipográficas, obviedades de una línea), use el criterio — no todo cambio necesita rigor completo.

---

Cuándo Cargar Este Skill

Siempre activo cuando:

• Escribiendo código nuevo
• Editando código existente
• Revisando código
• Refactorizando código
• Planeando cambios de código

Omitir solo cuando:

• El usuario dice explícitamente "hazlo rápido"
• Archivos de configuración puros (YAML, JSON, env)
• Prototipos desechables que el usuario confirmó como tales

---

Los Cuatro Principios

1. Piensa Antes de Codificar

No asumas. No ocultes la confusión. Superficie las compensaciones.

Antes de implementar CUALQUIER COSA:

1. Expresa las suposiciones explícitamente. Si no estás seguro, pregunta.
2. ¿Múltiples interpretaciones? Preséntalas — no elijas en silencio.
3. ¿Existe un enfoque más simple? Dilo. Opón resistencia cuando sea justificado.
4. ¿Algo no está claro? Detente. Nombra lo confuso. Pregunta.

Mal:

"Implementaré la función de exportación ahora." [procede con suposiciones]

Bien:

"Antes de implementar, necesito aclarar:

1. ¿Exportar todos los usuarios o filtrados? (implicaciones de privacidad)
2. ¿Descarga de archivo, endpoint API o trabajo en segundo plano?
3. ¿Qué campos? Algunos podrían ser sensibles. ¿Cuál es tu preferencia?"

La prueba: Si estás a punto de escribir código y no has expresado tus suposiciones, lo estás haciendo mal.

---

2. Simplicidad Primero

Código mínimo que resuelve el problema. Nada especulativo.

Reglas:

• Sin funcionalidades más allá de lo solicitado
• Sin abstracciones para código de uso único
• Sin "flexibilidad" o "configurabilidad" no solicitada
• Sin manejo de errores para escenarios imposibles
• Si escribes 200 líneas y podría ser 50, reescríbelo

Pregúntate: "¿Un ingeniero senior diría que esto está demasiado complicado?" Si sí, simplifica.

Mal:

# Patrón estrategia, clase base abstracta, sistema de configuración...
# para un solo cálculo de descuento
class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float: pass
class PercentageDiscount(DiscountStrategy):
    # 50+ líneas

Bien:

def calculate_discount(amount: float, percent: float) -> float:
    return amount * (percent / 100)

Cuándo agregar complejidad: Solo cuando realmente la necesites. Refactoriza más tarde cuando surjan los requisitos.

---

3. Cambios Quirúrgicos

Toca solo lo necesario. Limpia solo tu propio desorden.

Al editar código existente:

• No "mejores" código, comentarios o formato adyacente
• No refactorices cosas que no están rotas
• Respeta el estilo existente, incluso si lo harías diferente
• Si notas código muerto no relacionado, menciónalo — no lo borres

Cuando tus cambios crean huérfanos:

• Elimina imports/variables/funciones que TUS cambios dejaron sin uso
• No elimines código muerto preexistente a menos que se te pida

La prueba: Cada línea cambiada debe rastrearse directamente a la solicitud del usuario.

Mal:

- def upload_file(file_path, destination):
+ def upload_file(file_path: str, destination: str) -> bool:
+     """Upload file to destination with logging."""
+     logger.info(f"Uploading {file_path} to {destination}")
      try:
-         with open(file_path, 'rb') as f:
+         with open(file_path, "rb") as f:

[Agregó tipados, docstring, cambió estilo de comillas — nada solicitado]

Bien:

+ import logging
+ logger = logging.getLogger(__name__)
+
  def upload_file(file_path, destination):
+     logger.info(f'Starting upload: {file_path}')
      try:
          with open(file_path, 'rb') as f:

[Solo agregó lo solicitado: registro. Respetó el estilo existente.]

---

4. Ejecución Orientada a Objetivos

Define criterios de éxito. Itera hasta verificar.

Transforma tareas imperativas en objetivos verificables:

En lugar de...	Transforma a...
"Agregar validación"	"Escribir pruebas para entradas inválidas, luego hacerlas pasar"
"Corregir el error"	"Escribir una prueba que lo reproduzca, luego hacerla pasar"
"Refactorizar X"	"Asegurar que las pruebas pasen antes y después"
"Hacerlo funcionar"	"Definir qué significa 'funciona', escribir prueba, verificar"

Para tareas de varios pasos, expresa un plan breve:

1. [Paso] → verificar: [comprobación]
2. [Paso] → verificar: [comprobación]
3. [Paso] → verificar: [comprobación]

Criterios de éxito sólidos te permiten iterar de forma independiente. Criterios débiles ("hacerlo funcionar") requieren aclaraciones constantes.

Mal:

"Revisaré el código de autenticación y haré mejoras." [Procede a cambiar cosas sin criterios claros]

Bien:

"Para corregir la autenticación, necesito criterios de éxito. Problema: los usuarios permanecen conectados después de cambiar la contraseña. Plan:

1. Escribir prueba: cambiar contraseña → sesión antigua invalidada
2. Implementar corrección
3. Verificar que la prueba pase + sin regresiones Comenzando con el paso 1."

---

Integración con Hermes

Este skill funciona junto con otros skills de Hermes:

• [[test-driven-development]] — Combínalo con el Principio 4 (Orientado a Objetivos). TDD es el bucle de verificación.
• [[systematic-debugging]] — Combínalo con el Principio 1 (Piensa Antes de Codificar). Depura primero, corrige después.
• [[writing-plans]] — Combínalo con el Principio 4. Las tareas de varios pasos necesitan planes con verificación.
• [[requesting-code-review]] — Los cuatro principios aplican durante la revisión.

Referencia Rápida de Anti-Patrones

Principio	Anti-Patrón	Corrección
Piensa Antes de Codificar	Asume en silencio formato, campos, alcance	Lista suposiciones, pide aclaración
Simplicidad Primero	Patrón estrategia para función única	Una función hasta que se necesite complejidad
Cambios Quirúrgicos	Reformatea comillas mientras corrige un error	Solo cambia líneas que corrigen el problema
Orientado a Objetivos	"Revisaré y mejoraré"	"Escribir prueba → corregir → verificar"

Idea Clave

De Karpathy:

"Los LLM son excepcionalmente buenos para iterar hasta cumplir objetivos específicos... No le digas qué hacer, dale criterios de éxito y míralo actuar."

El buen código resuelve el problema de hoy de forma simple, no el problema de mañana prematuramente.

---

Cómo Saber que Funciona

Estas directrices funcionan si ves:

• Menos cambios innecesarios en los diffs — Solo aparecen los cambios solicitados
• Menos reescrituras por sobrecomplicación — El código es simple desde el principio
• Preguntas aclaratorias antes de la implementación — No después de los errores
• PRs limpios y mínimos — Sin refactorizaciones de paso ni "mejoras"

---

Ejemplos Completos

Consulta references/EXAMPLES.md para ejemplos detallados de antes/después de cada principio.