coding-guidelines（编码指南）

Coding Guidelines — Ejemplos y Anti-patrones

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.

Aplicacion por Lenguaje

• references/typescript.md - TypeScript strict mode, testing, estructura
• references/python.md - Type hints, mypy, pytest, ruff

Ejemplos: Pensar Antes de Codear

Ejemplo 1: Feature de logging

Usuario: "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?

Ejemplo 2: Refactor grande

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.

Ejemplo 3: Validacion ambigua

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?

Anti-patrones

Saltar a codear sin discutir

// 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.

Features "por las dudas"

// 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.

Refactorizar de paso (violacion de Surgical Changes)

// 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.

Over-engineering (violacion de Simplicity First)

// 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?".

Asumir en vez de investigar

// 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.

Tarea vaga sin objetivo verificable (violacion de Goal-Driven)

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?