recuperación-iterativa

Patrón de Recuperación Iterativa

Resuelve el "problema de contexto" en flujos de trabajo multi-agente donde los subagentes no saben qué contexto necesitan hasta que empiezan a trabajar.

Cuándo Activarlo

• Al generar subagentes que necesitan contexto del código base que no pueden predecir de antemano
• Al construir flujos de trabajo multi-agente donde el contexto se refina progresivamente
• Al encontrar fallos de "contexto demasiado grande" o "contexto faltante" en tareas de agentes
• Al diseñar pipelines de recuperación tipo RAG para exploración de código
• Al optimizar el uso de tokens en la orquestación de agentes

El Problema

Los subagentes se generan con contexto limitado. No saben:

• Qué archivos contienen código relevante
• Qué patrones existen en el código base
• Qué terminología usa el proyecto

Los enfoques estándar fallan:

• Enviar todo: Supera los límites de contexto
• No enviar nada: El agente carece de información crítica
• Adivinar lo necesario: A menudo es incorrecto

La Solución: Recuperación Iterativa

Un bucle de 4 fases que refina progresivamente el contexto:

┌─────────────────────────────────────────────┐
│                                             │
│   ┌──────────┐      ┌──────────┐            │
│   │ DISPATCH │─────│ EVALUATE │            │
│   └──────────┘      └──────────┘            │
│        ▲                  │                 │
│        │                  ▼                 │
│   ┌──────────┐      ┌──────────┐            │
│   │   LOOP   │─────│  REFINE  │            │
│   └──────────┘      └──────────┘            │
│                                             │
│        Máximo 3 ciclos, luego proceder      │
└─────────────────────────────────────────────┘

Fase 1: DISPATCH (DESPACHAR)

Consulta inicial amplia para recopilar archivos candidatos:

// Comenzar con la intención de alto nivel
const consultaInicial = {
  patrones: ['src/**/*.ts', 'lib/**/*.ts'],
  palabrasClave: ['autenticación', 'usuario', 'sesión'],
  exclusiones: ['*.test.ts', '*.spec.ts']
};

// Despachar al agente de recuperación
const candidatos = await recuperarArchivos(consultaInicial);

Fase 2: EVALUATE (EVALUAR)

Evaluar el contenido recuperado para determinar su relevancia:

function evaluarRelevancia(archivos, tarea) {
  return archivos.map(archivo => ({
    ruta: archivo.ruta,
    relevancia: puntuarRelevancia(archivo.contenido, tarea),
    motivo: explicarRelevancia(archivo.contenido, tarea),
    contextoFaltante: identificarBrechas(archivo.contenido, tarea)
  }));
}

Criterios de puntuación:

• Alta (0.8-1.0): Implementa directamente la funcionalidad objetivo
• Media (0.5-0.7): Contiene patrones o tipos relacionados
• Baja (0.2-0.4): Relacionado tangencialmente
• Ninguna (0-0.2): No relevante, excluir

Fase 3: REFINE (REFINAR)

Actualizar los criterios de búsqueda según la evaluación:

function refinarConsulta(evaluacion, consultaPrevia) {
  return {
    // Agregar nuevos patrones descubiertos en archivos de alta relevancia
    patrones: [...consultaPrevia.patrones, ...extraerPatrones(evaluacion)],

    // Agregar terminología encontrada en el código base
    palabrasClave: [...consultaPrevia.palabrasClave, ...extraerPalabrasClave(evaluacion)],

    // Excluir rutas confirmadas como irrelevantes
    exclusiones: [...consultaPrevia.exclusiones, ...evaluacion
      .filter(e => e.relevancia < 0.2)
      .map(e => e.ruta)
    ],

    // Apuntar a brechas específicas
    areasDeEnfoque: evaluacion
      .flatMap(e => e.contextoFaltante)
      .filter(unicos)
  };
}

Fase 4: LOOP (BUCLE)

Repetir con criterios refinados (máximo 3 ciclos):

async function recuperarIterativamente(tarea, maxCiclos = 3) {
  let consulta = crearConsultaInicial(tarea);
  let mejorContexto = [];

  for (let ciclo = 0; ciclo < maxCiclos; ciclo++) {
    const candidatos = await recuperarArchivos(consulta);
    const evaluacion = evaluarRelevancia(candidatos, tarea);

    // Verificar si tenemos contexto suficiente
    const altaRelevancia = evaluacion.filter(e => e.relevancia >= 0.7);
    if (altaRelevancia.length >= 3 && !tieneBrechasCriticas(evaluacion)) {
      return altaRelevancia;
    }

    // Refinar y continuar
    consulta = refinarConsulta(evaluacion, consulta);
    mejorContexto = fusionarContexto(mejorContexto, altaRelevancia);
  }

  return mejorContexto;
}

Ejemplos Prácticos

Ejemplo 1: Contexto para Corrección de Errores

Tarea: "Corregir el error de expiración del token de autenticación"

Ciclo 1:
  DISPATCH: Buscar "token", "auth", "expiracion" en src/**
  EVALUATE: Se encontraron auth.ts (0.9), tokens.ts (0.8), user.ts (0.3)
  REFINE: Agregar palabras clave "refresh", "jwt"; excluir user.ts

Ciclo 2:
  DISPATCH: Buscar términos refinados
  EVALUATE: Se encontraron session-manager.ts (0.95), jwt-utils.ts (0.85)
  REFINE: Contexto suficiente (2 archivos de alta relevancia)

Resultado: auth.ts, tokens.ts, session-manager.ts, jwt-utils.ts

Ejemplo 2: Implementación de Funcionalidad

Tarea: "Agregar limitación de velocidad a los endpoints de la API"

Ciclo 1:
  DISPATCH: Buscar "limitacion", "limite", "api" en routes/**
  EVALUATE: Sin coincidencias - el código base usa terminología "throttle"
  REFINE: Agregar palabras clave "throttle", "middleware"

Ciclo 2:
  DISPATCH: Buscar términos refinados
  EVALUATE: Se encontraron throttle.ts (0.9), middleware/index.ts (0.7)
  REFINE: Se necesitan patrones de enrutador

Ciclo 3:
  DISPATCH: Buscar patrones "router", "express"
  EVALUATE: Se encontró router-setup.ts (0.8)
  REFINE: Contexto suficiente

Resultado: throttle.ts, middleware/index.ts, router-setup.ts

Integración con Agentes

Usar en los prompts de los agentes:

Al recuperar contexto para esta tarea:
1. Comenzar con una búsqueda amplia de palabras clave
2. Evaluar la relevancia de cada archivo (escala 0-1)
3. Identificar qué contexto aún falta
4. Refinar los criterios de búsqueda y repetir (máximo 3 ciclos)
5. Devolver archivos con relevancia >= 0.7

Mejores Prácticas

1. Comenzar amplio, reducir progresivamente - No especificar demasiado las consultas iniciales
2. Aprender la terminología del código base - El primer ciclo a menudo revela las convenciones de nomenclatura
3. Rastrear lo que falta - La identificación explícita de brechas impulsa el refinamiento
4. Detenerse en "suficientemente bueno" - 3 archivos de alta relevancia son mejores que 10 mediocres
5. Excluir con confianza - Los archivos de baja relevancia no se volverán relevantes

Relacionados

• La Guía Extensa - Sección de orquestación de subagentes
• Habilidad aprendizaje-continuo - Para patrones que mejoran con el tiempo
• Definiciones de agente incluidas con ECC (ruta de instalación manual: agents/)