Coding Guidelines
Principios core para trabajar con LLMs en tareas de desarrollo.
4 Principios
1. Pensa Antes de Codear
NO empezar a escribir codigo inmediatamente.
- Surfacea assumptions antes de implementar
- Pregunta sobre preferencias: estructuras de datos, patrones, librerias
- Presenta multiples opciones con trade-offs
- Confirma alineamiento antes de codear
2. Simplicidad Primero
El codigo mas simple que resuelve el problema.
- KISS, DRY, YAGNI siempre
- Sin abstracciones especulativas ("por si algun dia...")
- Sin features no pedidas
- Sin over-engineering: 3 lineas similares > abstraccion prematura
3. Cambios Quirurgicos
Editar lo minimo necesario.
- Matchear patterns existentes del codebase
- No refactorizar codigo que no toca la feature
- No agregar docstrings/comments donde no habia
- No cambiar estilo/formato de codigo existente
4. Objetivos Verificables
Criterios claros para saber cuando esta listo.
- Definir que significa "funciona"
- Tests que validen el comportamiento esperado
- Checkear lint, types, build antes de terminar
Aplicacion por Lenguaje
Ver referencias para reglas especificas:
references/typescript.md- TypeScript strict mode, testing, estructurareferences/python.md- Type hints, mypy, pytest, ruff
Ejemplos de Uso
Ejemplo 1: Usuario pide agregar feature de logging
Usuario: "Agregá logging a este servicio"
MAL (sin consultar):
// Empezar a agregar winston, estructurar logs, crear middleware...
import winston from 'winston';
const logger = winston.createLogger({...});
BIEN (consultar primero):
Antes de agregar logging, necesito entender:
1. ¿Qué librería de logging prefieren? (winston, pino, console estructurado)
2. ¿A dónde van los logs? (stdout, archivo, servicio externo)
3. ¿Qué nivel de detalle? (solo errores, debug incluido)
4. ¿Hay un formato estándar en el proyecto?
Vi que ya usan console.log en otros lugares. ¿Prefieren mantener
consistencia o migrar todo a una librería?
Ejemplo 2: Usuario pide refactorizar
Usuario: "Este archivo está muy largo, refactorizalo"
MAL (hacer todo):
// Extraer todo a archivos separados, agregar types, cambiar naming...
BIEN (proponer opciones):
El archivo tiene 450 líneas. Opciones:
A) Extraer helpers a utils/helpers.ts (reduce a ~300 líneas)
B) Separar por dominio: user.ts, auth.ts, session.ts
C) Solo extraer la función más larga (validateUserSession, 80 líneas)
¿Cuál preferís? Recomiendo C porque es el cambio mínimo
que mejora legibilidad sin reestructurar todo.
Ejemplo 3: Usuario pide implementar validación
Usuario: "Agregá validación al form de registro"
MAL (asumir):
// Instalar zod, crear schemas, agregar validación client y server...
import { z } from 'zod';
const userSchema = z.object({...});
BIEN (preguntar scope):
¿Qué tipo de validación necesitás?
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 preferís otra librería?
Anti-patrones
❌ Saltar a codear sin discutir
// Usuario: "Agregá cache"
// Inmediatamente:
import Redis from 'ioredis';
const redis = new Redis(); // ← ¿Quién pidió Redis?
Problema: Asumiste Redis cuando podría ser in-memory, localStorage, o un servicio externo.
❌ Agregar features "por las dudas"
// Te pidieron: agregar un botón de logout
// Agregaste:
<Button onClick={logout}>Logout</Button>
<ConfirmModal /> {/* ← Nadie pidió confirmación */}
<SessionTimeoutWarning /> {/* ← Nadie pidió esto */}
Problema: Features no solicitadas = código extra que mantener.
❌ Refactorizar de paso
// Te pidieron: corregir bug en calculateTotal()
// Hiciste:
- function calculateTotal(items) {
+ function calculateTotal(items: CartItem[]): Money { // ← Tipos nuevos
// ... fix del bug ...
}
+ // También renombré variables para mayor claridad ← NO
+ // Y extraje la lógica de descuentos ← NO
Problema: El PR tiene cambios mezclados, difícil de revisar.
❌ Over-engineering
// Te pidieron: guardar preferencia de tema (dark/light)
// Hiciste:
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 un patrón Observer.
❌ Asumir en vez de preguntar
// Usuario: "No funciona el login"
// Empezaste a reescribir el auth flow completo...
// Cuando el bug era:
- if (password = storedHash) // typo: = en vez de ===
+ if (password === storedHash)
Problema: Investigar primero, preguntar qué error ven, antes de reescribir.