# PRINCIPIO: ECONOMÍA DE TOKENS

**Versión:** 1.0.0
**Fecha:** 2025-12-08
**Aplica a:** Todos los agentes
**Prioridad:** OBLIGATORIA para evitar errores de context overflow

---

## RESUMEN EJECUTIVO

> **Los agentes tienen límites de tokens. Excederlos = fallo de tarea.**
> Planificar con economía de tokens = tareas exitosas.
> Tareas grandes sin desglose = error garantizado.

---

## LÍMITES CRÍTICOS

```yaml
CONTEXTO_MAXIMO:
  entrada: ~200,000 tokens  # Lo que el agente puede "ver"
  salida: ~8,000 tokens     # Lo que puede generar por respuesta
  recomendado_carga: <50,000 tokens  # Para dejar espacio de trabajo

ARCHIVO_INDIVIDUAL:
  maximo_recomendado: 500 líneas (~2,000 tokens)
  ideal: 200-300 líneas (~1,000 tokens)
  alerta: >400 líneas → considerar división

PROMPT_DELEGACION:
  maximo: 3,000 tokens (~750 líneas de prompt)
  recomendado: 1,500 tokens (~375 líneas)
  minimo_efectivo: 500 tokens (~125 líneas)
```

---

## REGLAS DE ECONOMÍA

### Regla 1: Cargar Solo Lo Necesario

```yaml
MAL:
  - Cargar TODOS los archivos del proyecto
  - Leer archivos completos cuando solo necesitas una sección
  - Incluir documentación extendida en prompts de delegación

BIEN:
  - Cargar SOLO archivos relevantes para la tarea actual
  - Usar SIMCO-QUICK-REFERENCE.md en lugar de _INDEX.md completo
  - Referencias a archivos en vez de copiar contenido
```

### Regla 2: Desglosar Tareas Grandes

```yaml
TAREA_GRANDE (>2000 tokens de output esperado):
  - Dividir en subtareas independientes
  - Cada subtarea = máximo 1 archivo o 1 función
  - Secuenciar: crear → validar → siguiente

EJEMPLO_MALO:
  "Crear el módulo completo de usuarios con entity, service,
   controller, DTOs, tests, y documentación"
  # Esto generará >8000 tokens de salida = ERROR

EJEMPLO_BUENO:
  ST-001: Crear UserEntity alineada con DDL
  ST-002: Crear CreateUserDto y UpdateUserDto
  ST-003: Crear UserService con CRUD básico
  ST-004: Crear UserController con endpoints
  ST-005: Ejecutar build + lint
  # Cada una <2000 tokens = ÉXITO
```

### Regla 3: Prompts de Delegación Concisos

```yaml
INCLUIR:
  - Contexto mínimo necesario (nivel, variables críticas)
  - Tarea específica (1 cosa)
  - Criterios de aceptación (checklist corto)
  - 1-2 archivos de referencia máximo

NO INCLUIR:
  - Historia completa del proyecto
  - Documentación extendida
  - Múltiples opciones/alternativas
  - Código de ejemplo extenso (>50 líneas)
```

---

## ESTRATEGIAS DE DESGLOSE

### Por Capa (Vertical)

```yaml
# En lugar de: "Crear feature de notificaciones"
# Desglosar en:

ST-001_DATABASE:
  tarea: "Crear tabla notifications.notifications"
  output_esperado: ~300 tokens (1 archivo DDL)

ST-002_BACKEND_ENTITY:
  tarea: "Crear NotificationEntity"
  output_esperado: ~200 tokens (1 archivo)

ST-003_BACKEND_DTO:
  tarea: "Crear DTOs de Notification"
  output_esperado: ~300 tokens (2 archivos pequeños)

ST-004_BACKEND_SERVICE:
  tarea: "Crear NotificationService con CRUD"
  output_esperado: ~400 tokens (1 archivo)

ST-005_BACKEND_CONTROLLER:
  tarea: "Crear NotificationController con endpoints"
  output_esperado: ~350 tokens (1 archivo)

ST-006_VALIDACION:
  tarea: "Ejecutar build + lint backend"
  output_esperado: ~100 tokens (comandos)
```

### Por Funcionalidad (Horizontal)

```yaml
# En lugar de: "Implementar autenticación"
# Desglosar en:

ST-001: Verificar @CATALOG (¿existe auth?)
ST-002: Si existe → usar SIMCO-REUTILIZAR
ST-003: Si no existe → crear esquema auth (DDL)
ST-004: Crear AuthModule básico (register/login)
ST-005: Crear JWT strategy
ST-006: Crear guards
ST-007: Integrar en app.module
ST-008: Validar build + lint
```

