coding-guidelines

Coding Guidelines — Examples and Anti-patterns

The core principles (Simplicity First, Surgical Changes, Goal-Driven Execution) live in ~/.claude/CLAUDE.md global, and always apply. This skill is the deep dive: concrete examples and anti-patterns for doubtful cases.

Inspired by Andrej Karpathy's observations on common LLM mistakes. Original source vendored in references/karpathy-original.md.

Application by Language

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

Examples: Think Before Coding

Example 1: Logging feature

User: "Add logging to this service"

BAD (without asking):

import winston from 'winston';
const logger = winston.createLogger({...});

GOOD (ask first):

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?

Example 2: Big refactor

User: "This file is too long, refactor it"

BAD (do everything):

// Extraer todo a archivos separados, agregar types, cambiar naming...

GOOD (propose options with 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.

Example 3: Ambiguous validation

User: "Add validation to the signup form"

BAD (assume):

import { z } from 'zod';
const userSchema = z.object({...});

GOOD (ask 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-patterns

Jumping to code without discussing

// Usuario: "Agrega cache"
// Inmediatamente:
import Redis from 'ioredis';
const redis = new Redis(); // Quien pidio Redis?

Problem: Redis was assumed when it could be in-memory, localStorage, or an external service.

"Just in case" features

// Te pidieron: agregar un boton de logout
// Agregaste:
<Button onClick={logout}>Logout</Button>
<ConfirmModal />         {/* Nadie pidio confirmacion */}
<SessionTimeoutWarning /> {/* Nadie pidio esto */}

Problem: Unsolicited features = extra code to maintain.

Refactoring along the way (violation of 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

Problem: The PR has mixed changes, hard to review. Every line touched must be traceable to the original request.

Over-engineering (violation of 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');

Problem: Unnecessary complexity. A boolean does not need an Observer pattern. Rule: "would a senior engineer say this is overcomplicated?".

Assuming instead of investigating

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

Problem: Investigate first, ask what error they see, before rewriting.

Vague task without a verifiable goal (violation of Goal-Driven)

Usuario: "Arregla el bug del carrito"
Claude: *empieza a tocar codigo random del carrito*

GOOD:

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?