rckrdmrd/workspace-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
803abb3d95
workspace-v1/orchestration/analisis/ANALISIS-GESTION-CONTEXTO-TOKENS-2026-01-07.md
rckrdmrd ff3038f183 feat(orchestration): Add subagent token management system 
Sistema completo de gestión de tokens para subagentes NEXUS v4.0:

Nuevas directivas SIMCO:
- SIMCO-SUBAGENTE.md: Protocolo para agentes en modo subagente
- SIMCO-CCA-SUBAGENTE.md: CCA ligero para subagentes (~1,500 tokens)
- SIMCO-CONTROL-TOKENS.md: Gestión de límites de tokens
- SIMCO-DELEGACION-PARALELA.md: Delegación paralela

Perfiles compact (~250 tokens cada uno):
- PERFIL-BACKEND-COMPACT.md
- PERFIL-FRONTEND-COMPACT.md
- PERFIL-DATABASE-COMPACT.md
- PERFIL-DEVOPS-COMPACT.md
- PERFIL-ML-COMPACT.md
- PERFIL-GENERIC-SUBAGENT.md

Templates de delegación escalonados:
- TEMPLATE-DELEGACION-MINIMA.md (~250 tokens)
- TEMPLATE-DELEGACION-ESTANDAR.md (~600 tokens)
- TEMPLATE-DELEGACION-COMPLETA.md (~1,800 tokens)

Nuevos perfiles especializados:
- PERFIL-MCP-ARCHITECT.md
- PERFIL-MCP-DEVELOPER.md
- PERFIL-RAG-ENGINEER.md
- PERFIL-CICD-SPECIALIST.md
- PERFIL-PRODUCTION-MANAGER.md
- PERFIL-MONITORING-AGENT.md
- PERFIL-SECRETS-MANAGER.md
- PERFIL-PROPAGATION-TRACKER.md

Checklists y documentación:
- CHECKLIST-PRE-DELEGACION.md
- Análisis y planes de implementación

Métricas de mejora:
- ~59% reducción de tokens por delegación
- Perfiles compact: 69% más ligeros
- CCA subagente: 85% más ligero

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-07 04:43:01 -06:00

549 lines
17 KiB
Markdown
Raw Blame History