---

## ESTIMACIÓN DE TOKENS

### Fórmula Rápida

```
tokens ≈ caracteres / 4
tokens ≈ palabras * 1.3
tokens ≈ líneas * 10 (código promedio)
```

### Tabla de Referencia

| Tipo de Archivo | Líneas Típicas | Tokens Estimados |
|-----------------|----------------|------------------|
| Entity simple | 30-50 | 300-500 |
| Entity con relaciones | 80-120 | 800-1200 |
| DTO | 20-40 | 200-400 |
| Service CRUD | 100-150 | 1000-1500 |
| Controller REST | 80-120 | 800-1200 |
| Tabla DDL | 30-60 | 300-600 |
| Componente React simple | 50-80 | 500-800 |
| Componente React complejo | 150-250 | 1500-2500 |
| Hook | 30-60 | 300-600 |

---

## DETECCIÓN DE PROBLEMAS

### Señales de Alerta

```yaml
ANTES_DE_EJECUTAR:
  - [ ] ¿La tarea pide crear >3 archivos? → Desglosar
  - [ ] ¿El prompt de delegación >1500 tokens? → Reducir
  - [ ] ¿Se pide "módulo completo"? → Desglosar por componente
  - [ ] ¿Se incluye código de referencia >50 líneas? → Usar referencia a archivo

DURANTE_EJECUCION:
  - [ ] ¿Respuesta truncada? → Tarea muy grande
  - [ ] ¿Error de context? → Demasiados archivos cargados
  - [ ] ¿Alucinaciones? → Contexto insuficiente o confuso
```

### Acciones Correctivas

```yaml
SI_RESPUESTA_TRUNCADA:
  1. Dividir tarea en 2-3 subtareas
  2. Re-ejecutar cada subtarea por separado
  3. Validar entre subtareas

SI_ERROR_CONTEXT:
  1. Descargar archivos no esenciales
  2. Usar SIMCO-QUICK-REFERENCE en lugar de _INDEX completo
  3. Referencias en lugar de contenido inline

SI_ALUCINACIONES:
  1. Verificar que archivos de referencia se cargaron
  2. Incluir más contexto específico (menos genérico)
  3. Ser más explícito en criterios de aceptación
```

---

## TEMPLATE DE DELEGACIÓN OPTIMIZADO

```yaml
# PROMPT OPTIMIZADO (~800 tokens)

## SUBAGENTE: {Tipo}
Nivel: {nivel} | Proyecto: {proyecto} | Ruta: {orchestration_path}

## TAREA ÚNICA
{Descripción en 1-2 oraciones}

## ESPECIFICACIÓN
{Solo lo necesario, máximo 10 líneas}

## REFERENCIA
- Archivo: `{ruta exacta}` (copiar patrón de líneas X-Y)

## CRITERIOS (máximo 5)
- [ ] {criterio 1}
- [ ] {criterio 2}
- [ ] {criterio 3}

## VALIDACIÓN
```bash
{1-2 comandos}
```

## ENTREGABLES
1. {archivo a crear/modificar}
```

---

## INTEGRACIÓN CON CAPVED

### Fase P (Planeación) - Verificar Tokens

```yaml
ANTES_DE_APROBAR_PLAN:
  - [ ] Cada subtarea genera <2000 tokens de output
  - [ ] Cada prompt de delegación <1500 tokens
  - [ ] No hay subtareas que pidan "módulo completo"
  - [ ] Subtareas son independientes (pueden fallar sin afectar otras)
```

### Fase E (Ejecución) - Monitorear

```yaml
DURANTE_EJECUCION:
  - Si subtarea falla por tokens → subdividir más
  - Si contexto insuficiente → cargar archivo específico
  - Si respuesta truncada → dividir y reintentar
```

---

## MÉTRICAS DE ÉXITO

```yaml
TAREA_BIEN_DESGLOSADA:
  - 0 errores de token overflow
  - 0 respuestas truncadas
  - Cada subtarea completa en 1 iteración
  - Build pasa después de cada subtarea

DELEGACION_OPTIMA:
  - Prompt <1500 tokens
  - Respuesta completa sin truncar
  - Criterios verificables cumplidos
  - Sin re-trabajo por malentendidos
```

---

## REFERENCIAS

- **Referencia rápida:** `SIMCO-QUICK-REFERENCE.md`
- **Delegación:** `SIMCO-DELEGACION.md`
- **Desglose de tareas:** `SIMCO-TAREA.md`

---

**Versión:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental
