Ejemplos detallados y anti-patrones para escribir codigo de calidad con LLMs (simplicidad, cambios quirurgicos, objetivos verificables). Use this skill at the start of any coding task where the user asks to implement a feature, add functionality, fix a bug, refactor code, or modify an existing file, especially when the request is vague ("agrega X", "arregla Y", "mejora Z", "refactoriza esto") and assumptions about libraries, patterns, or scope need to be surfaced before writing code. Also use when the user asks for code review focused on over-engineering, scope creep, or unnecessary changes.
Los principios core (Simplicity First, Surgical Changes, Goal-Driven Execution) viven en ~/.claude/CLAUDE.md global, y aplican siempre.
Este skill es el deep dive: ejemplos concretos y anti-patrones para casos dudosos.
Inspirado en las observaciones de Andrej Karpathy sobre errores comunes de LLMs.
Fuente original vendorizada en references/karpathy-original.md.
references/typescript.md - TypeScript strict mode, testing, estructurareferences/python.md - Type hints, mypy, pytest, ruffUsuario: "Agrega logging a este servicio"
MAL (sin consultar):
import winston from 'winston';
const logger = winston.createLogger({...});
BIEN (consultar primero):
Antes de agregar logging, necesito entender:
1. Que libreria de logging prefieren? (winston, pino, console estructurado)
2. A donde van los logs? (stdout, archivo, servicio externo)
3. Que nivel de detalle? (solo errores, debug incluido)
4. Hay un formato estandar en el proyecto?
Vi que ya usan console.log en otros lugares. Prefieren mantener
consistencia o migrar todo a una libreria?
Usuario: "Este archivo esta muy largo, refactorizalo"
MAL (hacer todo):
// Extraer todo a archivos separados, agregar types, cambiar naming...
BIEN (proponer opciones con trade-offs):
El archivo tiene 450 lineas. Opciones:
A) Extraer helpers a utils/helpers.ts (reduce a ~300 lineas)
B) Separar por dominio: user.ts, auth.ts, session.ts
C) Solo extraer la funcion mas larga (validateUserSession, 80 lineas)
Cual preferis? Recomiendo C porque es el cambio minimo
que mejora legibilidad sin reestructurar todo.
Usuario: "Agrega validacion al form de registro"
MAL (asumir):
import { z } from 'zod';
const userSchema = z.object({...});
BIEN (preguntar scope):
Que tipo de validacion necesitas?
1. Solo frontend (mostrar errores en el form)
2. Solo backend (retornar 400 con errores)
3. Ambos (schema compartido)
Vi que el proyecto usa yup en otros forms.
Sigo con yup o preferis otra libreria?
// Usuario: "Agrega cache"
// Inmediatamente:
import Redis from 'ioredis';
const redis = new Redis(); // Quien pidio Redis?
Problema: Se asumio Redis cuando podria ser in-memory, localStorage, o un servicio externo.
// Te pidieron: agregar un boton de logout
// Agregaste:
<Button onClick={logout}>Logout</Button>
<ConfirmModal /> {/* Nadie pidio confirmacion */}
<SessionTimeoutWarning /> {/* Nadie pidio esto */}
Problema: Features no solicitadas = codigo extra que mantener.
// Te pidieron: corregir bug en calculateTotal()
// Se hizo:
- function calculateTotal(items) {
+ function calculateTotal(items: CartItem[]): Money { // Tipos nuevos
// ... fix del bug ...
}
+ // Tambien se renombraron variables para mayor claridad - NO
+ // Y se extrajo la logica de descuentos - NO
Problema: El PR tiene cambios mezclados, dificil de revisar. Cada linea tocada debe trazarse al pedido original.
// Te pidieron: guardar preferencia de tema (dark/light)
// Se hizo:
class ThemeManager implements IThemeProvider {
private strategy: ThemeStrategy;
private observers: ThemeObserver[] = [];
constructor(config: ThemeConfig) { ... }
}
// Cuando bastaba:
localStorage.setItem('theme', 'dark');
Problema: Complejidad innecesaria. Un boolean no necesita patron Observer. Regla: "¿un senior engineer diria que esto esta overcomplicado?".
// Usuario: "No funciona el login"
// Se empezo a reescribir el auth flow completo...
// Cuando el bug era:
- if (password = storedHash) // typo: = en vez de ===
+ if (password === storedHash)
Problema: Investigar primero, preguntar que error ven, antes de reescribir.
Usuario: "Arregla el bug del carrito"
Claude: *empieza a tocar codigo random del carrito*
BIEN:
Para arreglar el bug necesito:
1. Reproducirlo: que pasos llevan al bug?
2. Escribir un test que falle mostrando el bug
3. Hacerlo pasar con el fix minimo
4. Verificar que el resto de tests siguen verdes
Podes darme los pasos de reproduccion?