---
version: "1.0.0"
fecha: "2026-01-07"
tipo: analisis
fase: "2 - Análisis Detallado"
autor: "Claude Code (Opus 4.5)"
objetivo: "Identificar problemas y oportunidades de mejora en gestión de contexto/tokens"
---
# ANÁLISIS DETALLADO: GESTIÓN DE CONTEXTO Y TOKENS EN SUBAGENTES
## 1. RESUMEN EJECUTIVO
### 1.1 Alcance del Análisis
Se analizaron exhaustivamente:
- **36 perfiles de agentes** en `orchestration/agents/perfiles/`
- **39 directivas SIMCO** en `orchestration/directivas/simco/`
- **4 templates CONTEXTO-NIVEL-*.md** en `orchestration/templates/`
- **Templates de delegación y herencia** de contexto
- **Directivas de control de tokens** y economía de contexto
### 1.2 Hallazgos Principales
| Categoría | Estado Actual | Nivel de Preocupación |
|-----------|---------------|----------------------|
| Estructura de Niveles L0-L3 | Bien definida | BAJO |
| Presupuestos de tokens | Definidos pero no validados | MEDIO |
| Templates de delegación | Completos pero muy extensos | ALTO |
| Herencia de contexto | 3 formatos disponibles | MEDIO |
| Validación @CATALOG | Definida pero inconsistente | ALTO |
| Perfiles de agentes | Muy extensos (600-900 tokens cada uno) | ALTO |
| Recuperación de contexto | Definida pero no integrada | MEDIO |
### 1.3 Problema Central Identificado
> **Los perfiles y directivas NO optimizan el contexto para subagentes.**
>
> El sistema actual está diseñado para agentes con contexto completo, no para subagentes que reciben contexto delegado y deben operar con menos tokens disponibles.
---
## 2. PROBLEMAS IDENTIFICADOS
### 2.1 PROBLEMA CRÍTICO: Perfiles Demasiado Extensos
**Ubicación**: `orchestration/agents/perfiles/PERFIL-*.md`
**Descripción**: Cada perfil tiene 600-900 tokens, incluyendo:
- Sección completa de CONTEXT REQUIREMENTS
- Sección completa de CMV (Contexto Mínimo Viable)
- Sección de Recovery Protocol
- Múltiples referencias a SIMCO y directivas
**Impacto en Subagentes**:
- Un subagente recibe ~1,000-1,500 tokens solo por cargar su perfil
- El presupuesto L0 (4,500 tokens) se consume mayormente en el perfil
- Subagentes quedan con menos tokens para la tarea específica
**Archivos Afectados**:
```
orchestration/agents/perfiles/PERFIL-BACKEND.md (~800 tokens)
orchestration/agents/perfiles/PERFIL-FRONTEND.md (~750 tokens)
orchestration/agents/perfiles/PERFIL-DATABASE.md (~700 tokens)
orchestration/agents/perfiles/PERFIL-ORQUESTADOR.md (~900 tokens)
orchestration/agents/perfiles/PERFIL-TECH-LEADER.md (~850 tokens)
... (36 perfiles en total)
```
**Solución Propuesta**:
1. Crear versión compacta de cada perfil: `PERFIL-*-COMPACT.md` (~200-300 tokens)
2. Usar versión compacta para subagentes
3. Versión completa solo para agentes principales
---
### 2.2 PROBLEMA ALTO: Directivas SIMCO No Diferenciadas por Rol
**Ubicación**: `orchestration/directivas/simco/SIMCO-*.md`
**Descripción**: Las directivas SIMCO no distinguen entre:
- Agente principal (orquestador/líder) que coordina
- Subagente especializado que ejecuta
**Impacto**:
- Subagentes cargan directivas completas (SIMCO-TAREA, SIMCO-CAPVED-PLUS) que son para orquestadores
- Secciones de "delegación" y "tracking" son irrelevantes para subagentes
- Tokens desperdiciados en contexto que no aplica
**Archivos Afectados**:
```
orchestration/directivas/simco/SIMCO-TAREA.md
orchestration/directivas/simco/SIMCO-CAPVED-PLUS.md
orchestration/directivas/simco/SIMCO-DELEGACION.md
orchestration/directivas/simco/SIMCO-DELEGACION-PARALELA.md
```
**Solución Propuesta**:
1. Agregar sección `MODO_SUBAGENTE:` a cada SIMCO relevante
2. Definir qué secciones cargar cuando se opera como subagente
3. Implementar directiva `SIMCO-SUBAGENTE.md` con protocolo específico
---
### 2.3 PROBLEMA ALTO: Template de Delegación Demasiado Extenso
**Ubicación**: `orchestration/templates/TEMPLATE-DELEGACION-SUBAGENTE.md`
**Descripción**: El template tiene 8 bloques y consume ~1,500-2,000 tokens cuando se instancia
**Estructura Actual**:
```yaml
BLOQUE 1: IDENTIDAD Y CONTEXTO (~300 tokens)
BLOQUE 2: CONTEXTO HEREDADO (~400 tokens)
BLOQUE 3: DIRECTIVAS A SEGUIR (~200 tokens)
BLOQUE 4: TAREA ESPECÍFICA (~300 tokens)
BLOQUE 5: DEPENDENCIAS (~150 tokens)
BLOQUE 6: CRITERIOS (~200 tokens)
BLOQUE 7: ENTREGABLES (~100 tokens)
BLOQUE 8: RESTRICCIONES (~150 tokens)
TOTAL: ~1,800 tokens por delegación
```
**Impacto**:
- Si prompt de delegación usa ~2,000 tokens
- Y subagente carga perfil (~800 tokens)
- Y subagente carga SIMCO (~800 tokens)
- Total contexto inicial: ~3,600 tokens (36% del límite seguro)
**Solución Propuesta**:
1. Crear 3 versiones del template:
- `TEMPLATE-DELEGACION-COMPLETA.md` (8 bloques, ~1,800 tokens)
- `TEMPLATE-DELEGACION-ESTANDAR.md` (5 bloques, ~800 tokens)
- `TEMPLATE-DELEGACION-MINIMA.md` (3 bloques, ~300 tokens)
2. Orquestador elige según complejidad de tarea
---
### 2.4 PROBLEMA MEDIO: Falta de Validación de Presupuesto
**Ubicación**: `orchestration/directivas/simco/SIMCO-CONTROL-TOKENS.md`
**Descripción**: El presupuesto está definido pero:
- No hay checklist de validación pre-delegación obligatoria
- No hay mecanismo de verificación automática
- No hay alertas cuando se excede el presupuesto
**Presupuesto Definido**:
```yaml
L0_sistema: 4,500 tokens (obligatorio)
L1_proyecto: 3,000 tokens (obligatorio)
L2_operacion: 2,500 tokens (obligatorio)
L3_tarea: max 8,000 tokens (variable)
TOTAL_BASE: 10,000 tokens
DISPONIBLE: 8,000 tokens para tarea
LIMITE_SEGURO: 18,000 tokens
```
**Problema Real**:
- Perfiles (800 tokens) + Principios (6 x 600 = 3,600 tokens) = 4,400 tokens solo en L0
- Ya consume casi todo el presupuesto de L0
- ¿Quién valida que no se exceda?
**Solución Propuesta**:
1. Crear `CHECKLIST-PRE-DELEGACION.md` con validación obligatoria
2. Agregar sección "TOKENS_ESTIMADOS" a cada archivo SIMCO/PERFIL
3. Orquestador debe sumar y validar antes de delegar
---
### 2.5 PROBLEMA MEDIO: Protocolo CCA Pesado para Subagentes
**Ubicación**: `orchestration/directivas/simco/SIMCO-INICIALIZACION.md`
**Descripción**: El protocolo CCA (Carga de Contexto Automática) tiene 4 fases:
1. CARGA NIVEL CORE (~4,000 tokens)
2. CARGA NIVEL PROYECTO (~3,000 tokens)
3. CARGA NIVEL OPERACION (~2,000 tokens)
4. CARGA NIVEL TAREA (variable)
**Impacto para Subagentes**:
- Subagente ejecuta CCA completo
- Pero mucho contexto ya fue heredado del orquestador
- Duplicación de carga = desperdicio de tokens
**Solución Propuesta**:
1. Crear `CCA-SUBAGENTE` (versión ligera del protocolo)
2. Subagente solo carga: Perfil compacto + SIMCO específico + Tarea
3. Contexto de proyecto ya viene heredado
---
### 2.6 PROBLEMA MEDIO: Recovery No Diferenciado
**Ubicación**: Sección `recovery:` en cada PERFIL-*.md
**Descripción**: El protocolo de recuperación es el mismo para:
- Agente principal que perdió contexto
- Subagente que perdió contexto
**Impacto**:
- Subagente intenta recovery completo
- Pero no tiene acceso a CONTEXTO-PROYECTO del orquestador
- Recovery falla o es incompleto
**Solución Propuesta**:
1. Definir `RECOVERY-SUBAGENTE` específico
2. Subagente escala a orquestador si pierde contexto crítico
3. Orquestador re-delega con contexto heredado actualizado
---
### 2.7 PROBLEMA BAJO: Herencia de Contexto Poco Usada
**Ubicación**: `orchestration/templates/TEMPLATE-HERENCIA-CONTEXTO.md`
**Descripción**: Existen 3 formatos de herencia:
- Completo (~1,000 tokens)
- Compactado (~300 tokens)
- Ultra-compactado (~100 tokens)
**Problema**:
- Los perfiles no mencionan cuándo usar cada formato
- Orquestadores tienden a usar siempre formato completo
- No hay guía de decisión clara
**Solución Propuesta**:
1. Agregar matriz de decisión a `SIMCO-DELEGACION.md`:
```
Si tokens_disponibles > 15,000 → Formato Completo
Si tokens_disponibles 8,000-15,000 → Formato Compactado
Si tokens_disponibles < 8,000 → Formato Ultra-compactado
```
2. Hacer obligatorio el cálculo antes de delegar
---
## 3. MATRIZ DE PROBLEMAS Y PRIORIDADES
| # | Problema | Impacto | Esfuerzo | Prioridad |
|---|----------|---------|----------|-----------|
| 2.1 | Perfiles demasiado extensos | ALTO | ALTO | P1 |
| 2.2 | SIMCO no diferenciados por rol | ALTO | MEDIO | P1 |
| 2.3 | Template delegación extenso | ALTO | BAJO | P1 |
| 2.4 | Falta validación de presupuesto | MEDIO | BAJO | P2 |
| 2.5 | CCA pesado para subagentes | MEDIO | MEDIO | P2 |
| 2.6 | Recovery no diferenciado | MEDIO | BAJO | P3 |
| 2.7 | Herencia poco usada | BAJO | BAJO | P3 |
---
## 4. DEPENDENCIAS ENTRE ARCHIVOS
### 4.1 Archivos que Deben Modificarse
```yaml
PRIORIDAD_1_ALTA:
perfiles_compactos:
crear:
- orchestration/agents/perfiles/compact/PERFIL-BACKEND-COMPACT.md
- orchestration/agents/perfiles/compact/PERFIL-FRONTEND-COMPACT.md
- orchestration/agents/perfiles/compact/PERFIL-DATABASE-COMPACT.md
- orchestration/agents/perfiles/compact/PERFIL-GENERIC-SUBAGENT.md
directivas_subagente:
crear:
- orchestration/directivas/simco/SIMCO-SUBAGENTE.md
modificar:
- orchestration/directivas/simco/SIMCO-DELEGACION.md (agregar MODO_SUBAGENTE)
- orchestration/directivas/simco/SIMCO-CONTROL-TOKENS.md (agregar checklist)
templates_delegacion:
crear:
- orchestration/templates/TEMPLATE-DELEGACION-ESTANDAR.md
- orchestration/templates/TEMPLATE-DELEGACION-MINIMA.md
modificar:
- orchestration/templates/TEMPLATE-DELEGACION-SUBAGENTE.md (renombrar a COMPLETA)
PRIORIDAD_2_MEDIA:
protocolo_cca:
crear:
- orchestration/directivas/simco/SIMCO-CCA-SUBAGENTE.md
modificar:
- orchestration/directivas/simco/SIMCO-INICIALIZACION.md (agregar referencia)
validacion:
crear:
- orchestration/checklists/CHECKLIST-PRE-DELEGACION.md
PRIORIDAD_3_BAJA:
recovery:
modificar:
- orchestration/directivas/simco/SIMCO-INICIALIZACION.md (agregar RECOVERY-SUBAGENTE)
herencia:
modificar:
- orchestration/directivas/simco/SIMCO-DELEGACION.md (agregar matriz de decisión)
```
### 4.2 Dependencias Identificadas
```yaml
SIMCO-SUBAGENTE.md:
depende_de:
- PRINCIPIO-ECONOMIA-TOKENS.md (filosofía base)
- SIMCO-CONTROL-TOKENS.md (límites)
referenciado_por:
- Todos los PERFIL-*-COMPACT.md
- TEMPLATE-DELEGACION-*.md
PERFIL-*-COMPACT.md:
depende_de:
- SIMCO-SUBAGENTE.md (protocolo)
- Perfil original correspondiente
referenciado_por:
- TEMPLATE-DELEGACION-*.md (cuando se usa para subagentes)
TEMPLATE-DELEGACION-ESTANDAR.md:
depende_de:
- TEMPLATE-DELEGACION-SUBAGENTE.md (base completa)
- SIMCO-CONTROL-TOKENS.md (presupuesto)
referenciado_por:
- SIMCO-DELEGACION.md
- PERFIL-ORQUESTADOR.md
- PERFIL-TECH-LEADER.md
CHECKLIST-PRE-DELEGACION.md:
depende_de:
- SIMCO-CONTROL-TOKENS.md (límites)
- SIMCO-DELEGACION.md (proceso)
referenciado_por:
- PERFIL-ORQUESTADOR.md
- PERFIL-TECH-LEADER.md
```
---
## 5. ESTIMACIÓN DE AHORRO DE TOKENS
### 5.1 Ahorro por Uso de Perfiles Compactos
| Perfil | Actual | Compacto | Ahorro |
|--------|--------|----------|--------|
| BACKEND | 800 | 250 | 550 (69%) |
| FRONTEND | 750 | 230 | 520 (69%) |
| DATABASE | 700 | 220 | 480 (69%) |
| PROMEDIO | 750 | 235 | 515 (69%) |
### 5.2 Ahorro por Templates de Delegación Escalonados
| Template | Tokens | Uso |
|----------|--------|-----|
| COMPLETA | 1,800 | Tareas complejas multi-archivo |
| ESTANDAR | 800 | Tareas estándar (mayoría) |
| MINIMA | 300 | Tareas simples 1 archivo |
**Ahorro promedio**: Si 60% de tareas son estándar y 30% son simples:
- Antes: 100 delegaciones x 1,800 = 180,000 tokens
- Después: 10 x 1,800 + 60 x 800 + 30 x 300 = 75,000 tokens
- **Ahorro: 58%**
### 5.3 Ahorro Total Estimado
```yaml
ANTES (por delegación típica):
prompt_delegacion: 1,800 tokens
perfil_subagente: 800 tokens
simco_cargados: 1,600 tokens (2 SIMCO)
contexto_heredado: 1,000 tokens
TOTAL: 5,200 tokens
DESPUÉS (con optimizaciones):
prompt_delegacion: 800 tokens (ESTANDAR)
perfil_subagente: 250 tokens (COMPACT)
simco_cargados: 800 tokens (1 SIMCO específico)
contexto_heredado: 300 tokens (Compactado)
TOTAL: 2,150 tokens
AHORRO: 3,050 tokens por delegación (59%)
```
---
## 6. PROPUESTA DE ARQUITECTURA OPTIMIZADA
### 6.1 Nueva Estructura de Archivos
```
orchestration/
├── agents/
│ └── perfiles/
│ ├── PERFIL-*.md (completos, para agentes principales)
│ ├── compact/
│ │ ├── PERFIL-BACKEND-COMPACT.md
│ │ ├── PERFIL-FRONTEND-COMPACT.md
│ │ ├── PERFIL-DATABASE-COMPACT.md
│ │ └── ... (versiones compactas)
│ └── _MAP.md (actualizado con referencia a compact/)
│
├── directivas/
│ └── simco/
│ ├── SIMCO-SUBAGENTE.md (NUEVO - protocolo para subagentes)
│ ├── SIMCO-CCA-SUBAGENTE.md (NUEVO - CCA ligero)
│ ├── SIMCO-DELEGACION.md (modificado - incluye matriz herencia)
│ └── SIMCO-CONTROL-TOKENS.md (modificado - incluye checklist)
│
├── templates/
│ ├── TEMPLATE-DELEGACION-COMPLETA.md (renombrado)
│ ├── TEMPLATE-DELEGACION-ESTANDAR.md (NUEVO)
│ └── TEMPLATE-DELEGACION-MINIMA.md (NUEVO)
│
└── checklists/
└── CHECKLIST-PRE-DELEGACION.md (NUEVO)
```
### 6.2 Nuevo Flujo de Delegación
```
ORQUESTADOR recibe tarea
│
├─ (1) Evaluar complejidad
│ ├─ Simple (1 archivo) → TEMPLATE-MINIMA
│ ├─ Estándar (2-3 archivos) → TEMPLATE-ESTANDAR
│ └─ Compleja (>3 archivos) → TEMPLATE-COMPLETA
│
├─ (2) Calcular tokens disponibles
│ └─ CHECKLIST-PRE-DELEGACION
│
├─ (3) Elegir formato de herencia
│ ├─ >15K disponibles → Completo
│ ├─ 8K-15K disponibles → Compactado
│ └─ <8K disponibles → Ultra-compactado
│
├─ (4) Seleccionar perfil de subagente
│ └─ Usar versión COMPACT (no completa)
│
├─ (5) Preparar prompt de delegación
│ └─ Template seleccionado + Herencia seleccionada
│
├─ (6) Delegar con instrucción
│ └─ "Sigue @SIMCO-SUBAGENTE"
│
└─ SUBAGENTE recibe
│
├─ Ejecuta CCA-SUBAGENTE (ligero)
│ ├─ Cargar PERFIL-*-COMPACT
│ ├─ Cargar SIMCO específico (1 solo)
│ └─ Usar contexto heredado (no re-cargar)
│
├─ Ejecutar tarea
│
└─ Reportar resultado (formato compacto)
```
---
## 7. PRÓXIMOS PASOS (FASE 3: PLANEACIÓN)
### 7.1 Orden de Implementación
```yaml
SPRINT_1 (Fundamentos):
- Crear SIMCO-SUBAGENTE.md
- Crear SIMCO-CCA-SUBAGENTE.md
- Crear CHECKLIST-PRE-DELEGACION.md
SPRINT_2 (Perfiles):
- Crear directorio compact/
- Crear PERFIL-BACKEND-COMPACT.md
- Crear PERFIL-FRONTEND-COMPACT.md
- Crear PERFIL-DATABASE-COMPACT.md
- Crear PERFIL-GENERIC-SUBAGENT.md
- Actualizar _MAP.md
SPRINT_3 (Templates):
- Renombrar TEMPLATE-DELEGACION-SUBAGENTE.md → COMPLETA
- Crear TEMPLATE-DELEGACION-ESTANDAR.md
- Crear TEMPLATE-DELEGACION-MINIMA.md
SPRINT_4 (Integración):
- Modificar SIMCO-DELEGACION.md (matriz herencia)
- Modificar SIMCO-CONTROL-TOKENS.md (checklist obligatorio)
- Modificar SIMCO-INICIALIZACION.md (referencia CCA-SUBAGENTE)
SPRINT_5 (Validación):
- Actualizar PERFIL-ORQUESTADOR.md (nuevo flujo)
- Actualizar PERFIL-TECH-LEADER.md (nuevo flujo)
- Documentar en README de cada directorio
```
### 7.2 Criterios de Éxito
```yaml
MÉTRICA_1:
nombre: "Tokens por delegación"
antes: 5,200 tokens
objetivo: <2,500 tokens
MÉTRICA_2:
nombre: "Archivos cargados por subagente"
antes: 15+ archivos
objetivo: <8 archivos
MÉTRICA_3:
nombre: "Tiempo de CCA subagente"
antes: 18 minutos (estimado)
objetivo: <5 minutos
MÉTRICA_4:
nombre: "Validación pre-delegación"
antes: Inexistente
objetivo: 100% delegaciones validadas
```
---
## 8. CONCLUSIÓN
El sistema actual tiene una arquitectura sólida para agentes principales, pero no está optimizado para la operación con subagentes. Los principales problemas son:
1. **Perfiles demasiado extensos** para subagentes
2. **Directivas no diferenciadas** por rol (agente vs subagente)
3. **Templates de delegación muy pesados** para tareas simples
4. **Falta de validación** del presupuesto de tokens
La solución propuesta introduce un sistema escalonado donde:
- Subagentes usan versiones compactas de perfiles
- Templates de delegación se escalan según complejidad
- Un checklist valida el presupuesto antes de delegar
- Un protocolo CCA ligero permite inicialización rápida
**Ahorro estimado: 59% de tokens por delegación.**
---
## ANEXO: ARCHIVOS ANALIZADOS
```yaml
perfiles_analizados: 36
directivas_simco_analizadas: 39
templates_analizados: 12
core_orchestration_archivos: 8
total_archivos: 95
tokens_promedio_perfil: 750
tokens_promedio_simco: 900
tokens_promedio_template: 800
```
Reference in New Issue View Git Blame Copy Permalink